複数のリポジトリからの同期

Config Sync でマルチリポジトリ モードを有効にすると、複数のリポジトリの構成を同じ一連のクラスタに同期できます。マルチリポジトリ モードを使用するには、ルート リポジトリを 1 つ作成する必要があります。また、必要に応じて Namespace リポジトリを作成することもできます。ルート リポジトリはクラスタ スコープと Namespace スコープの構成ファイルを同期でき、通常は管理者によって管理されます。Namespace リポジトリには、複数のクラスタ全体で特定の Namespace に同期される Namespace スコープの構成ファイルが含まれます。こうしたリポジトリ タイプの詳細については、Config Sync の概要のリポジトリ セクションをご覧ください。

各リポジトリには、個別に管理できる Git リファレンス(リポジトリ ブランチ、commit またはタグ、ディレクトリ タプル)が 1 つあります。この構成により、構成ファイルのデプロイ ライフサイクルがチーム別に切り離されます。また、リポジトリを配置する場所の選択と、リポジトリを構成する方法の自由度も高まります。

次の図は、管理者がクラスタを単一のルート リポジトリ(管理者が管理)と複数の Namespace リポジトリ(アプリケーション オペレータが管理)にどのように同期するかの概要を示しています。

複数の構成ファイルを管理する中央管理者と、それぞれが自前の Namespace 構成ファイルを管理するアプリ オペレータ。

前の図では、中央管理者が組織の一元化されたインフラストラクチャを管理し、クラスタと組織内のすべての Namespace にポリシーを適用します。実際のデプロイメントを管理するアプリケーション オペレータは、取り組んでいる Namespace 内のアプリケーションに構成を適用します。

始める前に

マルチ リポジトリ モードを有効にする前に、次の作業を完了しておきます。

  • Git リポジトリを作成するか、Git リポジトリへのアクセス権を取得する。
  • Google Cloud プロジェクトを作成するか、プロジェクトへのアクセス権を取得する。
  • 次の要件を満たす Google Kubernetes Engine(GKE)クラスタを作成するか、クラスタへのアクセス権を取得する。
    • 標準クラスタ。Autopilot クラスタでは、Config Sync はサポートされていません。
    • GKE バージョン 1.18~1.20 を使用する。
    • 4 つ以上の vCPU を備えたマシンタイプを使用するノードプールが 1 つ存在する。
  • Config Sync バージョン 1.5.3 以降を使用する。
  • バージョン 1.7 を使用していて、限定公開クラスタに Config Sync をインストールする場合は、ファイアウォール ルールを追加してポート 8676 を許可します。Config Sync アドミッション Webhook では、ドリフト防止にポート 8676 を使用します。 バージョン 1.8.0 以降、ポートは 10250 に切り替えられ、限定公開クラスタではデフォルトで開いています。

制限事項

マルチリポジトリ モードを使用する場合は、次の制限事項を考慮してください。

ルート リポジトリからの同期の構成

ルート リポジトリからの同期を構成するには、ConfigManagement オブジェクトでマルチリポジトリ モードを有効にして、ルート リポジトリをクラスタに同期する RootSync オブジェクトを作成する必要があります。ルート リポジトリは、クラスタごとに 1 つだけ作成できます。また、ルート リポジトリは、非構造化リポジトリか、階層リポジトリのいずれかになります。

以降のセクションでは、マルチ リポジトリ モードを有効にする 3 つの方法を説明します。

  1. 以前に Config Sync をインストールしていない場合は、新しいルート Git リポジトリ構成を作成します。
  2. 以前に Config Sync をインストールしている場合は、そのルート Git リポジトリ構成を RootSync に移動します。
  3. 以前に Config Sync をインストールしspec.git フィールドを使用する必要がある場合は、ConfigManagement YAML ファイルにルート Git リポジトリの構成を保存します。

1. 新しい構成

Config Sync をまだインストールしていない場合は、次の操作を行ってマルチリポジトリ モードを有効にします。

  1. Config Sync の手動インストールの次のセクションを完了します。

    1. 始める前に
    2. Operator のデプロイ
    3. Operator に Git の読み取り専用アクセス権を付与する
  2. バージョン 1.7 を使用していて、限定公開クラスタに Config Sync をインストールする場合は、ファイアウォール ルールを追加してポート 8676 を許可します。Config Sync アドミッション Webhook では、ドリフト防止にポート 8676 を使用します。 バージョン 1.8.0 以降、ポートは 10250 に切り替えられ、限定公開クラスタではデフォルトで開いています。

  3. config-management.yaml という名前のファイルを作成して、次の YAML ファイルをコピーします。

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      enableMultiRepo: true
    
  4. 変更を適用します。

    kubectl apply -f config-management.yaml
    
  5. RootSync オブジェクトを作成します。

    # root-sync.yaml
    # If you are using a Config Sync version earlier than 1.7.0,
    # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: root-sync
      namespace: config-management-system
    spec:
      sourceFormat: ROOT_FORMAT
      git:
        repo: ROOT_REPOSITORY
        revision: ROOT_REVISION
        branch: ROOT_BRANCH
        dir: "ROOT_DIRECTORY"
        auth: ROOT_AUTH_TYPE
        gcpServiceAccountEmail: ROOT_EMAIL
        secretRef:
          name: ROOT_SECRET_NAME
        # the `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
        noSSLVerify: ROOT_NO_SSL_VERIFY
    

    次のように置き換えます。

    • ROOT_FORMAT: 非構造化リポジトリを使用するには unstructured を追加し、階層型リポジトリを使用するには hierarchy を追加します。この値では大文字と小文字が区別されます。このフィールドは省略可能で、デフォルト値は hierarchy です。unstructured を追加することをおすすめします。この形式では自分にとって最も便利な方法で構成ファイルを整理できます。
    • ROOT_REPOSITORY: ルート リポジトリとして使用する Git リポジトリの URL を記述します。HTTPS または SSH プロトコルを使用する URL を入力できます。たとえば、https://github.com/GoogleCloudPlatform/anthos-config-management-samples では HTTPS プロトコルを使用します。プロトコルを入力しない場合、URL は HTTPS URL として扱われます。このフィールドは必須です。
    • ROOT_REVISION: チェックアウトする Git リビジョン(タグまたはハッシュ)を記述します。このフィールドは省略可能で、デフォルト値は HEAD です。
    • ROOT_BRANCH: 同期元となるリポジトリのブランチを記述します。このフィールドは省略可能で、デフォルト値は master です。
    • ROOT_DIRECTORY: 同期先への構成を含むルート ディレクトリへの Git リポジトリのパスを記述します。このフィールドは省略可能で、デフォルトはリポジトリのルート ディレクトリ(/)です。
    • ROOT_AUTH_TYPE: 次のいずれかの認証タイプを記述します。

      • none: 認証なし
      • ssh: SSH 認証鍵ペアを使用
      • cookiefile: cookiefile を使用
      • token: トークンを使用
      • gcpserviceaccount: Google サービス アカウントを使用して Cloud Source Repositories にアクセス。
      • gcenode: Google サービス アカウントを使用して Cloud Source Repositories にアクセス。このオプションは、Workload Identity がクラスタで有効になっていない場合にのみ、選択してください。

      この認証の種類の詳細については、Config Sync に Git の読み取り専用アクセス権を付与するをご覧ください。

      このフィールドは必須です。

    • ROOT_EMAIL: AUTH_TYPE として gcpserviceaccount を追加した場合は、Google サービス アカウントのメールアドレスを追加します。例: acm@PROJECT_ID.iam.gserviceaccount.com

    • ROOT_SECRET_NAME: Secret の名前を追加します。Secret を使用している場合は、Secret の公開鍵を Git プロバイダに追加する必要があります。このフィールドは省略可能です。

    • ROOT_NO_SSL_VERIFY: SSL 証明書の検証を無効にするには、このフィールドを true に設定します。デフォルト値は false です。

フィールドの説明と、spec フィールドに追加できるフィールドの全一覧については、RootSync フィールドをご覧ください。

  1. 変更を適用します。

    kubectl apply -f root-sync.yaml
    

2. 構成の移動

以前に Config Sync をインストールしている場合は、Git リポジトリ構成を既存の ConfigManagement オブジェクトから RootSync オブジェクトに移動できます。

構成を移動してルート リポジトリを構成する場合は、次の操作を行います。

  1. バージョン 1.7 を使用していて、限定公開クラスタに Config Sync をインストールする場合は、ファイアウォール ルールを追加してポート 8676 を許可します。Config Sync アドミッション Webhook では、ドリフト防止にポート 8676 を使用します。 バージョン 1.8.0 以降、ポートは 10250 に切り替えられ、限定公開クラスタではデフォルトで開いています。
  2. ConfigManagement オブジェクトを開きます。
  3. spec.git フィールドの値をコピーします。これらの値は、RootSync オブジェクトを作成するときに使用します。
  4. ConfigManagement オブジェクトから spec.git フィールド(git: を含む)をすべて削除します。
  5. ConfigManagement オブジェクトの spec.enableMultiRepo フィールドを true に設定します。

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      enableMultiRepo: true
    
  6. 変更を適用します。

    kubectl apply -f config-management.yaml
    
  7. ConfigManagement オブジェクトからコピーした値を使用して、RootSync オブジェクトを作成します。次に例を示します。

    # root-sync.yaml
    # If you are using a Config Sync version earlier than 1.7.0,
    # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: root-sync
      namespace: config-management-system
    spec:
      sourceFormat: ROOT_FORMAT
      git:
        repo: ROOT_REPOSITORY
        revision: ROOT_REVISION
        branch: ROOT_BRANCH
        dir: "ROOT_DIRECTORY"
        auth: ROOT_AUTH_TYPE
        gcpServiceAccountEmail: ROOT_EMAIL
        secretRef:
          name: ROOT_SECRET_NAME
    

    次のように置き換えます。

    • ROOT_FORMAT: 非構造化リポジトリを使用するには unstructured を追加し、階層型リポジトリを使用するには hierarchy を追加します。この値では大文字と小文字が区別されます。このフィールドは省略可能で、デフォルト値は hierarchy です。unstructured を追加することをおすすめします。この形式では自分にとって最も便利な方法で構成ファイルを整理できます。
    • ROOT_REPOSITORY: ルート リポジトリとして使用する Git リポジトリの URL を記述します。HTTPS または SSH プロトコルを使用する URL を入力できます。たとえば、https://github.com/GoogleCloudPlatform/anthos-config-management-samples では HTTPS プロトコルを使用します。プロトコルを入力しない場合、URL は HTTPS URL として扱われます。このフィールドは必須です。
    • ROOT_REVISION: チェックアウトする Git リビジョン(タグまたはハッシュ)を記述します。このフィールドは省略可能で、デフォルト値は HEAD です。
    • ROOT_BRANCH: 同期元となるリポジトリのブランチを記述します。このフィールドは省略可能で、デフォルト値は master です。
    • ROOT_DIRECTORY: 同期先への構成を含むルート ディレクトリへの Git リポジトリのパスを記述します。このフィールドは省略可能で、デフォルトはリポジトリのルート ディレクトリ(/)です。
    • ROOT_AUTH_TYPE: 次のいずれかの認証タイプを記述します。

      • none: 認証なし
      • ssh: SSH 認証鍵ペアを使用
      • cookiefile: cookiefile を使用
      • token: トークンを使用
      • gcpserviceaccount: Google サービス アカウントを使用して Cloud Source Repositories にアクセス。
      • gcenode: Google サービス アカウントを使用して Cloud Source Repositories にアクセス。このオプションは、Workload Identity がクラスタで有効になっていない場合にのみ、選択してください。

      この認証の種類の詳細については、Config Sync に Git の読み取り専用アクセス権を付与するをご覧ください。

      このフィールドは必須です。

    • ROOT_EMAIL: AUTH_TYPE として gcpserviceaccount を追加した場合は、Google サービス アカウントのメールアドレスを追加します。例: acm@PROJECT_ID.iam.gserviceaccount.com

    • ROOT_SECRET_NAME: Secret の名前を追加します。Secret を使用している場合は、Secret の公開鍵を Git プロバイダに追加する必要があります。このフィールドは省略可能です。

  8. 変更を適用します。

    kubectl apply -f root-sync.yaml
    

3. 構成の保持

以前に Config Sync をインストールしている場合は、ConfigManagement オブジェクトに構成した既存のルート Git リポジトリをそのまま保持できます。ただし、この方法は、サポートが終了する予定のためおすすめしません。

ルート リポジトリを ConfigManagement オブジェクトに保持することでルート リポジトリを構成するには、次の操作を行います。

  1. バージョン 1.7 を使用していて、限定公開クラスタに Config Sync をインストールする場合は、ファイアウォール ルールを追加してポート 8676 を許可します。Config Sync アドミッション Webhook では、ドリフト防止にポート 8676 を使用します。 バージョン 1.8.0 以降、ポートは 10250 に切り替えられ、限定公開クラスタではデフォルトで開いています。

  2. ConfigManagement オブジェクトで、spec.enableMultiRepo および spec.enableLegacyFields フィールドを true に設定し、spec.sourceFormatunstructured に設定して非構造化リポジトリを使用するか、hierarchy に設定して階層リポジトリを使用します。この値では大文字と小文字が区別されます。このフィールドは省略可能で、デフォルト値は hierarchy です。unstructured を追加することをおすすめします。この形式では自分にとって最も便利な方法で構成ファイルを整理できます。

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      enableMultiRepo: true
      enableLegacyFields: true
      sourceFormat: FORMAT
      git:
        syncRepo: REPO
        syncBranch: BRANCH
        secretType: TYPE
        policyDir: "DIRECTORY"
    # ...other fields...
    
  3. 変更を適用します。

    kubectl apply -f config-management.yaml
    

config-management.yaml を適用して enableMultiRepo: trueenableLegacyFields: true を設定すると、クラスタに RootSync オブジェクトが自動的に生成されます。生成された RootSync 構成は変更しないでください。

オプションの Namespace リポジトリを追加するには、Namespace リポジトリからの同期の構成セクションに進んでください。1 つのリポジトリからのみ同期して、現在のワークフローを引き続き使用する場合、このセクションは省略できます。

ルート リポジトリの同期ステータスの確認

ルート リポジトリの同期ステータスは、nomos status コマンドを使用して確認できます。

nomos status

出力は次の例のようになります。

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4

RootSync のインストールの確認

RootSync オブジェクトを作成すると、Config Sync によって root-reconciler という調整ツールが作成されます。調整ツールは、Deployment としてデプロイされる Pod です。調整ツールは、Git リポジトリのマニフェストをクラスタに同期します。

RootSync オブジェクトが正しく機能していることは、root-reconciler Deployment のステータスをチェックして確認できます。

kubectl get -n config-management-system deployment/root-reconciler

出力は次の例のようになります。

NAME              READY   UP-TO-DATE   AVAILABLE   AGE
root-reconciler   1/1     1            1           3h42m

RootSync オブジェクトのステータスを確認する別の方法については、RootSync オブジェクトと RepoSync オブジェクトの確認セクションをご覧ください。

Namespace リポジトリからの同期の構成

ルート リポジトリを設定したら、管理者以外のユーザーが管理できる Namespace リポジトリを設定できます。Namespace リポジトリは、非構造化にする必要があります。

Namespace リポジトリを構成するには、権限を割り当てて、Namespace リポジトリをクラスタに同期する RepoSync オブジェクトを作成する必要があります。Namespace リポジトリを構成する方式は、次の 2 つから選択できます。

  • ルート リポジトリ内で Namespace リポジトリを管理する。この方式では、Namespace リポジトリのすべての構成が一元化され、中央管理者が設定を完全に管理できます。

  • Kubernetes API を使用して Namespace リポジトリを管理する。この方式では、Namespace リポジトリの管理を Namespace の所有者に委ねます。

  • 省略可: Namespace リポジトリでアドミッション Webhook を有効にしますドリフト防止を行うための追加手順として Config Sync アドミッション Webhook を有効にする場合は、Namespace リポジトリのアドミッション Webhook を有効にするにある手順を行ってください。

ルート リポジトリでの Namespace リポジトリの管理

この方式では、中央管理者がルート リポジトリから直接 Namespace リポジトリの設定を管理します。Namespace リポジトリのオブジェクトは Config Sync によって管理されるため、この方式では、ローカルで Namespace リポジトリの定義は変更できません。

この方法を使用するには、次の操作を行います。

  1. ルート リポジトリで、namespace 構成を宣言します。

    # ROOT_REPO/namespaces/NAMESPACE/namespace.yaml
    apiVersion: v1
    kind: Namespace
    metadata:
      name: NAMESPACE
    

    NAMESPACE は、Namespace の名前に置き換えます。

  2. ルート リポジトリで、同じ Namespace に RepoSync オブジェクトを作成します。

    # ROOT_REPO/namespaces/NAMESPACE/repo-sync.yaml
     # If you are using a Config Sync version earlier than 1.8.0,
     # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RepoSync
    metadata:
      name: repo-sync
      namespace: NAMESPACE
    spec:
      # Since this is for a namespace repository, the format should be unstructured
      sourceFormat: unstructured
      git:
       repo: NAMESPACE_REPOSITORY
       revision: NAMESPACE_REVISION
       branch: NAMESPACE_BRANCH
       dir: "NAMESPACE_DIRECTORY"
       auth: NAMESPACE_AUTH_TYPE
       gcpServiceAccountEmail: NAMESPACE_EMAIL
       secretRef:
         name: NAMESPACE_SECRET_NAME
       # the `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
       noSSLVerify: NAMESPACE_NO_SSL_VERIFY
    

    次のように置き換えます。

    • NAMESPACE: Namespace の名前を記述します。
    • NAMESPACE_REPOSITORY: Namespace リポジトリとして使用する Git リポジトリの URL を記述します。HTTPS または SSH プロトコルを使用する URL を入力できます。たとえば、https://github.com/GoogleCloudPlatform/anthos-config-management-samples では HTTPS プロトコルを使用します。プロトコルを入力しない場合、URL は HTTPS URL として扱われます。このフィールドは必須です。
    • NAMESPACE_REVISION: チェックアウトする Git リビジョン(タグまたはハッシュ)を記述します。このフィールドは省略可能で、デフォルト値は HEAD です。
    • NAMESPACE_BRANCH: 同期元となるリポジトリのブランチを記述します。このフィールドは省略可能で、デフォルト値は master です。
    • NAMESPACE_DIRECTORY: 同期先への構成を含むルート ディレクトリへの Git リポジトリのパスを記述します。このフィールドは省略可能で、デフォルトはリポジトリのルート ディレクトリ(/)です。
    • NAMESPACE_AUTH_TYPE: 次のいずれかの認証タイプを記述します。

      • none: 認証なし
      • ssh: SSH 認証鍵ペアを使用
      • cookiefile: cookiefile を使用
      • token: トークンを使用
      • gcpserviceaccount: Google サービス アカウントを使用して Cloud Source Repositories にアクセス。
      • gcenode: Google サービス アカウントを使用して Cloud Source Repositories にアクセス。このオプションは、Workload Identity がクラスタで有効になっていない場合にのみ、選択してください。

        この認証の種類の詳細については、Config Sync に Git の読み取り専用アクセス権を付与するをご覧ください。

      このフィールドは必須です。

    • NAMESPACE_EMAIL: AUTH_TYPE として gcpserviceaccount を追加した場合は、Google サービス アカウントのメールアドレスを追加します。例: acm@PROJECT_ID.iam.gserviceaccount.com

    • NAMESPACE_SECRET_NAME: Secret に付ける名前を記述します。このフィールドは省略可能です。

    • NAMESPACE_NO_SSL_VERIFY: SSL 証明書の検証を無効にするには、このフィールドを true に設定します。デフォルト値は false です。

    フィールドの説明と、spec フィールドに追加できるフィールドの全一覧については、RepoSync フィールドをご覧ください。

    1 つの Namespace に存在できる RepoSync オブジェクトは 1 つだけです。この制限を適用するには、オブジェクト namerepo-sync でなければなりません。RepoSync で参照されているディレクトリ内のすべての構成ファイルは、RepoSync オブジェクトと同じ Namespace に存在する必要があります。

  3. ルート リポジトリで、RoleBinding 構成を宣言し、Namespace 内のオブジェクトを管理するための権限を ns-reconciler-NAMESPACE サービス アカウントに付与します。RepoSync 構成がクラスタに同期される際、Config Sync は ns-reconciler-NAMESPACE サービス アカウントを自動的に作成します。

    RoleBinding を宣言するには、次のオブジェクトを作成します。

    # ROOT_REPO/namespaces/NAMESPACE/sync-rolebinding.yaml
     kind: RoleBinding
     apiVersion: rbac.authorization.k8s.io/v1
     metadata:
       name: syncs-repo
       namespace: NAMESPACE
     subjects:
     - kind: ServiceAccount
       name: ns-reconciler-NAMESPACE
       namespace: config-management-system
     roleRef:
       kind: ClusterRole
       name: RECONCILER_ROLE
       apiGroup: rbac.authorization.k8s.io
    

    次のように置き換えます。

    • NAMESPACE: Namespace の名前を記述します。
    • RECONCILER_ROLE: 中央管理者として RECONCILER_ROLE を設定すると、名前空間リポジトリから同期できる構成の種類を指定できます。ロールは、次のいずれかを選択できます。

      • デフォルトの ClusterRole。

        • admin
        • edit

        詳細については、ユーザー向けのロールをご覧ください。

      • ルート リポジトリで宣言されたユーザー定義の ClusterRole または Role。このロールを使用すると、きめ細かい権限を付与できます。

  4. ルート リポジトリに変更を commit します。

     git add .
     git commit -m 'Setting up new namespace repository.'
     git push
    
  5. 必要に応じて、任意の認証方法に基づいて Secret を作成します。認証タイプに none を使用した場合は、このステップはスキップできます。

    Secret は、次の要件を満たす必要があります。

    • Secret は、RepoSync と同じ Namespace に作成します。
    • Secret の名前は、repo-sync.yaml で定義した spec.git.secretRef の名前と一致する必要があります。
    • Secret の公開鍵は、Git プロバイダに追加する必要があります。
  6. 構成を確認するには、Namespace リポジトリのオブジェクトの 1 つに対して kubectl get を使用します。次に例を示します。

    kubectl get rolebindings -n NAMESPACE
    

Kubernetes API を使用した Namespace リポジトリの管理

この方式では、中央管理者がルート リポジトリで Namespace のみを宣言し、RepoSync ファイルの宣言はアプリケーション オペレータに任せます。

中央管理者の仕事

中央管理者は、次の作業を行います。

  1. ルート リポジトリで、namespace 構成を宣言します。

    # ROOT_REPO/namespaces/NAMESPACE/namespace.yaml
     apiVersion: v1
     kind: Namespace
     metadata:
       name: NAMESPACE
    

    NAMESPACE は、Namespace の名前に置き換えます。

  2. ルート リポジトリで RoleBinding を宣言し、アプリケーションのオペレータ権限を付与します。RBAC エスカレーション防止を使用して、アプリケーション オペレータが、このロール バインディングで付与されない権限を持つロール バインディングを適用できないようにします。

    RoleBinding を宣言するには、次のマニフェストを作成します。

    # ROOT_REPO/namespaces/NAMESPACE/operator-rolebinding.yaml
     kind: RoleBinding
     # Add RBAC escalation prevention
     apiVersion: rbac.authorization.k8s.io/v1
     metadata:
       name: operator
       namespace: NAMESPACE
     subjects:
     - kind: User
       name: USERNAME
       apiGroup: rbac.authorization.k8s.io
     roleRef:
       kind: ClusterRole
       name: OPERATOR_ROLE
       apiGroup: rbac.authorization.k8s.io
    

    次のように置き換えます。

    • NAMESPACE: ルート リポジトリで作成した Namespace を記述します。
    • USERNAME: アプリケーション オペレータのユーザー名を記述します。
    • OPERATOR_ROLE: 中央管理者として OPERATOR_ROLE を設定すると、名前空間リポジトリから同期できる構成の種類を指定できます。ロールは、次のいずれかを選択できます。

      • デフォルトの ClusterRole。

        • admin
        • edit

        詳細については、ユーザー向けのロールをご覧ください。

      • ルート リポジトリで宣言されているユーザー定義の ClusterRole またはロール。このロールを使用すると、きめ細かい権限を付与できます。

  3. ルート リポジトリに変更を commit します。

     git add .
     git commit -m 'Setting up new namespace repository.'
     git push
    

アプリケーション オペレータの仕事

アプリケーション オペレータは、次の作業を行います。

  1. RoleBinding 構成を宣言し、Namespace 内のオブジェクトを管理するための権限を ns-reconciler-NAMESPACE サービス アカウントに付与します。RepoSync 構成がクラスタに同期される際、Config Sync は ns-reconciler-NAMESPACE サービス アカウントを自動的に作成します。

    RoleBinding を宣言するには、次のマニフェストを作成します。

    # sync-rolebinding.yaml
    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: syncs-repo
      namespace: NAMESPACE
    subjects:
    - kind: ServiceAccount
      name: ns-reconciler-NAMESPACE
      namespace: config-management-system
    roleRef:
      kind: ClusterRole
      name: RECONCILER_ROLE
      apiGroup: rbac.authorization.k8s.io
    

    次のように置き換えます。

    • NAMESPACE: ルート リポジトリで作成した Namespace を記述します。
    • RECONCILER_ROLE: アプリケーション オペレータとして、RECONCILER_ROLE を設定すると、名前空間リポジトリから同期できる構成の種類を指定できます。中央管理者によって付与された一連の権限は、さらに制限することのみ可能です。そのため、このロールでは、前のセクションで中央管理者が宣言した OPERATOR_ROLE 以上の権限を与えることはできません。
  2. RoleBinding 構成を適用します。

    kubectl apply -f sync-rolebinding.yaml
    
  3. 必要に応じて、任意の認証方法に基づいて Secret を作成します。認証タイプに none を使用した場合は、このステップはスキップできます。

    Secret は、次の要件を満たす必要があります。

    • Secret は、RepoSync と同じ Namespace に作成します。
    • Secret の名前は、root-sync.yaml で定義した spec.git.secretRef の名前と一致する必要があります。
    • Secret の公開鍵は、Git プロバイダに追加する必要があります。
  4. RepoSync 構成を宣言します。

    # repo-sync.yaml
    # If you are using a Config Sync version earlier than 1.8.0,
    # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RepoSync
    metadata:
      name: repo-sync
      namespace: NAMESPACE
    spec:
      # Since this is for a namespace repository, the format should be unstructured
      sourceFormat: unstructured
      git:
       repo: NAMESPACE_REPOSITORY
       revision: NAMESPACE_REVISION
       branch: NAMESPACE_BRANCH
       dir: "NAMESPACE_DIRECTORY"
       auth: NAMESPACE_AUTH_TYPE
       gcpServiceAccountEmail: NAMESPACE_EMAIL
       secretRef:
         name: NAMESPACE_SECRET_NAME
       # the `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
       noSSLVerify: REPO_SSL_VERIFY
    

    次のように置き換えます。

    • NAMESPACE_REPOSITORY: Namespace リポジトリとして使用する Git リポジトリの URL を記述します。HTTPS または SSH プロトコルを使用する URL を入力できます。たとえば、https://github.com/GoogleCloudPlatform/anthos-config-management-samples では HTTPS プロトコルを使用します。プロトコルを入力しない場合、URL は HTTPS URL として扱われます。このフィールドは必須です。
    • NAMESPACE_REVISION: チェックアウトする Git リビジョン(タグまたはハッシュ)を記述します。このフィールドは省略可能で、デフォルト値は HEAD です。
    • NAMESPACE_BRANCH: 同期元となるリポジトリのブランチを記述します。このフィールドは省略可能で、デフォルト値は master です。
    • NAMESPACE_DIRECTORY: 同期先への構成を含むルート ディレクトリへの Git リポジトリのパスを記述します。このフィールドは省略可能で、デフォルトはリポジトリのルート ディレクトリ(/)です。
    • NAMESPACE_AUTH_TYPE: 次のいずれかの認証タイプを記述します。

      • none: 認証なし
      • ssh: SSH 認証鍵ペアを使用
      • cookiefile: cookiefile を使用
      • token: トークンを使用
      • gcpserviceaccount: Google サービス アカウントを使用して Cloud Source Repositories にアクセス。
      • gcenode: Google サービス アカウントを使用して Cloud Source Repositories にアクセス。このオプションは、Workload Identity がクラスタで有効になっていない場合にのみ、選択してください。

        この認証の種類の詳細については、Config Sync に Git の読み取り専用アクセス権を付与するをご覧ください。

      このフィールドは必須です。

    • NAMESPACE_EMAIL: AUTH_TYPE として gcpserviceaccount を追加した場合は、Google サービス アカウントのメールアドレスを追加します。例: acm@PROJECT_ID.iam.gserviceaccount.com

    • NAMESPACE_SECRET_NAME: Secret に付ける名前を記述します。このフィールドは省略可能です。

    • NAMESPACE_NO_SSL_VERIFY: SSL 証明書の検証を無効にするには、このフィールドを true に設定します。デフォルト値は false です。

    フィールドの説明と、spec フィールドに追加できるフィールドの全一覧については、RepoSync フィールドをご覧ください。

    1 つの Namespace に存在できる RepoSync オブジェクトは 1 つだけです。そうするためには、オブジェクトの namerepo-sync にする必要があります。RepoSync で参照されているディレクトリ内のすべての構成ファイルは、RepoSync オブジェクトと同じ Namespace に存在する必要があります。

  5. RepoSync 構成を適用します。

    kubectl apply -f repo-sync.yaml
    
  6. 構成を確認するには、Namespace リポジトリのオブジェクトの 1 つに対して kubectl get を使用します。次に例を示します。

    kubectl get rolebindings -n NAMESPACE
    

Namespace リポジトリの同期ステータスの確認

Namespace リポジトリの同期ステータスは、nomos status コマンドを使用して確認できます。

nomos status

出力は次の例のようになります。

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

この例では、bookstore という Namespace の Namespace リポジトリが構成されています。

RepoSync のインストールの確認

RepoSync オブジェクトを作成すると、Config Sync によって ns-reconciler-NAMESPACE という調整ツールが作成されます。ここで、NAMESPACE は、RepoSync オブジェクトを作成した Namespace です。

RepoSync オブジェクトが正しく機能していることは、ns-reconciler-NAMESPACE Deployment のステータスをチェックして確認できます。

kubectl get -n config-management-system deployment/ns-reconciler-NAMESPACE

NAMESPACE は、Namespace リポジトリを作成した Namespace に置き換えます。

RepoSync オブジェクトのステータスを確認する別の方法については、RootSync オブジェクトと RepoSync オブジェクトの確認セクションをご覧ください。

構成ファイルのドリフトの防止

Config Sync では、ドリフト検出によって「シャドウ オペレーション」のリスクを軽減できます。十分に検証されていない変更がライブクラスタに push されると、Config Sync は Git の信頼できるソースからのドリフトを検出して修正します。さらに、Config Sync のマルチリポジトリ モードでは、1.7.0 以降、競合する変更が使用中のクラスタに push されることを拒否するアドミッション Webhook を備えています。これにより、マニュアルで変更が試みられたときユーザーに通知せずに変更を修正することよりも、ユーザーへのフィードバックの質が向上します。

さらに、このアドミッション Webhook は、アドミッション Webhook や調整ツールの構成でエラーの原因となる、Config Sync のメタデータとアノテーションの手動による変更を防ぎます。

Namespace リポジトリでアドミッション Webhook を有効にする

競合する変更がライブクラスタに push されないようにするアドミッション Webhook は、Config Sync がマルチリポジトリ モードで構成されている場合にのみインストールされます。デフォルトでは、Webhook はルート リポジトリのみを保護します。各 Namespace リポジトリの Config Sync Reconciler には、クラスタレベルで ValidatingWebhookConfiguration オブジェクトの読み取りまたは更新を行う権限がないため、Namespace リポジトリは Webhook で保護されません。

この権限がないと、Namespace Reconciler のログに次のようなエラーが記録されます。

  Failed to update admission webhook: KNV2013: applying changes to admission webhook: Insufficient permission. To fix, make sure the reconciler has sufficient permissions.: validatingwebhookconfigurations.admissionregistration.k8s.io "admission-webhook.configsync.gke.io" is forbidden: User "system:serviceaccount:config-management-system:ns-reconciler-NAMESPACE" cannot update resource "validatingwebhookconfigurations" in API group "admissionregistration.k8s.io" at the cluster scope

Namespace リポジトリに Webhook 保護が必要ない場合、このエラーは無視できます。この保護を追加する場合は、次の手順を行い、この権限を各 Namespace リポジトリの Reconciler に付与します。

この方法を使用するには、次の操作を行います。

  1. ルート リポジトリで、Config Sync アドミッション Webhook に権限を付与するために使用される新しい ClusterRole 構成を宣言します。この ClusterRole は、クラスタごとに 1 回だけ定義する必要があります。

    # ROOT_REPO/cluster-roles/webhook-role.yaml
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: admission-webhook-role
    rules:
    - apiGroups: ["admissionregistration.k8s.io"]
      resources: ["validatingwebhookconfigurations"]
      resourceNames: ["admission-webhook.configsync.gke.io"]
      verbs: ["get", "update"]
    
  2. アドミッション Webhook 権限を付与する必要がある Namespace リポジトリごとに ClusterRoleBinding 構成を宣言して、アドミッション Webhook へのアクセス権を付与します。

    # ROOT_REPO/NAMESPACE/sync-webhook-rolebinding.yaml
    kind: ClusterRoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: syncs-webhook
    subjects:
    - kind: ServiceAccount
      name: ns-reconciler-NAMESPACE
      namespace: config-management-system
    roleRef:
      kind: ClusterRole
      name: admission-webhook-role
      apiGroup: rbac.authorization.k8s.io
    

    NAMESPACE は、Namespace の名前に置き換えます。

  3. ルート リポジトリに変更を commit します。

    git add .
    git commit -m 'Providing namespace repository the permission to update the admission webhook.'
    git push
    
    
  4. kubectl を使用して ClusterRole と ClusterRoleBinding が作成されていることを確認します。

    kubectl get clusterrole admission-webhook-role
    kubectl get clusterrolebindings syncs-webhook
    

同期の停止と再開

複数のリポジトリからの同期を停止する方法については、複数のリポジトリからの同期の停止と再開をご覧ください。

ルート リポジトリと Namespace リポジトリを削除する

名前空間リポジトリを削除する

[ルート リポジトリのメソッド] または [Kubernetes API メソッド] タブを選択し、関連する手順を表示します。

ルート リポジトリ方式

ルート リポジトリで名前空間リポジトリを制御する方法を使用した場合、中央管理者は次の 2 つの手順で名前空間リポジトリを削除できます。

  1. トラブルシューティングの指示に従って、RepoSync オブジェクトによって管理されているリソースを管理対象外にするか削除します。

  2. Git リポジトリから RepoSync オブジェクトを削除します。

Kubernetes API 方式

Kubernetes API で名前空間リポジトリを制御する方法を使用すると、アプリケーション オペレータは次の 2 つの手順で名前空間リポジトリを削除できます。

  1. トラブルシューティングの指示に従って、RepoSync オブジェクトによって管理されているリソースを管理対象外にするか削除します。

  2. RepoSync オブジェクトを削除するには、次のコマンドを実行します。

    kubectl delete -f repo-sync.yaml
    

ルート リポジトリの削除

中央管理者は、次の 2 つの手順でルート リポジトリを削除できます。

  1. トラブルシューティングの指示に従って、RootSync オブジェクトによって管理されているリソースを管理対象外にするか削除します。

  2. RootSync オブジェクトを削除するには、次のコマンドを実行します。

     kubectl delete -f root-sync.yaml
    

オブジェクトのミューテーションを無視する

Config Sync バージョン 1.7.0 以降で、背後にクラスタが存在するオブジェクトの状態を Config Sync が維持しないようにするには、Config Sync がミューテーションを無視するように client.lifecycle.config.k8s.io/mutation: ignore アノテーションをオブジェクトに追加します。この操作は、Config Sync でオブジェクトを作成した後、クラスタ内でそのオブジェクトに対して競合する変更をすべて無視する場合に有用です。

そのアノテーションをオブジェクトに追加する方法を、次の例に示します。

metadata:
  annotations:
    client.lifecycle.config.k8s.io/mutation: ignore 

クラスタのマネージド オブジェクトでは、このアノテーションは手動で変更できません。

競合の解決

2 つのリポジトリを使用する場合、ルート リポジトリと Namespace リポジトリの両方で同じオブジェクト(一致するグループ、種類、名前、Namespace)が宣言されると、競合が発生します。この競合が発生すると、ルート リポジトリの宣言のみがクラスタに適用されます。

この競合が発生した場合、ルート リポジトリが優先されるため、RootSync からは問題が報告されません。RepoSync は、そのステータスでエラー KNV 1060 を報告します。

ルート リポジトリは常に優先されるため、競合を解決するには、ルート リポジトリを Namespace リポジトリと一致するように更新するか、競合するオブジェクトを Namespace リポジトリから削除してください。

RootSync オブジェクトと RepoSync オブジェクトの確認

以降のセクションでは、RootSync オブジェクトと RepoSync オブジェクトの詳細を調べる複数の方法について説明します。

ログの表示

潜在的なエラーの詳細に関しては、RootSync オブジェクトと RepoSync オブジェクトのログを表示できます。

RootSync 調整ツールのログを表示するには、次のコマンドを実行します。

kubectl logs -n config-management-system deployment/root-reconciler CONTAINER_NAME

CONTAINER_NAME は、git-syncreconciler、または otel-agent に置き換えます。git-sync コンテナは、構成ファイルを、Git リポジトリから調整ツールコンテナが読み取り可能なローカル ディレクトリに pull します。reconciler コンテナは、それらの構成ファイルをクラスタに適用します。otel-agent コンテナは、Config Sync の指標の取得とエクスポートを行う OpenTelemetry エージェントです。

RepoSync 調整ツールのログを表示するには、次のコマンドを実行します。

kubectl logs -n config-management-system deployment/ns-reconciler-NAMESPACE CONTAINER_NAME

次のように置き換えます。

  • NAMESPACE: Namespace リポジトリを作成した Namespace。
  • CONTAINER_NAME: git-syncreconcilerotel-agent のいずれか。

同期した commit の表示

クラスタと同期した commit を確認できます。

RootSync の詳細を表示するには、次のコマンドを実行します。

kubectl get rootsync root-sync -n config-management-system

RepoSync の詳細を表示するには、次のコマンドを実行します。

kubectl get reposync repo-sync -n config-management-system

出力は次の例のようになります。

NAME        SOURCECOMMIT                               SYNCCOMMIT
root-sync   66882815f0ef5517df27e864fb1315e97756ab72   66882815f0ef5517df27e864fb1315e97756ab72

SOURCECOMMIT 列の値は、クラスタと同期する必要がある Git リポジトリからの commit です。SYNCCOMMIT 列の値は、現在クラスタにデプロイされている commit です。SOURCECOMMIT 列と SYNCCOMMIT 列の 2 つの値が同じ場合は、想定された commit がクラスタにデプロイ済みです。

オブジェクトの詳細の表示

RootSync オブジェクトと RepoSync オブジェクトの詳細を表示するには、kubectl describe を使用します。このコマンドにより、潜在的なエラーに関する詳細情報が提供されます。

RootSync オブジェクトの詳細を表示するには、次のコマンドを実行します。

kubectl describe rootsync root-sync -n config-management-system

RepoSync オブジェクトの詳細を表示するには、次のコマンドを実行します。

kubectl describe reposync repo-sync -n config-management-system

リソースの準備状況の表示

クラスタに同期されたリソースの準備状況を確認するには、調整ステータスを表示します。たとえば、このコマンドにより、同期された Deployment でトラフィックを処理できるかどうかを確認できます。

クラスタと同期された Git リポジトリの場合は、すべてのリソースの調整ステータスが ResourceGroup というリソースに集約されます。RootSync オブジェクトや RepoSync オブジェクトごとに ResourceGroup が生成され、クラスタに適用される一連のリソースを取り込んで、それらのステータスを集約します。

RootSync オブジェクトの調整ステータスを表示するには、次のコマンドを実行します。

kubectl get resourcegroup.kpt.dev root-sync -n config-management-system -o yaml

RepoSync オブジェクトの調整ステータスを表示するには、次のコマンドを実行します。

kubectl get resourcegroup.kpt.dev repo-sync -n NAMESPACE -o yaml

出力には、ResourceGroup のすべてのリソースのステータスが表示されます。たとえば、次の出力は、nginx-deployment という名前の Deployment の準備ができていることを示しています。

resourceStatuses:
- group: apps
  kind: Deployment
  name: nginx-deployment
  namespace: default
  status: Current

次のステップ