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 は次の認証方法にも対応していますが、これらの方法は、前の表にある認証方法が使用できない場合にのみ推奨されます。

• 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 Repo 閲覧者（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 のデフォルトのサービス アカウントを使用する

Workload Identity Federation for GKE を有効にしていない場合、Google サービス アカウントの代わりに、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 のインストールをカスタマイズする