kubectl を使用して Config Sync と Policy Controller を手動でインストールする

このページでは、kubectl コマンドを使用して Config Sync と Policy Controller をインストールする方法について説明します。

Config Sync のインストール

Config Management Operator は、Kubernetes クラスタ内の Config Sync を管理するコントローラです。Config Sync を使用して管理する各クラスタで Operator をインストールして構成するには、次の手順を行います。

始める前に

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

ローカル環境の準備

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

  • Config Sync の同期先となる構成ファイルを格納できる Git リポジトリを作成するか、対象リポジトリへのアクセス権を取得します。

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

  • デフォルトでは、kubectl は Cloud SDK によってインストールされません。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 アカウントのメールアドレス

ローカル システムでの gcloud コマンドライン ツールの構成方法によっては、--project フィールドと --zone フィールドを追加する必要があります。

クラスタの登録

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

  1. Operator をデプロイする
  2. Operator に Git への読み取り専用アクセス権を付与する
  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

このコマンドが失敗した場合は、トラブルシューティングをご覧ください。

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

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

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

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

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

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

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

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. ローカル ディスクから秘密鍵を削除するか、秘密鍵を保護します。

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 プロキシまたは HTTP プロキシを使用する必要がある場合は、次のコマンドを実行して、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 \
     --from-literal=http_proxy=HTTP_PROXY_URL
    

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

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

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

トークン

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

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

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

  2. トークンを作成して取得したら、それをクラスタの新しい 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: 前のステップで作成したトークン。
  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] フィールドに追加します。gcloud コマンドライン ツールを使用して Config Sync を構成する場合は、構成ファイルの syncRepo フィールドに URL を追加します。

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

    Workload Identity が有効になっている

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

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

      gcloud コマンドライン ツールを使用して Config Sync を構成する場合は、gcpserviceaccountsecretType として追加し、サービス アカウントのメールアドレスを gcpServiceAccountEmail に追加します。

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

      このバインディングにより、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/root-reconciler]" \
         GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
      

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

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

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

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

    gcloud コマンドライン ツールを使用して Config Sync を構成する場合は、gcenodesecretType として追加します。

    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 の構成

Config Sync の動作を構成するには、ConfigManagement CustomResource の構成ファイルを作成し、kubectl apply コマンドを使用してそれを適用します。

  1. config-management.yaml ファイルを作成して、次の YAML をコピーします。

    # config-management.yaml
    
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      # clusterName is required if you want to use ClusterSelectors and must be
      # unique among all managed clusters
      clusterName: CLUSTER_NAME
      # Enable multi-repo mode to use additional features
      enableMultiRepo: true
    

    CLUSTER_NAME の部分は、この構成を適用する登録済みクラスタの名前に置き換えます。

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

  2. kubectl apply コマンドを使用して構成を適用します。

    kubectl apply -f config-management.yaml
    

    ファイルを適用する際に次のエラーが発生した場合は、インストールに必要な権限が不足している可能性があります。

    Error from server (Forbidden): error when creating "config-management-operator.yaml": clusterroles.rbac.authorization.k8s.io "config-management-operator" is forbidden: attempt to grant extra privileges: [...] ruleResolutionErrors=[]
    

    必要な権限があることを確認するには、権限の準備をご覧ください。

    クラスタごと、またはクラスタのタイプごとに別々の構成ファイルを作成しなければならない場合があります。適用するクラスタを指定するには、--context オプションを使用します。

    kubectl apply -f config-management.yaml --context=KUBE_CONFIG
    

    KUBE_CONFIG は、使用する Kubernetes コンテキストの名前に置き換えます。Kubernetes コンテキストは kubeconfig ファイルに保存されます。

  3. root-sync.yaml ファイルを作成して、次の YAML をコピーします。

    ルート リポジトリから同期を構成するには、ルート リポジトリとクラスタを同期する RootSync オブジェクトを作成する必要があります。詳細については、複数のリポジトリからの同期をご覧ください。

    # root-sync.yaml
    # If you are using a Config Sync version earlier than 1.7,
    # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: root-sync
      namespace: config-management-system
    spec:
      sourceFormat: FORMAT
      git:
        repo: REPO
        branch: BRANCH
        dir: "DIRECTORY"
        auth: TYPE
        secretRef:
          name: SECRET_NAME
        # the `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
        noSSLVerify: SSL_VERIFY
    

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

    • FORMAT: 非構造化リポジトリを使用するには unstructured を追加し、階層型リポジトリを使用するには hierarchy を追加します。この値では大文字と小文字が区別されます。このフィールドは省略可能で、デフォルト値は hierarchy です。unstructured を追加することをおすすめします。この形式では自分にとって最も便利な方法で構成ファイルを整理できます。
    • REPO: 真の同期ソースとして使用する Git リポジトリの URL を追加します。HTTPS または SSH プロトコルを使用して URL を入力できます。たとえば、https://github.com/GoogleCloudPlatform/anthos-config-management-samples では HTTPS プロトコルを使用します。プロトコルを入力しない場合は URL が HTTPS URL として扱われます。このフィールドは必須です。
    • BRANCH: 同期元となるリポジトリのブランチを追加します。デフォルトは、メイン(マスター)ブランチです。
    • DIRECTORY: 同期先の構成を含むルート ディレクトリへの Git リポジトリのパス。デフォルトは、リポジトリのルート ディレクトリです。
    • TYPE: 次のいずれかの SecretTypes を追加します。

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

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

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

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

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

  4. RootSync をクラスタに適用します。

    kubectl apply -f root-sync.yaml
Workload Identity で Cloud Source Repositories を使用する

クラスタで Workload Identity が有効になっており、Google サービス アカウントを認証タイプとして使用している場合は、追加の手順を行う必要があります。

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

このバインディングにより、Config Sync Kubernetes サービス アカウントが Compute Engine のデフォルトのサービス アカウントとして機能します。

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

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

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

バインディングを作成したら、Compute Engine のデフォルト サービス アカウントのメールアドレスを使用して、annotation を Config Sync Kubernetes サービス アカウントに追加します。

kubectl annotate serviceaccount -n config-management-system importer \
    iam.gke.io/gcp-service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

PROJECT_NUMBER は、組織のプロジェクト番号に置き換えます。

Config Sync のインストールを確認する

nomos status コマンドを使用して、Operator が正常にインストールされているかを確認できます。問題のない有効なインストールのステータスは PENDING または SYNCED です。無効なインストール、または不完全なインストールのステータスは NOT INSTALLED または NOT CONFIGURED です。出力には、報告済みのエラーも含まれます。

正常にデプロイされた Operator は、名前が config-management-operator で始まる Pod で実行されます。バージョン 1.9.0 以降の Anthos Config Management では、この Pod は config-management-system 名前空間にあり、それ以前のバージョンでは、kube-system 名前空間にあります。Pod が初期化されるまで少し時間がかかることがあります。

Pod が、バージョン 1.9.0 以降の Anthos Config Management で実行されていることを確認するには:

kubectl -n config-management-system get pods -l k8s-app=config-management-operator

Pod が、1.9.0 より前のバージョンで実行されていることを確認するには:

kubectl -n kube-system get pods -l k8s-app=config-management-operator

Pod が実行されている場合、コマンドのレスポンスは次のようになります(同一ではありません)。

config-management-operator-6f988f5fdd-4r7tr 1/1 Running 0 26s

また、config-management-system 名前空間が存在することを確認することもできます。

kubectl get ns config-management-system

コマンドの出力は次のようになります。

config-management-system Active 1m

コマンドの出力が上記と異なる場合は、次のコマンドを使用してログを表示し、問題の原因を確認します。

kubectl -n kube-system logs -l k8s-app=config-management-operator

kubectl get events を使用して、Config Sync がなんらかのイベントを作成したかどうかを確認することもできます。

kubectl get events -n kube-system

git-creds Secret が欠落している、無効であるなど、すぐに検出されない無効な構成が存在する可能性があります。トラブルシューティングの手順については、トラブルシューティング ページの有効であるが正しくない ConfigManagement オブジェクトをご覧ください。

Config Sync のアップグレード

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

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

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

    kubectl apply -f config-management-operator.yaml
    

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

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

Config Sync のアンインストール

Config Sync をアンインストールするには、config-management.yaml ファイルで Anthos Config Management の構成を編集し、git セクションを削除してクラスタに適用します。

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

Policy Controller のインストール

次の手順では、Policy Controller のインストール方法を説明します。

デフォルトでは、Policy Controller は一般的なポリシータイプの制約テンプレートのライブラリをインストールします。制約テンプレートのインストールをスキップするには、マニフェストの templateLibraryInstalled で始まる行のコメント化を解除します。

  1. Anthos Config Management 構成ファイルspec.policyController オブジェクト内の enabled の値を true に設定します。

    # config-management.yaml
    
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      # Set to true to install and enable Policy Controller
      policyController:
        enabled: true
        # Uncomment to prevent the template library from being installed
        # templateLibraryInstalled: false
        # Uncomment to enable support for referential constraints
        # referentialRulesEnabled: true
        # Uncomment to disable audit, adjust value to set audit interval
        # auditIntervalSeconds: 0
        # Uncomment to log all denies and dryrun failures
        # logDeniesEnabled: true
        # Uncomment to exempt namespaces
        # exemptableNamespaces: ["namespace-name"]
      # ...other fields...
    

    参照制約のサポートは、デフォルトで無効になっています。有効にする前に、結果整合性に関する注意事項を必ず理解してください。

  2. kubectl apply を使用して構成を適用します。

    kubectl apply -f config-management.yaml
    

Policy Controller の確認

Policy Controller が正しくインストールされている場合、その Pod が実行されます。Pod が使用可能になるまでに Pod が数回再起動される場合があります。

Policy Controller Pod は gatekeeper-system 名前空間で実行されるため、次のコマンドを実行してステータスを確認できます。

kubectl get pods -n gatekeeper-system

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

NAME                              READY   STATUS    RESTARTS   AGE
gatekeeper-controller-manager-0   1/1     Running   1          53s

Policy Controller のアンインストール

Policy Controller をアンインストールするには、config-management.yaml ファイルで Anthos Config Management の構成を編集し、policyController.enabledfalse に設定します。Anthos Config Management が policycontroller.configmanagement.gke.io ファイナライザを削除すると、アンインストールは完了です。

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