ClusterClass の作成

このトピックでは、Tanzu Kubernetes Grid (TKG) スタンドアローン管理クラスタでクラスベースのワークロード クラスタを作成するためのベースとして使用できる、独自のカスタム ClusterClass リソース定義を作成する方法について説明します。ClusterClass をクラスタのベースにするには、その spec.topology.class を ClusterClass 名に設定します。

この手順は、vSphere with Tanzu スーパーバイザーを使用する TKG には適用されません。

重要

カスタム ClusterClass リソース定義の作成は、上級ユーザー向けです。VMware は、任意の ClusterClass オブジェクトに基づくワークロード クラスタの機能は保証しません。デフォルトの ClusterClass リソースを使用してワークロード クラスタを作成するには、「クラスタ展開の手順」に記載の手順に従います。

要件

ClusterClass 定義を作成するには、次のツールがローカルにインストールされている必要があります。
ツール バージョン
clusterctl v1.2.0
ytt 0.42.0
Jq 1.5-1
yq v4.30.5

オプション：オーバーレイと新しいオブジェクト仕様

新しい ClusterClass を作成するには、ClusterClass オブジェクト ソースでリンクされている既存のデフォルトの ClusterClass オブジェクトから開始し、ytt オーバーレイで変更することをお勧めします。デフォルトの ClusterClass オブジェクトの新しいバージョンが公開されたら、同じカスタマイズを実装するためにオーバーレイを新しいバージョンに適用できます。次に示す手順では、カスタム ClusterClass オブジェクトを作成するこの方法について説明します。

新しい ClusterClass オブジェクトをゼロから記述する場合は、クラスタ API ドキュメントの「Writing a ClusterClass」の説明に従います。

カスタム ClusterClass オブジェクトの作成

Tanzu Framework リポジトリで定義されている既存の ClusterClass に基づいてカスタム ClusterClass オブジェクト定義を作成するには、次の手順を実行します。

ClusterClass オブジェクト ソースの取得

  1. Github の Tanzu Framework コード リポジトリから、v0.28.1 zip バンドルをダウンロードして展開します。

  2. ターゲット インフラストラクチャに応じて、リポジトリの package サブディレクトリに cd します。

    • AWS：packages/tkg-clusterclass-aws
    • Azure：packages/tkg-clusterclass-azure
    • vSphere：packages/tkg-clusterclass-vsphere

  3. bundle フォルダをワークスペースにコピーします。構造は次のようになります。

    $ tree bundle
bundle
|-- config
   |-- upstream
   │   |-- base.yaml
   │   |-- overlay-kube-apiserver-admission.yaml
   │   |-- overlay.yaml
   |-- values.yaml

ベース ClusterClass マニフェストの生成

  1. スタンドアローン管理クラスタをすでに展開しているかどうかに応じて、次のように値ファイルにインフラストラクチャ設定をキャプチャします。

    • 管理クラスタが展開されている場合：次のコマンドを実行して、default-values.yaml を生成します。

      cat <<EOF > default_values.yaml
#@data/values

#@overlay/match-child-defaults missing_ok=True
---
EOF
kubectl get secret tkg-clusterclass-infra-values -o jsonpath='{.data.values\.yaml}' -n tkg-system | base64 -d >> default_values.yaml

    • スタンドアローン管理クラスタが展開されていない場合：

      1. bundle ディレクトリで、values.yaml を新しいファイル default_values.yaml にコピーします。
      cp bundle/config/values.yaml default_values.yaml
      1. インフラストラクチャに応じて、次のように、default_values.yaml を編集して変数設定を入力します。
      VSPHERE_DATACENTER: /dc0
VSPHERE_DATASTORE: /dc0/datastore/sharedVmfs-0
VSPHERE_FOLDER: /dc0/vm

      インフラストラクチャ固有の変数については、「構成ファイル変数リファレンス」を参照してください。

  2. 値ファイルからベースの ClusterClass マニフェストを生成します。

    ytt -f bundle -f default_values.yaml > default_cc.yaml

ClusterClass マニフェストのカスタマイズ

ClusterClass マニフェストをカスタマイズするには、マニフェストと一緒に ytt オーバーレイ ファイルを作成します。次の例は、ClusterClass 定義で Linux カーネル パラメータを変更する方法を示しています。

  1. 次のように、custom フォルダを作成します。

    $ tree custom
 custom
 |-- overlays
 |   -- kernels.yaml
 -- values.yaml

  2. たとえば、custom/overlays/kernels.yaml を編集して nfConntrackMax を変数として追加し、その値を制御プレーン ノードのカーネル パラメータ net.netfilter.nf_conntrack_max に追加するパッチを定義します。

    このオーバーレイは、preKubeadmCommands フィールドにコマンドを追加して、構成を sysctl.conf に書き込みます。この設定を有効にするには、コマンド sysctl -p を追加してこの変更を適用できます。

    #@ load("@ytt:overlay", "overlay")
#@ load("@ytt:data", "data")

#@overlay/match by=overlay.subset({"kind":"ClusterClass"})
---
apiVersion: cluster.x-k8s.io/v1beta1
kind: ClusterClass
spec:
  variables:
  - name: nfConntrackMax
    required: false
    schema:
      openAPIV3Schema:
        type: string
  patches:
  - name: nfConntrackMax
    enabledIf: '{{ not (empty .nfConntrackMax) }}'
    definitions:
      - selector:
          apiVersion: controlplane.cluster.x-k8s.io/v1beta1
          kind: KubeadmControlPlaneTemplate
          matchResources:
            controlPlane: true
        jsonPatches:
          - op: add
            path: /spec/template/spec/kubeadmConfigSpec/preKubeadmCommands/-
            valueFrom:
              template: echo "net.netfilter.nf_conntrack_max={{ .nfConntrackMax }}" >> /etc/sysctl.conf

  3. デフォルトの ClusterClass 定義は変更できないため、custom/values.yaml オーバーレイを作成または編集し、-extended とバージョンを追加して、カスタム ClusterClass とそのすべてのテンプレートの名前を変更します。次に例を示します。

    #@data/values

#@overlay/match-child-defaults missing_ok=True
---
#! Change the suffix so we know from which default ClusterClass it is extended
CC-VERSION: extended-v1.0.0

#! Add other variables below if necessary

    ここで、CC-VERSION はクラスタ クラス バージョンの名前です（例：VSPHERE_CLUSTER_CLASS_VERSION）。

  4. カスタム ClusterClass を生成します。

    ytt -f bundle -f default_values.yaml -f custom > custom_cc.yaml

  5. （オプション）デフォルト ClusterClass とカスタム ClusterClass の違いを確認して、すべての名前のサフィックスが -extended であり、新しい変数や JSON パッチが追加されていることを確認します。

    $ diff default_cc.yaml custom_cc.yaml
4c4
<   name: tkg-vsphere-default-v1.0.0-cluster
---
>   name: tkg-vsphere-default-extended-v1.0.0-cluster
15c15
<   name: tkg-vsphere-default-v1.0.0-control-plane
---
>   name: tkg-vsphere-default-extended-v1.0.0-control-plane
39c39
<   name: tkg-vsphere-default-v1.0.0-worker
---
>   name: tkg-vsphere-default-extended-v1.0.0-worker
63c63
<   name: tkg-vsphere-default-v1.0.0-kcp
---
>   name: tkg-vsphere-default-extended-v1.0.0-kcp
129c129
<   name: tkg-vsphere-default-v1.0.0-md-config
---
>   name: tkg-vsphere-default-extended-v1.0.0-md-config
165c165
<   name: tkg-vsphere-default-v1.0.0
---
>   name: tkg-vsphere-default-extended-v1.0.0
174c174
<       name: tkg-vsphere-default-v1.0.0-kcp
---
>       name: tkg-vsphere-default-extended-v1.0.0-kcp
180c180
<         name: tkg-vsphere-default-v1.0.0-control-plane
---
>         name: tkg-vsphere-default-extended-v1.0.0-control-plane
195c195
<       name: tkg-vsphere-default-v1.0.0-cluster
---
>       name: tkg-vsphere-default-extended-v1.0.0-cluster
205c205
<             name: tkg-vsphere-default-v1.0.0-md-config
---
>             name: tkg-vsphere-default-extended-v1.0.0-md-config
211c211
<             name: tkg-vsphere-default-v1.0.0-worker
---
>             name: tkg-vsphere-default-extended-v1.0.0-worker
228c228
<             name: tkg-vsphere-default-v1.0.0-md-config
---
>             name: tkg-vsphere-default-extended-v1.0.0-md-config
234c234
<             name: tkg-vsphere-default-v1.0.0-worker
---
>             name: tkg-vsphere-default-extended-v1.0.0-worker
537a538,542
>   - name: nfConntrackMax
>     required: false
>     schema:
>       openAPIV3Schema:
>         type: string
1807a1813,1825
>   - name: nfConntrackMax
>     enabledIf: '{{ not (empty .nfConntrackMax) }}'
>     definitions:
>     - selector:
>         apiVersion: controlplane.cluster.x-k8s.io/v1beta1
>         kind: KubeadmControlPlaneTemplate
>         matchResources:
>           controlPlane: true
>       jsonPatches:
>       - op: add
>         path: /spec/template/spec/kubeadmConfigSpec/preKubeadmCommands/-
>         valueFrom:
>           template: echo "net.netfilter.nf_conntrack_max={{ .nfConntrackMax }}" >> /etc/sysctl.conf

管理クラスタへの ClusterClass のインストール

管理クラスタでカスタム ClusterClass を使用できるようにするには、次のようにインストールします。

  1. 次のように ClusterClass マニフェストを適用します。

    $ kubectl apply -f custom_cc.yaml
vsphereclustertemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-cluster created
vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-control-plane created
vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-worker created
kubeadmcontrolplanetemplate.controlplane.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-kcp created
kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-md-config created
clusterclass.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0 created

  2. カスタム ClusterClass がデフォルトの名前空間に伝達されているかどうかを確認します。次に例を示します。

    $ kubectl get clusterclass,kubeadmconfigtemplate,kubeadmcontrolplanetemplate,vspheremachinetemplate,vsphereclustertemplate
NAME                                                                AGE
clusterclass.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0   3m16s
clusterclass.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0            2d18h

NAME                                                                                             AGE
kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-md-config   3m29s
kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-md-config            2d18h

NAME                                                                                                AGE
kubeadmcontrolplanetemplate.controlplane.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-kcp   3m27s
kubeadmcontrolplanetemplate.controlplane.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-kcp            2d18h

NAME                                                                                                       AGE
vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-control-plane   3m31s
vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-worker          3m28s
vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-control-plane            2d18h
vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-worker                   2d18h

NAME                                                                                                 AGE
vsphereclustertemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-cluster   3m31s
vsphereclustertemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-cluster            2d18h

カスタム ワークロード クラスタ マニフェストの生成

次のように、カスタム ClusterClass に基づいて新しいワークロード クラスタを作成します。

  1. --dry-run オプションを指定して tanzu cluster create を実行し、クラスタ マニフェストを生成します。

    tanzu cluster create --file workload-1.yaml --dry-run > default_cluster.yaml

  2. ytt オーバーレイを作成するか、クラスタ マニフェストを直接編集して次の操作を行います。

    • topology.class 値をカスタム ClusterClass の名前に置き換えます。
    • デフォルト値を使用して、カスタム変数を variables ブロックに追加します。

    ClusterClass オブジェクト仕様の変更と同様に、次のようにオーバーレイを使用すると、新しいアップストリーム クラスタ リリースが発生するたびに、変更を新しいオブジェクトに自動的に適用できます。

    #@ load("@ytt:overlay", "overlay")

#@overlay/match by=overlay.subset({"kind":"Cluster"})
---
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
spec:
  topology:
    class: tkg-vsphere-default-extended-v1.0.0
    variables:
    - name: nfConntrackMax
      value: "1048576"

  3. マニフェストを生成します。

    ytt -f default_cluster.yaml -f cluster_overlay.yaml > custom_cluster.yaml

  4. （オプション）前述の ClusterClass と同様に、diff を実行して、カスタムクラス クラスタ マニフェストをデフォルトのクラスベースのクラスタと比較できます。次に例を示します。

    $ diff custom_cluster.yaml default_cluster.yaml
142c142
<     class: tkg-vsphere-default-extended-v1.0.0
---
>     class: tkg-vsphere-default-v1.0.0
185,186d184
<     - name: nfConntrackMax
<       value: "1048576"

（オプション）クラスタ作成のドライラン

このオプションの手順では、カスタム ClusterClass が生成および管理するリソースを示します。

  1. custom_cluster.yaml のコピーを作成します。

    cp custom_cluster.yaml dryrun_cluster.yaml

  2. 変数 TKR_DATA を管理クラスタからコピーします。

    kubectl get cluster mgmt -n tkg-system -o jsonpath='{.spec.topology.variables}' | jq -r '.[] | select(.name == "TKR_DATA")' | yq -p json '.'

  3. この出力を dryrun_cluster.yaml の .spec.topology.variables に手動で追加します。たとえば、次の diff 出力のようになります。

    $ diff custom_cluster.yaml dryrun_cluster.yaml
186a187,214
>     - name: TKR_DATA
>       value:
>         v1.24.10+vmware.1:
>           kubernetesSpec:
>             coredns:
>               imageTag: v1.8.6_vmware.12
>             etcd:
>               imageTag: v3.5.4_vmware.10
>             imageRepository: projects.registry.vmware.com/tkg
>             kube-vip:
>               imageRepository: projects-stg.registry.vmware.com/tkg
>               imageTag: v0.5.5_vmware.1
>             pause:
>               imageTag: "3.7"
>             version: v1.24.10+vmware.1
>           labels:
>             image-type: ova
>             os-arch: amd64
>             os-name: photon
>             os-type: linux
>             os-version: "3"
>             ova-version: v1.24.10+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
>             run.tanzu.vmware.com/os-image: v1.24.10---vmware.1-tkg.1-efe12079f22627aa1246398eba077476
>             run.tanzu.vmware.com/tkr: v1.24.10---vmware.1-tkg.1-zshippable
>           osImageRef:
>             moid: vm-156
>             template: /dc0/vm/photon-3-kube-v1.24.10+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
>             version: v1.24.10+vmware.1-tkg.1-efe12079f22627aa1246398eba077476

  4. plan ディレクトリの作成：

    mkdir plan

  5. クラスタの作成をドライランします。次に例を示します。

    $ clusterctl alpha topology plan -f dryrun_cluster.yaml -o plan
Detected a cluster with Cluster API installed. Will use it to fetch missing objects.
No ClusterClasses will be affected by the changes.
The following Clusters will be affected by the changes:
＊ default/workload-1

Changes for Cluster "default/workload-1":

 NAMESPACE  KIND                    NAME                             ACTION
 default    KubeadmConfigTemplate   workload-1-md-0-bootstrap-lvchb  created
 default    KubeadmControlPlane     workload-1-2zmql                 created
 default    MachineDeployment       workload-1-md-0-hlr7c            created
 default    MachineHealthCheck      workload-1-2zmql                 created
 default    MachineHealthCheck      workload-1-md-0-hlr7c            created
 default    Secret                  workload-1-shim                  created
 default    VSphereCluster          workload-1-fmt2j                 created
 default    VSphereMachineTemplate  workload-1-control-plane-mf6k6   created
 default    VSphereMachineTemplate  workload-1-md-0-infra-k88bk      created
 default    Cluster                 workload-1                       modified

Created objects are written to directory "plan/created"
Modified objects are written to directory "plan/modified"

  6. 次のファイルが生成され、KubeadmControlPlane_default_workload-1-2zmql.yaml でカーネル構成が見つかります。

    $ tree plan
plan
|-- created
|   |-- KubeadmConfigTemplate_default_workload-1-md-0-bootstrap-lvchb.yaml
|   |-- KubeadmControlPlane_default_workload-1-2zmql.yaml
|   |-- MachineDeployment_default_workload-1-md-0-hlr7c.yaml
|   |-- MachineHealthCheck_default_workload-1-2zmql.yaml
|   |-- MachineHealthCheck_default_workload-1-md-0-hlr7c.yaml
|   |-- Secret_default_workload-1-shim.yaml
|   |-- VSphereCluster_default_workload-1-fmt2j.yaml
|   |-- VSphereMachineTemplate_default_workload-1-control-plane-mf6k6.yaml
|   `-- VSphereMachineTemplate_default_workload-1-md-0-infra-k88bk.yaml
`-- modified
   |-- Cluster_default_workload-1.diff
   |-- Cluster_default_workload-1.jsonpatch
   |-- Cluster_default_workload-1.modified.yaml
   `-- Cluster_default_workload-1.original.yaml

2 directories, 13 files

    カスタム ClusterClass に変更を加えるたびに、上記のようにリソースを比較する必要があります。

カスタム クラスタの作成

前述の生成されたカスタム マニフェストに基づいて、次のようにカスタム ワークロード クラスタを作成します。

  1. 上記で生成されたカスタムクラス クラスタ マニフェストを適用します。次に例を示します。

    $ kubectl apply -f custom_cluster.yaml
secret/workload-1-vsphere-credential created
secret/workload-1-nsxt-credential created
vspherecpiconfig.cpi.tanzu.vmware.com/workload-1 created
vspherecsiconfig.csi.tanzu.vmware.com/workload-1 created
clusterbootstrap.run.tanzu.vmware.com/workload-1 created
secret/workload-1 created
cluster.cluster.x-k8s.io/workload-1 created
    注意

    変数 TKR_DATA は TKG Webhook によって挿入されるため、マニフェストの生成に使用された dryrun_cluster.yaml の適用は使用しないでください。

  2. 作成されたオブジェクト プロパティを確認します。たとえば、前述のカーネル変更を行った場合は、KubeadmControlPlane オブジェクトを取得し、カーネル構成が設定されていることを確認します。

    $ kubectl get kcp workload-1-jgwd9 -o yaml
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
kind: KubeadmControlPlane
...
   preKubeadmCommands:
   - hostname "{{ ds.meta_data.hostname }}"
   - echo "::1         ipv6-localhost ipv6-loopback" >/etc/hosts
   - echo "127.0.0.1   localhost" >>/etc/hosts
   - echo "127.0.0.1   {{ ds.meta_data.hostname }}" >>/etc/hosts
   - echo "{{ ds.meta_data.hostname }}" >/etc/hostname
   - echo "net.netfilter.nf_conntrack_max=1048576" >> /etc/sysctl.conf
   useExperimentalRetryJoin: true
...

  3. 制御プレーン ノードにログインし、その sysctl.conf が変更されていることを確認します。

    $ capv@workload-1-cn779-pthp5
[ ~ ]$ sudo cat /etc/sysctl.conf
...
net.ipv4.ip_forward=1
net.ipv4.tcp_timestamps=1
net.netfilter.nf_conntrack_max=1048576
check-circle-line exclamation-circle-line close-line
Scroll to top icon