Config Connector を手動でインストールする

このページでは、Config Connector を手動でインストールする方法について説明します。手動インストールは、インストールされたバージョンとアップグレード スケジュールを制御できる柔軟なオプションです。

このページの手順では、Google Kubernetes Engine（GKE）クラスタに Config Connector をインストールする方法について説明します。さまざまなインストール オプションについて詳しくは、インストール タイプの選択をご覧ください。

ほとんどのユースケースでは、Config Connector を名前空間モードで手動でインストールする必要があります。もう 1 つの方法はクラスタモードです。名前空間モードはスケーラビリティが高く、権限の分離が向上するため、マルチテナント クラスタや複数のプロジェクトにわたるリソースの管理に推奨されるモードです。マルチテナント環境では、クラスタモードを使用しないでください。クラスタモードでは、単一の共有 Identity and Access Management（IAM）サービス アカウントが使用されます。任意の Namespace で Config Connector リソースを作成できるユーザーは、そのサービス アカウントの完全な IAM 権限で操作できます。

単一のクラスタ全体のサービス アカウントを使用する場合は、クラスタモードでインストールする手順に沿って操作します。

始める前に

Config Connector 演算子を手動でインストールする前に、次の手順を完了します。

• Config Connector がまだインストールされておらず、Workload Identity と Kubernetes Engine Monitoring を有効にした GKE クラスタの作成または識別を行います。
• クラスタに接続するように kubectl を構成します。

Config Connector Operator をインストールする

Config Connector は、Kubernetes Operator を使用してインストールを最新の状態にします。Config Connector を名前空間モードまたはクラスタモードでインストールする場合、オペレーターのインストールが必要です。

Config Connector 演算子をインストールするには、次の手順を行います。

1. 最新の Config Connector Operator の .tar ファイルをダウンロードします。

   gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
   

   注: インストール バンドルは、Config Connector をアンインストールするために必要であるため、このバンドルのコピーを保管してください。

2. tar ファイルを解凍します。

   tar zxvf release-bundle.tar.gz
   

3. クラスタに Config Connector Operator をインストールします。

   Autopilot

   kubectl apply -f operator-system/autopilot-configconnector-operator.yaml
   

   Standard

   kubectl apply -f operator-system/configconnector-operator.yaml
   

4. 名前空間モードで実行するように Config Connector Operator を構成するには、次の手順を完了します。

   1. 次の内容のマニフェストを configconnector.yaml という名前で作成します。

      apiVersion: core.cnrm.cloud.google.com/v1beta1
      kind: ConfigConnector
      metadata:
        # the name is restricted to ensure that there is only ConfigConnector resource installed in your cluster
        name: configconnector.core.cnrm.cloud.google.com
      spec:
        mode: namespaced
        stateIntoSpec: Absent
      

   2. マニフェストをクラスタに適用します。

      kubectl apply -f configconnector.yaml
      

Namespace が指定されたモードで Config Connector をインストールする

注: これらの手順は、Config Connector でリソースを作成するすべての Namespace に対して実行する必要があります。

以降のセクションでは、Config Connector をインストールするプロジェクトをホスト プロジェクトと呼びます。Config Connector でリソースを管理できる他のプロジェクトは、マネージド プロジェクトです。Config Connector でクラスタと同じプロジェクトにのみリソースを作成する場合は、ホスト プロジェクトとマネージド プロジェクトを同じプロジェクトにできます。

名前空間の作成

次のコマンドを実行して、新しい Namespace を作成します。

kubectl create namespace NAMESPACE

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

ID を作成する

次の手順を完了して、IAM サービス アカウントを作成し、IAM サービス アカウントと Config Connector Kubernetes サービス アカウントの間にバインディングを作成します。

1. IAM サービス アカウントを作成します。新しいサービス アカウントを作成せずに、既存のサービス アカウントを使用することもできます。次のコマンドを実行して、gcloud を使用してサービス アカウントを作成します。

   gcloud iam service-accounts create NAMESPACE_GSA --project HOST_PROJECT_ID
   

   以下を置き換えます。

   • NAMESPACE_GSA は、Namespace にバインドされた Google サービス アカウント（GSA）の名前に置き換えます。
   • HOST_PROJECT_ID は、ホスト プロジェクトの ID で置き換えます。

   サービス アカウントの作成の詳細については、サービス アカウントの作成と管理をご覧ください。

2. IAM サービス アカウントに、マネージド プロジェクトへの昇格した権限を付与します。

   gcloud projects add-iam-policy-binding MANAGED_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/owner"
   

   MANAGED_PROJECT_ID は、マネージド プロジェクトの ID に置き換えます。

   注: プロジェクトへの編集権限を付与する場合は、roles/owner を roles/editor に置き換えます。編集者のロールを付与すると、IAM の変更など、「プロジェクト / 組織」全体の構成を除く、ほとんどの Config Connector 機能が許可されます。

3. IAM サービス アカウントと Config Connector Kubernetes サービス アカウントの間に IAM ポリシー バインディングを作成します。

   gcloud iam service-accounts add-iam-policy-binding \
       NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com \
       --member="serviceAccount:HOST_PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager-NAMESPACE]" \
       --role="roles/iam.workloadIdentityUser"
   

4. IAM サービス アカウントに、ホスト プロジェクトの Google Cloud Observability に Prometheus 指標を公開する権限を付与します。

   gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/monitoring.metricWriter"
   

ConfigConnectorContext を作成する

Google Cloud リソースを作成するには、その Namespace に ConfigConnectorContext オブジェクトを追加して、Namespace を監視するように Config Connector を構成します。

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

1. 次の内容のマニフェストを configconnectorcontext.yaml という名前で作成します。

   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnectorContext
   metadata:
     # you need one ConfigConnectorContext per namespace
     name: configconnectorcontext.core.cnrm.cloud.google.com
     namespace: NAMESPACE
   spec:
     googleServiceAccount: "NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com"
     stateIntoSpec: Absent
   

2. マニフェストをクラスタに適用します。

   kubectl apply -f configconnectorcontext.yaml
   

3. 次のコマンドを実行して、Config Connector オペレーターが Namespace の Kubernetes サービス アカウントを作成したことを確認します。

   kubectl get serviceaccount/cnrm-controller-manager-NAMESPACE  -n cnrm-system
   

4. Namespace で Config Connector コントローラ Pod が実行されていることを確認します。

   kubectl wait -n cnrm-system \
       --for=condition=Ready pod \
       -l cnrm.cloud.google.com/component=cnrm-controller-manager \
       -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE
   

   Config Connector コントローラが実行中の場合は、出力は次のようになります。

   cnrm-controller-manager-abcdefghijk-0 condition met.
   

Namespace 内のリソースの管理を停止する

Config Connector が Namespace 内のリソースの管理を停止するようにするには、その Namespace 内のすべての Config Connector リソースと ConfigConnectorContext オブジェクトを削除します。

1. Namespace 内のすべての Config Connector リソースを検索するには、Config Connector のカスタム リソース定義ごとにすべてのリソースを一覧表示します。

   kubectl get gcp -n NAMESPACE
   

   このコマンドの出力には、その Namespace で Config Connector によって管理されるリソースを表す、すべてのカスタム リソース定義（CRD）が一覧表示されます。これには、そのリソースの名前と Kubernetes の種類が含まれます。

2. すべての Config Connector リソースを削除するには、前の手順の出力にあるリソースごとに次のコマンドを実行します。

   kubectl delete -n NAMESPACE KIND NAME
   

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

   • KIND: リソースの Kubernetes の種類。
   • NAME: リソースの名前。

3. Namespace 内の ConfigConnectorContext オブジェクトを削除します。

   kubectl delete -n NAMESPACE ConfigConnectorContext configconnectorcontext.core.cnrm.cloud.google.com
   

   重要: Config Connector で管理されているすべてのリソースが削除されるまで、ConfigConnectorContext オブジェクトを削除しないでください。

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

Config Connector をアンインストールするには、次の手順を実行します。

1. Config Connector CRD とコントローラ コンポーネントを削除するには、次のコマンドを実行します。

   kubectl delete ConfigConnectorContext --all -A –wait=false
   
   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. Config Connector Operator をアンインストールするには、次のコマンドを実行します。

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

クラスタモードでインストールする

単一のプロジェクト内でリソースを管理し、Namespace モードで提供される権限の分離を必要としない場合は、クラスタモードで Config Connector をインストールして管理することをおすすめします。

ID を作成する

Config Connector は、Identity and Access Management（IAM）サービス アカウントで認証し、Workload Identity Federation for GKE を使用して IAM サービス アカウントを Kubernetes サービス アカウントにバインドすることで、 Google Cloud リソースを作成、管理します。

注: これらの手順を実行する必要があるのは、クラスタごとに 1 回のみです。

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

1. IAM サービス アカウントを作成します。既存のサービス アカウントを使用する場合は、そのアカウントを使用してこの手順を省略できます。

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
   

   SERVICE_ACCOUNT_NAME は、サービス アカウントの名前に置き換えます。

   サービス アカウントの作成の詳細については、サービス アカウントの作成と管理をご覧ください。

2. IAM サービス アカウントに、プロジェクトへの昇格した権限を付与します。

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

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

   注: 編集者ロールを付与すると、IAM の変更など、プロジェクトや組織全体の構成を除くほとんどの Config Connector 機能が使用できます。本番環境では、よりきめ細かいアクセス許可を設定することをおすすめします。IAM ロールの詳細については、ロールについてをご覧ください。

3. IAM サービス アカウントと、Config Connector が実行する事前定義された Kubernetes サービス アカウントの間の IAM ポリシー バインディングを作成します。

   gcloud iam service-accounts add-iam-policy-binding \
   SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --member="serviceAccount:PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
     --role="roles/iam.workloadIdentityUser"
   

Config Connector を構成する

インストールを完了するには、ConfigConnector CustomResource の構成ファイルを作成し、kubectl apply コマンドを使用してそれを適用します。Config Connector Operator は、Google Cloud リソースの CRD と Config Connector コンポーネントをクラスタにインストールします。

演算子をクラスタモードとして構成するには、次の手順を行います。

1. 次の YAML ファイルを configconnector.yaml という名前のファイルにコピーします。

   # configconnector.yaml
   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnector
   metadata:
     # the name is restricted to ensure that there is only one
     # ConfigConnector resource installed in your cluster
     name: configconnector.core.cnrm.cloud.google.com
   spec:
     mode: cluster
     googleServiceAccount: "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
     # Setting `stateIntoSpec` to `Absent` is recommended. It means setting `cnrm.cloud.google.com/state-into-spec`
     # annotation to `absent` for all Config Connector resources created in the cluster in the future.
     # It prevents Config Connector from populating unspecified fields into the spec.
     stateIntoSpec: Absent

   次のように置き換えます。
   • SERVICE_ACCOUNT_NAME: サービス アカウントの名前。
   • PROJECT_ID: プロジェクト ID。
2. kubectl apply でクラスタに構成を適用します。

     kubectl apply -f configconnector.yaml

リソースを作成する場所の指定

Config Connector は、プロジェクト、フォルダ、組織ごとにリソースを整理できます。これは、 Google Cloudでリソースを整理する場合と同じ方法です。

Config Connector を使用してリソースを作成する前に、リソースを作成する場所を構成する必要があります。Config Connector は、リソースを作成する場所を決定するために、リソース構成または既存の Namespace のアノテーションを使用します。詳細については、リソースの整理をご覧ください。

この目的の Namespace がない場合は、kubectl を使用して Namespace を作成します。

kubectl create namespace NAMESPACE

NAMESPACE を実際の Namespace 名に置き換えます。例: config-connector

タブを選択して、Config Connector がリソースを作成する場所を選びます。

プロジェクト

特定のプロジェクトにリソースを作成するには、次のコマンドを実行します。

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

以下を置き換えます。

• NAMESPACE は、実際の Namespace 名に置き換えます。
• PROJECT_ID: 実際の Google Cloud プロジェクト ID。

フォルダ

特定のフォルダにリソースを作成するには、次のコマンドを実行します。

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

以下を置き換えます。

• NAMESPACE は、実際の Namespace 名に置き換えます。
• FOLDER_ID: Google Cloud フォルダ ID。

組織

特定の組織にリソースを作成するには、次のコマンドを実行します。

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

以下を置き換えます。

• NAMESPACE は、実際の Namespace 名に置き換えます。
• ORGANIZATION_ID: Google Cloud 組織 ID。

名前空間にアノテーションを付けると、Config Connector は対応するプロジェクト、フォルダ、または組織にリソースを作成します。Config Connector が Kubernetes Namespace を使用する方法の詳細については、Kubernetes Namespace と Google Cloud プロジェクトをご覧ください。

インストールを確認する

Config Connector は、すべてのコンポーネントを cnrm-system という名前の Namespace で実行します。Pod の準備ができていることを確認するには、次のコマンドを実行します。

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

Config Connector が正しくインストールされている場合、出力は次のようになります。

pod/cnrm-controller-manager-0 condition met

注: コントローラ Pod の起動には数分かかることがあります。

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

Config Connector をアンインストールするには、次の手順を実行します。

1. Config Connector CRD とコントローラ コンポーネントを削除するには、次のコマンドを実行します。

   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. Config Connector Operator をアンインストールするには、次のコマンドを実行します。

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

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

最新バージョンの Config Connector Operator をダウンロードしてインストールするには、次のコマンドを実行します。

gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
tar zxvf release-bundle.tar.gz
kubectl apply -f operator-system/configconnector-operator.yaml

Config Connector をダウングレードする

Config Connector の完全なダウングレードはサポートされていません。Config Connector オペレーターと CRD の両方をダウングレードするには、Config Connector をアンインストールして再インストールし、リソースを再適用する必要があります。

Config Connector バージョン 1.123.1 以降では、名前空間モードを使用するインストールのオペレーター バージョンをロールバックできます。ロールバックするオペレーターがある各名前空間で、ConfigConnectorContext オブジェクトの spec.version フィールドを以前の Config Connector バージョンに設定します。

Config Connector コントローラは、最大 3 つのマイナー バージョンまでロールバックできます。特定のマイナー バージョンの最新のパッチ バージョンにロールバックする必要があります。

オペレーター以外のインストールからのアップグレード

Config Connector バージョン 1.33.0 以降では、GKE アドオン、またはオペレーターを使用したインストールのみがサポートされます。

（すべての Config Connector リソースを保持して）オペレーターにアップグレードするには、CRD を除くすべての Config Connector システム コンポーネントを削除してから、オペレーターをインストールする必要があります。

1. 次のコマンドを実行して、CRD 以外の Config Connector システム コンポーネントを削除します。

   kubectl delete sts,deploy,po,svc,roles,clusterroles,clusterrolebindings --all-namespaces -l cnrm.cloud.google.com/system=true --wait=true
   kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
   kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
   kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
   

2. Config Connector を GKE アドオンまたはオペレーターを使用してインストールします。

アドオンから手動インストールに切り替える

アドオンとしてインストールすると、Config Connector のバージョンは、インストールされている GKE のバージョンに直接関連付けられます。

手動インストールでは、手動アップグレードを犠牲にして、より迅速な更新が可能になります。

インストール方法を切り替えてリソースを安全に保持するには、次の手順を行います。

1. ConfigConnector オブジェクトまたは ConfigConnectorContext オブジェクトを削除せずに、アドオンを無効にします。

   gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
   

   CLUSTER_NAME は、Config Connector をインストールしたクラスタの名前に置き換えます。

2. 選択したバージョンの手動オペレーターをインストールします。

   CRD 検証エラー（KNV2009: Invalid value: "v1beta1": must appear in spec.versions など）を回避するには、選択した手動オペレーターのバージョンが、アドオンで使用していたバージョンと同じかそれ以降である必要があります。手動オペレーターのバージョンをダウングレードすると、GKE アドオンが特定の CRD を新しい Config Connector バージョンにアップグレードしている可能性があるため、エラー（KNV2009 など）が発生することがあります。

注: configconnector-operator-system 名前空間内の namespace-id、ConfigMap はアドオンの無効化の一環として削除されるため、古い cnrm-controller-manager、StatefulSets は再作成されます。

次のステップ

• Config Connector を使ってみる。
• Config Connector のベスト プラクティスについて学習する。