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 します。

    • AWSpackages/tkg-clusterclass-aws
    • Azurepackages/tkg-clusterclass-azure
    • vSpherepackages/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