Config Sync に Git リポジトリへのアクセス権を付与する

このページでは、Config Sync を Git リポジトリに対して認証する方法について説明します。Config Sync が構成を読み取り、クラスタに適用して同期を維持するには、信頼できる情報源に対する読み取り専用アクセス権が必要です。

認証方法を選択する

使用する認証方法は、ソースタイプでサポートされているものによって異なります。

次の表に、Config Sync で使用できる認証方法の概要を示します。

メソッド	サポート対象のソース	説明	制限事項
認証なし	Git、OCI、Helm	追加の設定は必要ありません。	信頼できる情報源が公開されている場合にのみ機能します。
SSH 認証鍵ペア	Git	ほとんどの Git プロバイダでサポートされています。	鍵の管理が必要です。OCI または Helm ではサポートされていません。
token	Git、Helm	ほとんどの Git プロバイダでサポートされています。組織で SSH 認証鍵の使用が許可されていない場合に適した代替手段です。Helm のユーザー名とパスワードをサポートします。	トークン管理が必要です。トークンには有効期限があります。オフライン コンバージョン インポートではサポートされていません。
Kubernetes サービス アカウント	OCI、Helm	IAM を使用して、Artifact Registry へのアクセス権を Kubernetes サービス アカウントに直接付与します。クラスタで Workload Identity Federation for GKE が有効になっている必要があります。	Git ではサポートされていません。
Google サービス アカウント	Git	IAM を使用するため、認証情報を Kubernetes Secret に保存する必要がありません。Secure Source Manager と Cloud Source Repositories に推奨されます。クラスタで Workload Identity Federation for GKE が有効になっている必要があります。	クラスタに Config Sync をインストールする前後に構成が必要です。Secure Source Manager または Cloud Source Repositories の外部でホストされているリポジトリではサポートされていません。
GitHub アプリ	Git	GitHub との直接統合。きめ細かい権限を付与できます。	GitHub でホストされているリポジトリでのみサポートされます。Config Sync バージョン 1.19.1 以降でのみサポートされます。

Config Sync は次の認証方法もサポートしていますが、これらの方法は、前の表に記載されているオプションのいずれも使用できない場合にのみ推奨されます。

• cookiefile: は、すべての Git プロバイダでサポートされているとは限りません。OCI または Helm ではサポートされていません。
• Compute Engine のデフォルトのサービス アカウント（gcenode）: この方法は、Workload Identity Federation for GKE が無効になっている場合にのみ機能するため、おすすめしません。Git、OCI、Helm でサポートされています。
• Helm と OCI の Google サービス アカウント: サポートされていますが、Kubernetes サービス アカウントの方法では構成が少なくて済むため、おすすめしません。

フリート パッケージによる認証

フリート パッケージを使用している場合は、このページの手順を完了する必要はありません。フリート パッケージは Cloud Build を使用して Git の認証を行うため、プロジェクトごとに 1 回認証するだけで済みます。クラスタに Config Sync をインストールするたびにアクセス権を付与する必要はありません。

始める前に

Config Sync に Git リポジトリに対する読み取り専用アクセス権を付与する前に、次のタスクを完了します。

• Config Sync で同期する構成ファイルを保存する Git リポジトリを準備するか、このリポジトリにアクセスできるようにします。詳しくは、次のリソースをご覧ください。

  • 信頼できる情報源に構成を追加する: 構成に関するコンセプト情報。
  • GitOps のベスト プラクティス: リポジトリの整理と管理に関するヒントと一般的なベスト プラクティス。
  • 非構造化リポジトリを使用する: 非構造化リポジトリの使用と整理に関する推奨事項。

• GKE クラスタを作成するか、アクセス権を取得します。クラスタを作成する前に、Config Sync のクラスタ構成の要件と推奨事項を確認してください。

重要: このページの手順で作成された Secret や機密情報を保護します。たとえば、不要になったファイルは削除したり、安全な方法で保存したりできます。

SSH 認証鍵ペアを使用する

SSH 認証鍵ペアは、公開鍵と秘密鍵の 2 つのファイルで構成されています。Config Sync はパスフレーズの作成をサポートしていません。セキュリティとコンプライアンスの要件に応じて、すべてのクラスタに対して単一の鍵ペアを使用するか、クラスタごとに 1 つの鍵ペアを使用するかを選択できます。

SSH 鍵ペアを使用して Config Sync に Git リポジトリへの読み取り専用アクセス権を付与するには、次の操作を行います。

1. SSH 認証鍵ペアを作成するか、セキュリティ管理者に提供を依頼します。SSH 認証鍵ペアを作成する必要がある場合は、次のコマンドを実行して 4, 096 ビットの RSA 鍵を作成します。

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

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

   • GIT_REPOSITORY_USERNAME: Config Sync がリポジトリへの認証で使用するユーザー名。GitHub などのサードパーティ Git リポジトリ ホストを使用している場合や、Secure Source Manager でサービス アカウントを使用する場合は、認証に別のアカウントを使用することをおすすめします。
   • /path/to/KEYPAIR_FILENAME: 鍵ペア ファイルのパス。

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

   • Secure Source Manager
   • Bitbucket
   • GitHub
   • GitLab

3. 秘密鍵を使用して git-creds 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
   

   注: プロキシを使用する必要がある場合は、--from-literal=https_proxy=HTTPS_PROXY_URL フラグを渡します。

   /path/to/KEYPAIR_PRIVATE_KEY_FILENAME は、秘密鍵の名前に置き換えます。

4. 省略可（推奨）: SSH 認証を使用するときに既知のホストのチェックを構成するには、git_creds Secret の data.known_hosts フィールドに既知のホストキーを追加します。

   1. 既知のホスト鍵を追加するには、次のコマンドを実行します。

      kubectl edit secret git-creds --namespace=config-management-system
      

   2. data に known_hosts エントリを追加するには、次のコマンドを実行します。

        known_hosts: KNOWN_HOSTS_KEY
      

      KNOWN_HOSTS_KEY は、既知のホストキーに置き換えます。

   known_hosts のチェックを無効にするには、Secret から known_hosts フィールドを削除します。

Config Sync をインストールするときに、認証タイプとして SSH 鍵ペア（ssh）を使用します。

Git リポジトリの URL を入力する場合は、URL で SSH プロトコル形式を使用する必要があります。URL の形式は Git プロバイダによって異なります。

cookiefile を使用する

cookiefile を取得するプロセスは、リポジトリの構成によって異なります。通常、認証情報はホーム ディレクトリの .gitcookies ファイルに保存されます。また、セキュリティ管理者から提供されることもあります。

cookiefile を使用して Config Sync に Git リポジトリへの読み取り専用アクセス権を付与するには、次の操作を行います。

cookiefile を作成または取得したら、クラスタの新しい Secret に追加します。セキュリティ上の理由から、HTTPS の使用をおすすめします。

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

/path/to/COOKIEFILE は、パスとファイル名に置き換えます。

注: プロキシを使用する必要がある場合は、--from-literal=https_proxy=HTTPS_PROXY_URL フラグを渡します。

Config Sync をインストールするときに、認証タイプとして cookiefile（cookiefile）を使用します。

トークンを使用する

組織で SSH 認証鍵の使用が許可されていない場合は、トークンを使用することをおすすめします。

トークンを使用して Config Sync に Git リポジトリへの読み取り専用アクセス権を付与するには、次の操作を行います。

1. Git プロバイダからトークンを生成します。手順については、ご使用の Git ホスティング プロバイダのドキュメントをご覧ください。よく使われる Git ホスティング プロバイダの手順へのリンクを以下に示します。

   • GitHub: PAT を作成します。トークンに repo スコープを付与し、非公開リポジトリから読み取れるようにします。PAT を GitHub アカウントにバインドするため、マシンユーザーを作成し、PAT をそのマシンユーザーにバインドすることをおすすめします。
   • GitLab: PAT を作成するか、デプロイ トークンを作成します。
   • Bitbucket: アプリ パスワードを作成します。

2. トークンを作成または取得したら、クラスタの新しい Secret に追加します。セキュリティ上の理由から、HTTPS の使用をおすすめします。

   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: 前のステップで作成したトークン。

Config Sync をインストールするときに、認証タイプとしてトークン（token）を使用します。

Google サービス アカウントを使用する

Google サービス アカウントを使用して、マネージド クラスタと同じプロジェクト内のリポジトリに対するアクセス権を Config Sync に付与できます。次の要件を満たす必要があります。

• リポジトリが Secure Source Manager または Cloud Source Repositories にある。
• クラスタで Workload Identity Federation for GKE または フリート Workload Identity Federation for GKE が有効になっている。

Google サービス アカウントを使用して Git リポジトリへの読み取り専用アクセス権を Config Sync に付与するには、次の操作を行います。

1. ポリシー バインディングの作成に必要な権限を取得するには、サービス アカウントに対するサービス アカウント管理者 （roles/iam.serviceAccountAdmin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

   必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

2. サービス アカウントがない場合は、サービス アカウントを作成します。

3. 使用しているリポジトリのタイプに応じて、IAM ロールを Google サービス アカウントに付与します。

   Secure Source Manager

   Google サービス アカウントに Secure Source Manager インスタンス アクセサー（roles/securesourcemanager.instanceAccessor）と Secure Source Manager リポジトリ読み取り（roles/securesourcemanager.repoReader）の IAM ロールを付与します。

   • 同じ権限がプロジェクト内のすべてのリポジトリに適用される場合は、プロジェクト全体の権限を付与します。

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/securesourcemanager.instanceAccessor \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/securesourcemanager.repoReader \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

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

     • PROJECT_ID: プロジェクト ID。
     • GSA_NAME: Secure Source Manager に接続する Google サービス アカウントの名前。

   • リポジトリ固有の権限を付与するには、Secure Source Manager のドキュメントのユーザーにリポジトリ レベルのロールを付与するをご覧ください。

   Config Sync をインストールするときに、認証タイプとして Workload Identity（gcpserviceaccount）を使用します。サービス アカウントのメールアドレスも追加する必要があります。

   Secure Source Manager では、リポジトリ URL に https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git という特定の形式が必要です。

   Cloud Source Repositories

   Google サービス アカウントに Cloud Source Repositories 読み取り（roles/source.reader）IAM ロールを付与します。

   • 同じ権限がプロジェクト内のすべてのリポジトリに適用される場合は、プロジェクト全体の権限を付与します。

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/source.reader \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

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

     • PROJECT_ID: プロジェクト ID。
     • GSA_NAME: Cloud Source Repositories への接続に使用する Google サービス アカウントの名前。

   • サービス アカウントに、プロジェクト内のリポジトリごとに異なるレベルのアクセス権を付与する場合は、リポジトリ固有の権限を付与します。

     gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID
     

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

     • PROJECT_ID: プロジェクト ID。
     • REPOSITORY: リポジトリの名前。
     • POLICY_FILE: Identity and Access Management ポリシーを含む JSON または YAML ファイル。

   Config Sync をインストールするときに、認証タイプとして Workload Identity（gcpserviceaccount）を使用します。サービス アカウントのメールアドレスも追加する必要があります。

次の手順は、Config Sync を初めて構成するまで Kubernetes サービス アカウントが作成されないため、Config Sync の構成後に完了する必要があります。この操作はフリートごとに 1 回だけ行う必要があります。Kubernetes サービス アカウントが Google サービス アカウントとして機能できるようにするバインディングを作成するには、次のコマンドを実行します。

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

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

• FLEET_HOST_PROJECT_ID: Workload Identity Federation for GKE を使用している場合、値は PROJECT_ID と同じです。フリートの Workload Identity Federation for GKE を使用する場合は、クラスタが登録されているフリートのプロジェクト ID を値として使用します。
• GSA_NAME: Secure Source Manager または Cloud Source Repositories への接続に使用するカスタム Google サービス アカウント。
• KSA_NAME: Reconciler の Kubernetes サービス アカウント。ほとんどの場合、値は root-sync です。これは、 Google Cloud コンソールまたは Google Cloud CLI を使用してインストールすると、Config Sync によって root-sync という RootSync オブジェクトが自動的に作成されるためです。それ以外の場合は、値として root-reconciler-ROOT_SYNC_NAME を使用します。

Google サービス アカウントで Config Sync に接続する際に問題が発生した場合は、Google サービス アカウントの権限に関する問題のトラブルシューティングを行うをご覧ください。

Compute Engine のデフォルトのサービス アカウントを使用する

Google サービス アカウントの代わりに、Workload Identity Federation for GKE が有効になっていない場合は、Compute Engine サービス アカウントを使用して認証できます。このメソッドは、Secure Source Manager と Cloud Source Repositories のリポジトリでのみサポートされています。

Compute Engine のデフォルトのサービス アカウントを使用して Config Sync にリポジトリへの読み取り専用アクセス権を付与するには、デフォルトのサービス アカウントに roles/source.reader ロールを付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:[e-mail]"

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

• PROJECT_ID: プロジェクト ID
• PROJECT_NUMBER: プロジェクト番号。

Config Sync をインストールするときに、認証タイプとして Google Cloud Repository（gcenode）を使用します。

GitHub アプリを使用する

リポジトリが GitHub にある場合は、GitHub アプリを使用してリポジトリを Config Sync に接続できます。

1. GitHub の手順に沿って GitHub アプリをプロビジョニングし、リポジトリからの読み取り権限を付与します。

2. クライアント ID またはアプリケーション ID を使用して、GitHub アプリの構成をクラスタ内の新しい Secret に追加します。

   クライアント ID

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-literal=github-app-client-id=CLIENT_ID \
     --from-literal=github-app-installation-id=INSTALLATION_ID \
     --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
     --from-literal=github-app-base-url=BASE_URL
   

   • CLIENT_ID は、GitHub アプリのクライアント ID に置き換えます。
   • INSTALLATION_ID は、GitHub アプリのインストール ID に置き換えます。
   • /path/to/GITHUB_PRIVATE_KEY は、秘密鍵を含むファイルの名前に置き換えます。
   • BASE_URL は、GitHub API エンドポイントのベース URL に置き換えます。この値は、リポジトリが www.github.com でホストされていない場合にのみ必要です。それ以外の場合は、引数を省略できます。デフォルトは https://api.github.com/ です。

   アプリケーション ID

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
       --namespace=config-management-system \
       --from-literal=github-app-application-id=APPLICATION_ID \
       --from-literal=github-app-installation-id=INSTALLATION_ID \
       --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
       --from-literal=github-app-base-url=BASE_URL
   

   • APPLICATION_ID は、GitHub アプリのアプリケーション ID に置き換えます。
   • INSTALLATION_ID は、GitHub アプリのインストール ID に置き換えます。
   • /path/to/GITHUB_PRIVATE_KEY は、秘密鍵を含むファイルの名前に置き換えます。
   • BASE_URL は、GitHub API エンドポイントのベース URL に置き換えます。この値は、リポジトリが www.github.com でホストされていない場合にのみ必要です。それ以外の場合は、引数を省略できます。デフォルトは https://api.github.com/ です。

Config Sync をインストールするときは、認証タイプとして GitHub アプリ（githubapp）を使用します。

トラブルシューティング

Config Sync を信頼できる情報源に接続する際の問題のトラブルシューティングについては、次のトラブルシューティング トピックをご覧ください。

• 信頼できる情報源への接続
• Google サービス アカウントの権限に関する問題

次のステップ

• デフォルトの設定で Config Sync をインストールする
• Config Sync のインストールをカスタマイズする