kubectl を使用して Config Sync を手動でインストールする（非推奨）

このページでは、kubectl コマンドを使用して Config Sync をインストールする方法について説明します。Config Management Operator は、Kubernetes クラスタ内の Config Sync を管理するコントローラです。Config Sync を使用して管理する各クラスタで Operator をインストールして構成するには、次の手順を行います。

準備

このセクションでは、kubectl を使用して Config Sync をインストールする場合の前提条件について説明します。

ローカルの環境を準備する

Operator をインストールする前に、次の作業を行い、ローカル環境を準備してください。

  • 信頼できる情報源を作成するか、信頼できる情報源へのアクセス権を取得します。

  • この手順で使用する gcloud、gsutil、kubectl、nomos コマンドを含む Google Cloud CLI をインストールして初期化します。Cloud Shell を使用する場合、Google Cloud CLI がプリインストールされています。

  • kubectl は、デフォルトでは Google Cloud CLI によってインストールされません。kubectl をインストールするには、次のコマンドを使用します。

    gcloud components install kubectl

  • Config Sync のコンポーネントをダウンロードできるように、gcloud auth login コマンドを使用して Google Cloud に対する認証を行います。

クラスタを準備する

Config Sync の要件を満たす GKE クラスタを作成するか、該当するクラスタへのアクセス権を取得します。

権限を準備する

Config Sync をインストールする Google Cloud ユーザーには、クラスタに新しいロールを作成するための IAM 権限が必要です。必要であれば、次のコマンドを使用して、これらのロールを付与してください。

gcloud container clusters get-credentials CLUSTER_NAME

kubectl create clusterrolebinding cluster-admin-binding \
    --clusterrole cluster-admin --user USER_ACCOUNT

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

  • CLUSTER_NAME: クラスタ名
  • USER_ACCOUNT: Google Cloud アカウントのメールアドレス

ローカル システムでの Google Cloud CLI の構成方法によっては、--project フィールドと --zone フィールドを追加する必要があります。

認証タイプとして gcpserviceaccount を使用して OCI へのアクセス権を Operator に付与する必要がある場合は、ポリシー バインディングを作成するために iam.serviceAccounts.setIamPolicy 権限が必要になります。この権限は、サービス アカウント管理者（roles/iam.serviceAccountAdmin）に IAM ロールを付与することで取得できます。カスタムロールや他の事前定義ロールを使用して、この権限を取得することもできます。

ロールの付与の詳細については、アクセスの管理をご覧ください。

クラスタを登録する

Config Sync でクラスタを登録するには、次の手順を行います。

  1. Operator をデプロイする
  2. 次のいずれかへの読み取り専用権限を Operator に付与します。
  3. Operator を構成する

Operator をデプロイする

すべての前提条件を満たしていることを確認したら、YAML マニフェストをダウンロードして適用し、Operator をデプロイします。

  1. 次のコマンドを使用して、Operator マニフェストの最新バージョンをダウンロードします。特定のバージョンをダウンロードするには、ダウンロードをご覧ください。

    gsutil cp gs://config-management-release/released/latest/config-management-operator.yaml config-management-operator.yaml

  2. マニフェストを適用します。

    kubectl apply -f config-management-operator.yaml

YAML または JSON 構文エラーに起因しない ConfigManagement オブジェクトの問題によって失敗する場合、オブジェクトはクラスタでインスタンス化される場合もありますが、正しく動作しない可能性があります。この場合、nomos status コマンドを使用してオブジェクトのエラーを確認できます。

問題のない有効なインストールのステータスは PENDING または SYNCED です。

無効なインストールのステータスは NOT CONFIGURED であり、次のいずれかのエラーが表示されます。

  • missing git-creds Secret
  • missing required syncRepo field
  • git-creds Secret is missing the key specified by secretType

問題を解決するには、構成エラーを修正してください。エラーのタイプに応じて、ConfigManagement マニフェストをクラスタに再適用する必要があります。

ユーザーが git-creds Secret の作成を失念したために問題が発生した場合は、Secret を作成すると Config Sync によって即時に検出されるため、構成を再適用する必要はありません。

Operator に読み取り専用アクセス権を付与する

構成ファイルを Git に保存する場合は、Operator に Git への読み取り専用アクセス権を付与する必要があります。構成ファイルを OCI イメージとして保存する場合は、Operator に OCI への読み取り専用アクセス権を付与する必要があります。構成ファイルを Helm に保存する場合は、Operator に Helm への読み取り専用アクセス権を付与する必要があります。

Operator に Git への読み取り専用アクセス権を付与する

Config Sync には、Git リポジトリに対する読み取り専用権限が必要です。この権限により、Config Sync はリポジトリに commit された構成ファイルを読み取り、クラスタに適用できるようになります。

読み取り専用アクセスに対してリポジトリによる認証が不要な場合は、引き続き Config Sync を構成し、認証タイプとして none を使用できます。たとえば、ログインせずにウェブ インターフェースでリポジトリを参照できる場合は認証の必要はありません。また、認証情報を指定することや、保存済みの認証情報を使用することなく、git clone を使用してリポジトリのクローンをローカルに作成できる場合も認証は不要です。この場合、Secret を作成する必要はありません。

ただし、ほとんどのユーザーは、リポジトリへの読み取りアクセスが制限されているため、認証情報を作成する必要があります。認証情報が必要な場合は、登録された各クラスタの git-creds Secret に認証情報が保存されています（Google サービス アカウントを使用している場合を除く）。Secret は固定値であるため、git-creds という名前にする必要があります。

Config Sync は、次の認証メカニズムをサポートしています。

  • SSH 認証鍵ペア
  • cookiefile
  • トークン
  • Google サービス アカウント（Cloud Source Repositories のリポジトリのみ）

どちらの方法を選択するかは、リポジトリがサポートする対象によって異なります。通常は、SSH 認証鍵ペアを使用することをおすすめします。GitHub と Bitbucket はどちらも SSH 認証鍵ペアの使用をサポートしています。ただし、Cloud Source Repositories のリポジトリを使用している場合は、プロセスがよりシンプルであるため、Google サービス アカウントの使用をおすすめします。組織でリポジトリをホストしていて、どの認証方法がサポートされているかがわからない場合は、管理者にお問い合わせください。

SSH 認証鍵ペア

SSH 認証鍵ペアは、公開鍵と秘密鍵の 2 つのファイルから構成されています。通常、公開鍵の拡張子は .pub です。

SSH 認証鍵ペアを使用するには、次の手順を行います。

  1. SSH 認証鍵ペアを作成し、Config Sync が Git リポジトリに対して認証されるようにします。この手順は、リポジトリのクローンを作成するか、リポジトリの内容を読み取る際に認証が必要になる場合に必要になります。鍵ペアがセキュリティ管理者から提供される場合は、この手順を省略します。自社のセキュリティとコンプライアンスの要件に応じて、すべてのクラスタに対して単一の鍵ペアを使用するか、クラスタごとに 1 つの鍵ペアを使用するかを選びます。

    次のコマンドは 4,096 ビットの RSA 鍵を作成します。これよりビット数の少ない鍵はおすすめできません。

    ssh-keygen -t rsa -b 4096 \
-C "GIT_REPOSITORY_USERNAME" \
-N '' \
-f /path/to/KEYPAIR_FILENAME

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

    • GIT_REPOSITORY_USERNAME: Config Sync がリポジトリへの認証で使用するユーザー名。
    • /path/to/KEYPAIR_FILENAME: 鍵ペアへのパス。

    GitHub などのサードパーティ Git リポジトリ ホストを使用している場合や、Cloud Source Repositories でサービス アカウントを使用する場合は、別のアカウントを使用することをおすすめします。

  2. 新しく作成した公開鍵を認識するようにリポジトリを構成します。ご使用の Git ホスティング プロバイダのドキュメントをご覧ください。よく使われる Git ホスティング プロバイダの手順へのリンクを以下に示します。

  3. 秘密鍵をクラスタ内の新しい Secret に追加します。

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

    /path/to/KEYPAIR_PRIVATE_KEY_FILENAME は、秘密鍵の名前に置き換えます（.pub 拡張子は付けません）。

  4. ローカル ディスクから秘密鍵を削除するか、秘密鍵を保護します。

  5. Config Sync を構成して Git リポジトリの URL を追加する場合は、SSH プロトコルを使用します。Cloud Source Repositories のリポジトリを使用している場合は、URL を入力する際に次の形式を使用する必要があります。

    ssh://EMAIL@source.developers.google.com:2022/p/PROJECT_ID/r/REPO_NAME

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

    • EMAIL: Google Cloud ユーザー名
    • PROJECT_ID: リポジトリが配置されている Google Cloud プロジェクトの ID
    • REPO_NAME: リポジトリの名前

cookiefile

cookiefile を取得するプロセスは、リポジトリの構成によって異なります。サンプルについては、Cloud Source Repositories のドキュメントの静的認証情報を生成するをご覧ください。認証情報は通常、ユーザーのホーム ディレクトリにある .gitcookies ファイルに保存されますが、セキュリティ管理者から提供されることもあります。

cookiefile を作成するには、次の手順を行います。

  1. cookiefile を作成して取得したら、クラスタの新しい Secret に追加します。

    HTTPS プロキシを使用しない場合は、次のコマンドを使用して Secret を作成します。

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=cookie_file=/path/to/COOKIEFILE

    HTTPS プロキシを使用する必要がある場合は、次のコマンドを実行して、cookiefile と一緒に Secret に追加します。

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=cookie_file=/path/to/COOKIEFILE \
 --from-literal=https_proxy=HTTPS_PROXY_URL

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

    • /path/to/COOKIEFILE: 適切なパスとファイル名
    • HTTPS_PROXY_URL: Git リポジトリとの通信時に使用する HTTPS プロキシの URL

  2. 引き続きローカルで必要な場合は、cookiefile の内容を保護します。必要でなければ削除します。

トークン

組織で SSH 認証鍵の使用が許可されていない場合は、トークンを使用することをおすすめします。Config Sync では、トークンとして GitHub の個人アクセス トークン（PAT）、GiLab の PAT、デプロイキー、Bitbucket のアプリ パスワードを使用できます。

トークンを使用して Secret を作成するには、次の手順を行います。

  1. GitHub または Bitbucket を使用してトークンを作成します。

  2. トークンを作成して取得したら、それをクラスタの新しい Secret に追加します。

    HTTPS プロキシを使用しない場合は、次のコマンドを使用して Secret を作成します。

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace="config-management-system" \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN

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

    • USERNAME: 使用するユーザー名。
    • TOKEN: 前のステップで作成したトークン。

    HTTPS プロキシを使用する必要がある場合は、次のコマンドを実行して、username および token と一緒に Secret に追加します。

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-literal=username=USERNAME \
  --from-literal=token=TOKEN \
 --from-literal=https_proxy=HTTPS_PROXY_URL

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

    • USERNAME: 使用するユーザー名。
    • TOKEN: 前のステップで作成したトークン。
    • HTTPS_PROXY_URL: Git リポジトリとの通信時に使用する HTTPS プロキシの URL。

  3. ローカルでのトークンが必要な場合は、トークンを保護します。必要でなければ削除します。

Google サービス アカウント

リポジトリが Cloud Source Repositories にある場合は、Google サービス アカウントを使用して、マネージド クラスタと同じプロジェクト内のリポジトリに対するアクセス権を Config Sync に付与できます。

Cloud Source Repositories のリポジトリを Config Sync リポジトリとして使用するには、次の手順を行います。

  1. Cloud Source Repositories の URL を取得します。

    1. リポジトリのリストを取得します。

      gcloud source repos list

    2. 使用するリポジトリの URL を出力からコピーします。次に例を示します。

      REPO_NAME  PROJECT_ID  URL
my-repo    my-project  https://source.developers.google.com/p/my-project/r/my-repo-csr

      この URL は、次のセクションで Config Sync を構成するときに必要になります。Google Cloud Console を使用して Config Sync を構成する場合は、URL を [URL] フィールドに追加します。Google Cloud CLI を使用して Config Sync を構成する場合は、構成ファイルの syncRepo フィールドに URL を追加します。

  2. Config Sync を構成するときに、適切な認証タイプを選択します。選択する認証タイプは、所有しているクラスタの種類と Workload Identity が有効かどうかによって異なります。

    • Workload Identity が有効な場合: GKE Workload Identity を有効にしている場合、またはフリートの Workload Identity を使用している場合は、この方法を使用します。フリートの Workload Identity を使用している場合は、GKE クラスタと非 GKE クラスタの両方でこの認証方法を使用できます。

      クラスタがフリートに登録されている場合、Config Sync はデフォルトでフリートの Workload Identity を使用します。登録したクラスタでフリートの Workload Identity が有効になっていることを確認します。詳細については、クラスタを登録するをご覧ください。クラスタがフリート ホスト プロジェクトと異なるプロジェクトにある場合は、フリート ホスト プロジェクトの Kubernetes サービス アカウントに Google サービス アカウントをバインドする必要があります。

    • Workload Identity が有効になっていない場合: この方法は、GKE クラスタにのみ使用できます。

    Workload Identity が有効になっている

    1. 必要に応じて、サービス アカウントを作成します。サービス アカウントに source.reader ロールを付与して、Cloud Source Repositories に対する読み取りアクセス権があることを確認します。

    2. Google Cloud Console を使用して Config Sync を構成する場合は、[認証タイプ] で [Workload Identity] を選択し、サービス アカウントのメールアドレスを追加します。

      Google Cloud CLI を使用して Config Sync を構成する場合は、gcpserviceaccount を secretType として追加し、サービス アカウントのメールアドレスを gcpServiceAccountEmail に追加します。

    3. Config Sync の構成が完了したら、Kubernetes サービス アカウントと Google サービス アカウントの間に IAM ポリシー バインディングを作成します。Config Sync を構成するまで Kubernetes サービス アカウントは作成されません。

      フリートに登録されたクラスタを使用している場合は、フリートごとに 1 回だけポリシー バインディングを作成する必要があります。フリートに登録されたすべてのクラスタは、同じ Workload Identity プールを共有します。フリートのコンセプトである同一性により、1 つのクラスタの Kubernetes サービス アカウントに IAM ポリシーを追加すると、同じフリート内の他のクラスタでも同じ Namespace の Kubernetes サービス アカウントが同じ IAM ポリシーを取得します。

      このバインディングにより、Config Sync Kubernetes サービス アカウントが Google サービス アカウントとして機能できるようになります。

      gcloud iam service-accounts add-iam-policy-binding \
   --role roles/iam.workloadIdentityUser \
   --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

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

      • PROJECT_ID: GKE Workload Identity を使用している場合は、組織のプロジェクト ID を追加します。

        フリートの Workload Identity を使用している場合は、2 つの異なるプロジェクト ID を使用できます。serviceAccount:PROJECT_ID で、クラスタが登録されているフリートのプロジェクト ID を追加します。GSA_NAME@PROJECT_ID に、Cloud Source Repositories のリポジトリに対する読み取りアクセス権を持つプロジェクトのプロジェクト ID を追加します。

      • KSA_NAME: Reconciler の Kubernetes サービス アカウント。ルート リポジトリでは、RootSync の名前が root-sync の場合、KSA_NAME は root-reconciler です。それ以外の場合は root-reconciler-ROOT_SYNC_NAME です。

        名前空間リポジトリでは、RepoSync の名前が repo-sync の場合、KSA_NAME は ns-reconciler-NAMESPACE です。それ以外の場合は ns-reconciler-NAMESPACE-REPO_SYNC_NAME です。

      • GSA_NAME: Cloud Source Repositories への接続に使用するカスタム Google サービス アカウント。選択した Google サービス アカウントに source.reader ロールがあることを確認します。

    Workload Identity が有効になっていない

    Google Cloud Console を使用して Config Sync を構成する場合は、[認証タイプ] に [Google Cloud Repository] を選択します。

    Google Cloud CLI を使用して Config Sync を構成する場合は、gcenode を secretType として追加します。

    Google Cloud Repository または gcenode を選択すると、Compute Engine のデフォルトのサービス アカウントを使用できます。デフォルトでは、Compute Engine のデフォルトのサービス アカウント PROJECT_ID-compute@developer.gserviceaccount.com には、同じプロジェクトのリポジトリに対する source.reader アクセス権が付与されています。ただし、Cloud Source Repositories がクラスタのプロジェクトと異なるプロジェクトに存在する場合、クラスタのプロジェクトからデフォルトの Compute Engine サービス アカウントに Cloud Source Repositories のプロジェクトの source.reader を付与する必要があります。

    次のコマンドで source.reader ロールを追加できます。

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
  --role roles/source.reader

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

    • PROJECT_ID: 組織のプロジェクト ID
    • PROJECT_NUMBER: 組織のプロジェクト番号

    アクセス スコープは、ノードプールの作成後は変更できません。ただし、同じクラスタを使用しながら、適切なアクセス スコープを持つ新しいノードプールを作成できます。デフォルトの gke-default スコープに cloud-source-repos-ro は含まれません。

Operator に OCI への読み取り専用アクセス権を付与する

イメージに含まれている構成ファイルを読み取り、クラスタに適用できるように、Artifact Registry に保存されている OCI イメージへの読み取り専用権限を Config Sync に付与する必要があります。

イメージに読み取り専用アクセスの認証が不要な場合は、引き続き Config Sync を構成し、認証タイプとして none を使用します。たとえば、イメージが公開されていて、インターネットで誰でもアクセスできる場合、認証は不要です。

ただし、ほとんどのユーザーは、制限付きイメージにアクセスするために、認証情報を作成する必要があります。制限付きの読み取りアクセスが許可されているイメージの場合、認証タイプとして gcenode または gcpserviceaccount を使用する Google サービス アカウントを使用できます。

gcenode

クラスタが GKE クラスタで、Workload Identity が有効になっていない場合は、認証タイプとして gcenode を使用できます。Config Sync は Compute Engine のデフォルトのサービス アカウントを使用します。Compute Engine のデフォルト サービス アカウントには、Artifact Registry への読み取りアクセス権を付与する必要があります。

  1. 次のコマンドを実行して、プロジェクト番号を環境変数に保存します。

    export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID \
    --format=json | jq -r .projectNumber)

    PROJECT_ID は、実際のプロジェクト ID に置き換えます。

  2. 次のコマンドを実行して、Compute Engine サービス アカウントに Artifact Registry への読み取り権限を付与します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
   --role=roles/artifactregistry.reader

gcpserviceaccount

クラスタで GKE Workload Identity またはフリートの Workload Identity を使用している場合は、認証タイプとして gcpserviceaccount を使用できます。

  1. サービス アカウントをまだ持っていない場合は、サービス アカウントを作成して Artifact Registry 読み取り（roles/artifactregistry.reader）IAM ロールを付与します。

  2. 次のコマンドを実行して、Kubernetes サービス アカウントと Google サービス アカウントの IAM ポリシー バインディングを作成します。

    gcloud iam service-accounts add-iam-policy-binding \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

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

    • PROJECT_ID: GKE Workload Identity を使用している場合は、組織のプロジェクト ID。フリートの Workload Identity を使用している場合は、2 つの異なるプロジェクト ID を使用できます。serviceAccount:PROJECT_ID で、クラスタが登録されているフリートのプロジェクト ID を追加します。GSA_NAME@PROJECT_ID に、Cloud Source Repositories のリポジトリに対する読み取りアクセス権を持つプロジェクトのプロジェクト ID を追加します。
    • KSA_NAME: Reconciler の Kubernetes サービス アカウント。
      • ルート リポジトリで、RootSync 名が root-sync の場合は、root-reconciler を追加します。それ以外の場合は、root-reconciler-ROOT_SYNC_NAME を追加します。
      • Namespace リポジトリで、RepoSync 名が repo-sync の場合は ns-reconciler-NAMESPACE を追加します。それ以外の場合は、ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH を追加します。ここで、REPO_SYNC_NAME_LENGTH は REPO_SYNC_NAME の文字数です。
    • GSA_NAME: Artifact Registry への接続に使用するカスタム Google サービス アカウント。このサービス アカウントには、Artifact Registry 読み取り（roles/artifactregistry.reader）IAM ロールが必要です。

認証局の Operator を構成する

まだ信頼されていない認証局（CA）の証明書が構成されている Git サーバーの場合、CA 証明書を使用して Git サーバーへの HTTPS 接続を検証するように Config Sync を構成できます。CA 証明書には、完全な SSL 証明書（ルート / 中間 / リーフ）が含まれている必要があります。Git サーバーですでに信頼できる CA が使用されているか、HTTPS 経由で接続していない場合は、この手順をスキップして caCertSecretRef を未設定のままにしてください。

RootSync

  1. Git サーバーの証明書の発行に使用された CA 証明書を取得し、ファイルに保存します。

  2. RootSync オブジェクトの場合、Secret は config-management-system Namespace 内に作成する必要があります。次に例を示します。

    kubectl create ns config-management-system && 
    
kubectl create secret generic ROOT_CA_CERT_SECRET_NAME 
    
 --namespace=config-management-system 
    
 --from-file=cert=/path/to/CA_CERT_FILE

  3. Operator を構成する場合は、RootSync オブジェクトの spec.git.caCertSecretRef.name フィールドの値を ROOT_CA_CERT_SECRET_NAME に設定します。

RepoSync

  1. Git サーバーの証明書の発行に使用された CA 証明書を取得し、ファイルに保存します。

  2. RepoSync オブジェクトの場合、Secret は RepoSync と同じ Namespace に作成する必要があります。次に例を示します。

    kubectl create ns REPO_SYNC_NAMESPACE && 
    
kubectl create secret generic NAMESPACE_CA_CERT_SECRET_NAME 
    
 --namespace=REPO_SYNC_NAMESPACE 
    
 --from-file=cert=/path/to/CA_CERT_FILE

  3. RepoSync を構成する場合は、RepoSync オブジェクトの spec.git.caCertSecretRef.name フィールドの値を NAMESPACE_CA_CERT_SECRET_NAME に設定します。

Operator に Helm への読み取り専用アクセス権を付与する

Config Sync には、Helm リポジトリに対する読み取り専用権限が必要です。この権限により、Config Sync はリポジトリ内の Helm チャートを読み取り、クラスタ内にインストールできるようになります。

読み取り専用アクセスに対してリポジトリによる認証が不要な場合は、引き続き Config Sync を構成し、認証タイプとして none を使用できます。たとえば、Helm リポジトリが一般公開されていて、インターネットで誰でもアクセスできる場合は、認証する必要はありません。

ただし、ほとんどのユーザーは公開 Helm リボジトリにアクセスするために、認証情報を作成する必要があります。Config Sync は、次の認証メカニズムをサポートしています。

  • token
  • gcenode

  • gcpserviceaccount

token

Helm リポジトリのユーザー名とパスワードを使用して Secret を作成します。

kubectl create secret generic SECRET_NAME \
    --namespace=config-management-system \
    --from-literal=username=USERNAME \
    --from-literal=password=PASSWORD

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

  • SECRET_NAME: Secret に付ける名前。
  • USERNAME: Helm リポジトリのユーザー名。
  • PASSWORD: Helm リポジトリのパスワード。

Config Management Operator を構成する場合は、spec.helm.secretRef.name に選択した Secret 名を使用します。

gcenode

クラスタが GKE クラスタで、Workload Identity が有効になっていない場合は、認証タイプとして gcenode を使用できます。Config Sync は Compute Engine のデフォルトのサービス アカウントを使用します。Compute Engine のデフォルト サービス アカウントには、Artifact Registry への読み取りアクセス権を付与する必要があります。イメージを pull するための読み取り専用権限を付与するには、storage-ro アクセス スコープを付与することが必要な場合があります。

  1. プロジェクト番号を環境変数に保存します。

    export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')

    PROJECT_ID は、実際のプロジェクト ID に置き換えます。

  2. Compute Engine サービス アカウントに Artifact Registry への読み取り権限を付与します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/artifactregistry.reader

gcpserviceaccount

Helm チャートを Artifact Registry に保存し、クラスタで GKE Workload Identity かフリート Workload Identity を使用する場合、gcpserviceaccount を認証タイプとして使用できます。

  1. サービス アカウントをまだ持っていない場合は、サービス アカウントを作成して Artifact Registry 読み取り（roles/artifactregistry.reader）IAM ロールを付与します。Artifact Registry のロールと権限の詳細については、Artifact Registry のロールと権限の構成をご覧ください。

  2. 次のコマンドを実行して、Kubernetes サービス アカウントと Google サービス アカウントの IAM ポリシー バインディングを作成します。

    gcloud iam service-accounts add-iam-policy-binding \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

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

    • PROJECT_ID: GKE Workload Identity を使用している場合は、組織のプロジェクト ID。フリートの Workload Identity を使用している場合は、2 つの異なるプロジェクト ID を使用できます。serviceAccount:PROJECT_ID で、クラスタが登録されているフリートのプロジェクト ID を追加します。GSA_NAME@PROJECT_ID に、Cloud Source Repositories のリポジトリに対する読み取りアクセス権を持つプロジェクトのプロジェクト ID を追加します。
    • KSA_NAME: Reconciler の Kubernetes サービス アカウント。
      • ルート リポジトリで、RootSync 名が root-sync の場合は、root-reconciler を追加します。それ以外の場合は、root-reconciler-ROOT_SYNC_NAME を追加します。
      • Namespace リポジトリで、RepoSync 名が repo-sync の場合は ns-reconciler-NAMESPACE を追加します。それ以外の場合は、ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH を追加します。ここで、REPO_SYNC_NAME_LENGTH は REPO_SYNC_NAME の文字数です。
    • GSA_NAME: Artifact Registry への接続に使用するカスタム Google サービス アカウント。このサービス アカウントには、Artifact Registry 読み取り（roles/artifactregistry.reader）IAM ロールが必要です。

Operator を構成する

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

  1. Config Sync アドミッション Webhook を使用していて（アドミッション Webhook はデフォルトで無効になっています）、限定公開クラスタに Config Sync をインストールする場合、ポート 10250 を許可するファイアウォール ルールを追加します。Config Sync アドミッション Webhook では、ドリフト防止にポート 10250 を使用します。

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

    # config-management.yaml
apiVersion: configmanagement.gke.io/v1
kind: ConfigManagement
metadata:
  name: config-management
spec:
  # The `enableMultiRepo` field is set to true to enable RootSync and RepoSync APIs.
  enableMultiRepo: true
  preventDrift: PREVENT_DRIFT

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

    • PREVENT_DRIFT: true に設定されている場合、Config Sync アドミッション Webhook を有効にして、競合変更がライブクラスタに push されないように拒否することにより、ブレを防止します。デフォルトの設定は false です。Config Sync は、このフィールドの値に関係なく、常にブレを修正します。

  3. 変更を適用します。

    kubectl apply -f config-management.yaml

  4. CRD の RootSync と RepoSync が使用可能になるまで待ちます。

    until kubectl get customresourcedefinitions rootsyncs.configsync.gke.io reposyncs.configsync.gke.io; do date; sleep 1; echo ""; done

  5. 次のいずれかのマニフェストを root-sync.yaml として保存します。構成ファイルのソースタイプに対応するマニフェスト バージョンを使用します。

    Git

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: git
  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
    noSSLVerify: ROOT_NO_SSL_VERIFY
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

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

    • ROOT_SYNC_NAME: RootSync オブジェクトの名前を追加します。
    • ROOT_FORMAT: 非構造化リポジトリを使用するには unstructured を追加し、階層型リポジトリを使用するには hierarchy を追加します。この値では大文字と小文字が区別されます。このフィールドは省略可能で、デフォルト値は hierarchy です。unstructured を追加することをおすすめします。この形式では自分にとって最も便利な方法で構成ファイルを整理できます。
    • ROOT_REPOSITORY: ルート リポジトリとして使用する Git リポジトリの URL を記述します。HTTPS または SSH プロトコルを使用する URL を入力できます。たとえば、https://github.com/GoogleCloudPlatform/anthos-config-management-samples では HTTPS プロトコルを使用します。このフィールドは必須です。
    • 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: ROOT_AUTH_TYPE として gcpserviceaccount を追加した場合は、Google サービス アカウントのメールアドレスを追加します。例: acm@PROJECT_ID.iam.gserviceaccount.com

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

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

    • ROOT_CA_CERT_SECRET_NAME: Secret の名前を追加します。このフィールドが設定されている場合、この認証局（CA）によって発行された証明書を Git プロバイダで使用する必要があります。cert という名前の鍵の CA 証明書を Secret に含める必要があります。このフィールドは省略可能です。

      CA 証明書の Secret オブジェクトの構成方法については、認証局の Operator の構成をご覧ください。

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

    このマニフェストは、Git をソースとして使用する RootSync オブジェクトを作成します。

    OCI

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: oci
  sourceFormat: ROOT_FORMAT
  oci:
    image: ROOT_IMAGE
    dir: ROOT_DIRECTORY
    auth: ROOT_AUTH_TYPE
    gcpServiceAccountEmail: ROOT_EMAIL

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

    • ROOT_SYNC_NAME: RootSync オブジェクトの名前を追加します。
    • ROOT_FORMAT: 非構造化リポジトリを使用するには unstructured を追加し、階層型リポジトリを使用するには hierarchy を追加します。この値では大文字と小文字が区別されます。このフィールドは省略可能で、デフォルト値は hierarchy です。unstructured を追加することをおすすめします。この形式では自分にとって最も便利な方法で構成ファイルを整理できます。
    • ROOT_IMAGE: ルート リポジトリとして使用する OCI イメージの URL（例: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME）。デフォルトでは、イメージは latest タグから取得されますが、TAG または DIGEST を使用してイメージを pull することもできます。PACKAGE_NAME で TAG または DIGEST を指定します。
      • TAG で pull するには: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
      • DIGEST で pull するには: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST
    • ROOT_DIRECTORY: 同期先への構成を含むルート ディレクトリへのリポジトリのパスを記述します。このフィールドは省略可能で、デフォルトはリポジトリのルート ディレクトリ（/）です。

    • ROOT_AUTH_TYPE: 次のいずれかの認証タイプを記述します。

      • none: 認証なし
      • gcenode: Compute Engine のデフォルト サービス アカウントを使用して、Artifact Registry のイメージにアクセスします。このオプションは、Workload Identity がクラスタで有効になっていない場合にのみ選択してください。
      • gcpserviceaccount: Google サービス アカウントを使用してイメージにアクセスします。

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

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

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

    このマニフェストは、OCI イメージをソースとして使用する RootSync オブジェクトを作成します。

    Helm

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: helm
  sourceFormat: ROOT_FORMAT
  helm:
    repo: ROOT_HELM_REPOSITORY
    chart: HELM_CHART_NAME
    version: HELM_CHART_VERSION
    releaseName: HELM_RELEASE_NAME
    namespace: HELM_RELEASE_NAMESPACE
    values:
      foo:
        bar: VALUE_1
      baz:
      - qux: VALUE_2
        xyz: VALUE_3
    includeCRDs: HELM_INCLUDE_CRDS
    auth: ROOT_AUTH_TYPE
      gcpServiceAccountEmail: ROOT_EMAIL
      secretRef:
        name: ROOT_SECRET_NAME

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

    • ROOT_SYNC_NAME: RootSync オブジェクトの名前を追加します。
    • ROOT_FORMAT: 非構造化リポジトリを使用するには unstructured を追加し、階層型リポジトリを使用するには hierarchy を追加します。この値では大文字と小文字が区別されます。このフィールドは省略可能で、デフォルト値は hierarchy です。unstructured を追加することをおすすめします。この形式では自分にとって最も便利な方法で構成ファイルを整理できます。
    • ROOT_HELM_REPOSITORY: ルート リポジトリとして使用する Helm リポジトリの URL。HTTPS または SSH プロトコルを使用する URL を入力できます。たとえば、https://github.com/GoogleCloudPlatform/anthos-config-management-samples では HTTPS プロトコルを使用します。このフィールドは必須です。
    • HELM_CHART_NAME: Helm チャートの名前を追加します。このフィールドは必須です。
    • HELM_CHART_VERSION: チャートのバージョン。このフィールドは省略可能です。値が指定されていない場合は、最新バージョンが使用されます。
    • HELM_RELEASE_NAME: Helm リリースの名前。このフィールドは省略可能です。
    • HELM_RELEASE_NAMESPACE: リリースのターゲット Namespace。テンプレートに namespace: {{ .Release.Namespace }} を含むリソースの Namespace のみが設定されます。このフィールドは省略可能です。値が指定されていない場合は、デフォルトの Namespace config-management-system が使用されます。
    • HELM_INCLUDE_CRDS: Helm テンプレートでも CustomResourceDefinition を生成する場合は、true に設定します。このフィールドは省略可能です。値が指定されていない場合、デフォルトは false であり、CRD は生成されません。
    • VALUE: Helm チャートのデフォルト値の代わりに使用する値。このフィールドを Helm チャートの values.yaml ファイルと同じ方法でフォーマットします。このフィールドは省略可能です。

    • ROOT_AUTH_TYPE: 次のいずれかの認証タイプを記述します。

      • none: 認証なし
      • token: 非公開 Helm リポジトリへのアクセスにユーザー名とパスワードを使用します。
      • gcenode: Compute Engine のデフォルト サービス アカウントを使用して、Artifact Registry のイメージにアクセスします。このオプションは、Workload Identity がクラスタで有効になっていない場合にのみ選択してください。
      • gcpserviceaccount: Google サービス アカウントを使用してイメージにアクセスします。

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

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

    • ROOT_SECRET_NAME: token が ROOT_AUTH_TYPE の場合は、Secret の名前を追加します。このフィールドは省略可能です。

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

    このマニフェストは、Helm を情報源として使用する RootSync オブジェクトを作成します。

  6. 変更を適用します。

    kubectl apply -f root-sync.yaml

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

ルート リポジトリの同期ステータスは、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 の Reconciler が作成されます。Reconciler は、Deployment としてデプロイされる Pod です。Git リポジトリからマニフェストにクラスタに同期します。

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

kubectl get -n config-management-system deployment \
    -l configsync.gke.io/sync-name=ROOT_SYNC_NAME

ROOT_SYNC_NAME は、RootSync の名前に置き換えます。

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

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

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

ルート リポジトリの構成が終了したら、必要に応じて複数のリポジトリからの同期を構成選択できます。これらのリポジトリは、クラスタ全体で特定の Namespace に同期される名前空間スコープの構成ファイルを 1 つのリポジトリに保存する場合に役立ちます。

Config Sync をアップグレードする

Config Sync をアップグレードするには、登録されているクラスタごとに次のコマンドを実行します。

  1. 新しいバージョン用の Config Sync、Policy Controller、Config Controller のマニフェスト コマンドと nomos コマンドをダウンロードします。

  2. Config Sync、Policy Controller、Config Controller のマニフェストを適用します。

    kubectl apply -f config-management-operator.yaml

    このコマンドは、Config Sync、Policy Controller、Config Controller のイメージを更新します。Kubernetes は新しいバージョンを取得し、その新しいバージョンを使用して Config Sync、Policy Controller、Config Controller Pod を再起動します。Config Sync、Policy Controller、Config Controller が起動すると、新しいイメージにバンドルされたマニフェストのセットを適用する調整ループが実行されます。これにより、各コンポーネントの Pod が更新され、再起動されます。

  3. すべてのクライアントの nomos コマンドを新しいバージョンに置き換えます。この変更により、nomos コマンドを実行して、登録済みのすべてのクラスタのステータスを確実に取得し、構成ファイルを検証できるようになります。

Config Sync をアンインストールする

Config Sync をアンインストールする手順は次のとおりです。

  1. 中央管理者がルート リポジトリを削除する必要があります。

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

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

      kubectl delete -f root-sync.yaml

  2. リポジトリを削除します。

  3. config-management.yaml ファイルの spec.enableMultiRepo フィールドを削除します。

  4. config-management.yaml ファイルをクラスタに適用します。

Config Sync、Policy Controller、Config Controller を完全にアンインストールする場合は、Config Management Operator の削除をご覧ください。

次のステップ