Anthos Config Management のインストール

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

準備

このセクションでは、サポートされているクラスタを Anthos Config Management に登録する前に満たす必要がある前提条件について説明します。

ローカル環境

  • Anthos Config Management の使用には、有効な Anthos の使用権が必要です。詳細については、Anthos の料金をご覧ください。
  • この手順で使用する gcloudgsutilkubectl コマンドを提供する Cloud SDK をインストールする必要があります。

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

    gcloud components install kubectl
  • nomos コマンドをインストールし、nomos status サブコマンドを使用して、インストールとセットアップ中に問題を検出できるようにします。

  • Anthos Config Management のコンポーネントをダウンロードするには、gcloud auth login コマンドを使用して Google Cloud に認証される必要があります。

  • クラスタに接続するには、kubectl コマンドを構成する必要があります。そのための手順は、GKE クラスタと GKE On-Prem クラスタでは異なります。

  • プロジェクトで Anthos API を有効にする必要があります。

gcloud

Anthos API を有効にするには、次のコマンドを実行します。

gcloud services enable anthos.googleapis.com

コンソール

Anthos API を有効にする

クラスタ

  • クラスタは GKE v1.14.x または Anthos GKE on-prem v1.0.0 以降を実行する必要があります。

  • クラスタは、Connect を使用して Anthos 環境に登録する必要があります。プロジェクトの環境は、Google Cloud 外のクラスタを含む Anthos の一部として、クラスタとそのワークロードを表示して管理するために統合された方法を提供します。Anthos の料金は、登録済みのクラスタにのみ適用されます。 クラスタを登録する方法については、クラスタの登録をご覧ください。

権限

Anthos Config Management をインストールする Google Cloud ユーザーが、クラスタに新しいロールを作成するには、Identity and Access Management(IAM)権限が必要です。

クラスタの登録

Anthos Config Management でクラスタを登録するには:

  1. Operator をデプロイする
  2. Operator に Git への読み取り専用アクセス権を付与する
  3. Operator を構成する

Operator のデプロイ

Google Cloud Console を使用して Config Management Operator をインストールする場合、Operator は自動的にデプロイされます。git-creds Secret を作成するに進みます。

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

  1. 次のコマンドを使用して、Operator CRD の最新バージョンをダウンロードします。最新バーションの代わりに、特定のバージョンをダウンロードするには、ダウンロードをご覧ください。

    gsutil cp gs://config-management-release/released/latest/config-management-operator.yaml config-management-operator.yaml
    
  2. CRD を適用します。

    kubectl apply -f config-management-operator.yaml

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

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

Operator には、Git リポジトリ(リポ)に対する読み取り専用権限が必要です。これにより、Operator はリポジトリに commit されたコンフィグを読み取り、クラスタに適用できるようになります。認証情報が必要な場合は、登録された各クラスタの git-creds Secret に保存されています。

リポジトリで読み取り専用権限に対する認証や許可が不要な場合、git-creds Secret を作成する必要はありません。Anthos Config Management の構成にスキップして、SecretTypenone に設定できます。

ほとんどのユーザーは、リポジトリへの読み取りアクセスが制限されているため、認証情報を作成する必要があります。Anthos Config Management は、次の認証メカニズムをサポートしています。

どちらのメカニズムを選択するかは、リポジトリでサポートされている内容によって決まります。すべてのメカニズムを使用できる場合は、SSH 鍵ペアを使用することをおすすめします。このドキュメントの作成時点で、GitHub、Cloud Source Repositories、Bitbucket はいずれも SSH 鍵ペアの使用をサポートしています。リポジトリが組織でホストされていて、サポートされている認証方法がわからない場合は、管理者に連絡してください。

認証情報を作成したら、それをシークレットとしてクラスタに追加します。Secret の作成方法は、認証方法によって異なります。詳細については、以下の認証方法のセクションをご覧ください。

リポの承認を得る最適な方法を以下のオプションから選択します。選択した方法によって、Operator を構成するときに使用する secretType も決まります。

SSH 鍵ペアの使用

リポに対する承認で SSH 鍵ペアの使用がサポートされている場合は、このセクションの手順に従ってシークレットの材料を作成します。 SSH 鍵ペアの使用がサポートされていない場合は、cookiefile の使用の手順に従ってください。

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

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

    次のコマンドは 4,096 ビットの RSA 鍵を作成します。これよりビット数の少ない鍵はおすすめできません。[GIT REPOSITORY USERNAME]/path/to/[KEYPAIR-FILENAME] は、Operator がリポジトリへの認証に使用する値に置き換えます。GitHub などのサードパーティ Git リポジトリ ホストを使用している場合は、別のアカウントを使用することをおすすめします。Cloud Source Repositories を使用している場合は、サービス アカウントを使用することをおすすめします。

    ssh-keygen -t rsa -b 4096 \
     -C "[GIT REPOSITORY USERNAME]" \
     -N '' \
     -f [/path/to/KEYPAIR-FILENAME]
    
  2. 新しく作成した公開鍵を認識するようにリポを構成します。ご使用の Git ホスティング プロバイダのドキュメントをご覧ください。よく使われる Git ホスティング プロバイダの手順へのリンクを以下に示します。

  3. 秘密鍵をクラスタ内の新しいシークレットに追加します。/path/to/[KEYPAIR-PRIVATE-KEY-FILENAME]は、実際の秘密鍵の名前(.pub 拡張子は付けない)に置き換えます。

    kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/[KEYPAIR-PRIVATE-KEY-FILENAME]
    
  4. ローカル ディスクから秘密鍵を削除するか、秘密鍵を保護します。

cookiefile の使用

リポジトリが認証にSSH 鍵ペアの使用をサポートしていない場合は、cookiefile または Personal Access Token を使用できます。

このセクションの手順に従って、cookiefile Secret マテリアルを作成します。

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

  1. cookiefile を作成して取得したら、それをクラスターの新しい Secret に追加します。/path/to/[COOKIEFILE] は、適切なパスとファイル名に置き換えます。

    kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=cookie_file=/path/to/[COOKIEFILE]
    
  2. cookiefile が引き続きローカルで必要な場合は、cookiefile の内容を保護します。それ以外の場合は cookiefile を削除します。

トークンの使用

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

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

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

    GitHub

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

    Bitbucket

    アプリ パスワードを作成します

  2. トークンを作成して取得したら、それをクラスタの新しい Secret に追加します。[USERNAME] は目的のユーザー名に置き換え、[TOKEN] は前の手順で作成したトークンに置き換えます。

    kubectl create secret generic git-creds \
        --namespace="config-management-system" \
        --from-literal=username=[USERNAME] \
        --from-literal=token=[TOKEN]
    
  3. ローカルでのトークンが必要な場合は、トークンを保護します。それ以外の場合はトークンを削除します。

Google Source Repository での Google サービス アカウントの使用

リポジトリが Google Source Repository にある場合、secretType: gcenode を使用して Anthos Config Management にマネージド クラスタと同じプロジェクト内のリポジトリへのアクセスを許可できます。

開始する前に、次の前提条件を満たしていることを確認してください。

  • クラスタの Compute Engine のデフォルト サービス アカウント PROJECT_NUMBER-compute@developer.gserviceaccount.com には、リポジトリへの source.reader アクセス権が必要です。

    gcloud projects add-iam-policy-binding [PROJECT_ID] \
    --member serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role roles/source.reader
    
  • クラスタ内のノードのアクセス スコープには、cloud-source-repos-ro を含める必要があります。これは、クラスタ作成時に指定された --scopes リストに cloud-source-repos-ro を組み込むか、クラスタの作成時に cloud-platform スコープを使用することで対応できます。

    gcloud container clusters create example-cluster --scopes=cloud-platform
    

これらの前提条件が満たされたら、Operator を構成するときに、目的の Google ソース リポジトリの URL に spec.git.syncRepo を設定します。例:

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

次のことが必要になります。

spec.git.syncRepo: https://source.developers.google.com/p/my-project/r/my-repo-csr
Workload Identity での Google Source Repository の使用

クラスタで Workload Identity が有効になっている場合、secretType: gcenode を使用するには追加の手順が必要です。上記の手順を完了したら、Kubernetes サービスアカウントと Google サービスアカウントの間にIAM ポリシー バインディングを作成します。このバインディングにより、Anthos Config Management 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

最後に、Compute Engine のデフォルト サービス アカウントのメールアドレスを使用して、annotation を Anthos Config Management Kubernetes サービス アカウントに追加します。

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

認証を使用しない場合

リポジトリで読み取り専用権限に対する認証が不要な場合、Operator の構成に進み、spec.git.secretTypenone に設定します。

Operator の構成

kubectl または Google Cloud Console を使用して、クラスタの Operator を構成できます。

kubectl

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

たとえば、ファイル config-management.yaml を作成し、次の YAML ファイルをコピーします。

# config-management.yaml

apiVersion: configmanagement.gke.io/v1
kind: ConfigManagement
metadata:
  name: config-management
spec:
  # clusterName is required and must be unique among all managed clusters
  clusterName: my-cluster
  git:
    syncRepo: git@github.com:my-github-username/csp-config-management.git
    syncBranch: 1.0.0
    secretType: ssh
    policyDir: "foo-corp"

spec フィールドに追加できるフィールドの完全なリストについては、次の Git リポジトリの構成セクションをご覧ください。spec フィールド以外の構成の値を変更しないでください。

構成を適用するには、kubectl apply コマンドを使用します。

kubectl apply -f config-management.yaml

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

kubectl apply -f config-management1.yaml --context=cluster-1
Git リポジトリの構成
キー 説明
spec.git.syncRepo 真の情報源として使用する Git リポジトリの URL。必須。
spec.git.syncBranch 同期元となるリポジトリのブランチ。デフォルト: master
spec.git.policyDir 同期するリポの最上位レベルを表す Git リポジトリ内のパス。デフォルトはリポジトリのルート ディレクトリです。
spec.git.syncWait 連続する同期の時間間隔(秒)。デフォルトは 15 です。
spec.git.syncRev チェックアウトする Git リビジョン(タグまたはハッシュ)。デフォルトは HEAD です。
spec.git.secretType Git リポジトリへのアクセスのために構成されたシークレットのタイプ。sshcookiefiletokengcenodenone のいずれかです。必須。
spec.sourceFormat unstructured に設定すると、非階層リポジトリを構成します。デフォルト: hierarchy
Git リポジトリのプロキシ構成

組織のセキュリティ ポリシーでトラフィックを HTTP(S)プロキシ経由でルーティングする必要がある場合は、プロキシの URI を使用して Git ホストと通信できます。

説明
spec.git.proxy.httpProxy httpProxy は、Git リポジトリへのアクセスに使用される HTTP_PROXY 環境変数を定義します。
spec.git.proxy.httpsProxy httpsProxy は、Git リポジトリへのアクセスに使用する HTTPS_PROXY 環境変数を定義します。

httpProxy フィールドと httpsProxy フィールドの両方が指定されている場合、httpProxy は無視されます。

ConfigManagement オブジェクトの動作に関する構成
キー 説明
spec.clusterName クラスタをグループ化するために ClusterSelector によって使用される、クラスタのユーザー定義名。Anthos Config Management のインストール内で一意にする必要があります。
統合の構成

これらのフィールドにより、Config Connector および Policy Controller との統合が可能になります。

説明
spec.configConnector.enabled true の場合、Config Connector をインストールします。デフォルトは false です。
spec.policyController.enabled true の場合、Policy Controller を有効にします。デフォルトは false です。
spec.policyController.templateLibraryInstalled true の場合、制約テンプレート ライブラリをインストールします。デフォルトは true です。

コンソール

制限事項

Google Cloud Console で Anthos Config Management を構成する場合は、次の制限があります。

  • 以下をインストールまたは構成することはできません。
    • Policy Controller
    • コネクタの構成
    • Hierarchy Controller
  • サポートされているのは Config Sync 構成オプションのサブセットのみです。サポートされていない Config Sync 構成は次のとおりです。
    • spec.git.proxy
    • spec.git.secretType: gcenode
    • spec.git.secretType: token
    • spec.sourceFormat

これらのオプションを使用する場合は、Cloud Console を使用しないでください。

Operator の構成

Cloud Console で Operator を構成するには、次の手順に従います。

  1. Google Cloud Console の Anthos Config Management メニューにアクセスします。

    Anthos Config Management メニューに移動

  2. 登録済みクラスタを選択して、[構成] をクリックします。

  3. [ACM の Git リポジトリ認証] セクションで、次の操作を行います。

    1. [Secret の種類] で、次のいずれかを選択します。

      • なし。読み取り専用権限に対してリポジトリが認証を必要としないかどうかを選択します。
      • SSH
      • cookiefile

      token または gcenode を選択する場合は、kubectl を使用して Operator を構成します。

    2. [続行] をクリックします。

  4. [クラスタ用の ACM 設定] セクションで、次の操作を行います。

    1. [URL] フィールドに、信頼できる情報源として使用する Git リポジトリの URL を追加します。この欄は必須です。
    2. [ブランチ] フィールドに、同期元のリポジトリのブランチを追加します。デフォルトはマスターです。この欄は必須です。
    3. [タグ / commit] で、Git のリビジョン(タグまたはハッシュ)を追加してチェックアウトします。デフォルトは HEAD です。
    4. [詳細設定を表示] をクリックします。
    5. [ポリシーのディレクトリ] フィールドで、同期対象のポリシー階層の最上部にリポジトリ内のパスを追加します。デフォルトは、リポジトリのルート ディレクトリです。
    6. [同期の待機時間] フィールドで、連続する同期の時間間隔を秒単位で追加します。デフォルト値は 15 秒です。
  5. [完了] をクリックします。Anthos Config Management メニューに戻ります。数分後、ページを更新すると、構成したクラスタの横の [ステータス] 列に Synced と表示されます。

インストールの確認

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

正常にデプロイされた Operator は、kube-system 名前空間内の名前が config-management-operator で始まる Pod で実行されます。Pod が初期化されるまで少し時間がかかることがあります。Pod が実行されていることを確認するには、次のコマンドを使用します。

kubectl -n kube-system get pods | grep config-management

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

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

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

kubectl get ns | grep 'config-management-system'

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

config-management-system Active 1m

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

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

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

kubectl get events -n kube-system

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

トラブルシューティング

不十分な CPU

kubectl get events の出力には、タイプが FailedScheduling のイベントが含まれる場合があります。このイベントは次のようになります。

LAST SEEN   TYPE      REASON              OBJECT                                             MESSAGE
9s          Warning   FailedScheduling    pod/config-management-operator-74594dc8f6    0/1 nodes are available: 1 Insufficient cpu.

このエラーを修正するには、次のいずれかを行う必要があります。

  • 既存の GKE ノードプールにノードを追加する。
  • または、より大きなノードでノードプールを作成する。

エラー: 追加の権限を付与しようとしている

kubectl apply -f config-management-operator.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=[]

このエラーは、現在のユーザーの持つ権限が、インストールに必要な権限より低いことを示します。GKE での役割ベースのアクセス制御の前提条件セクションをご覧ください。

有効であるが正しくない ConfigManagement オブジェクト

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

問題のない有効なインストールのステータスは、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 を作成すると Operator で即時にそれが検出されるため、構成を再適用する必要はありません。

アップグレード

このセクションでは、現在のバージョンにアップグレードする一般的な手順を説明します。 アップグレードを行う前に、リリースノートで具体的な手順をご確認ください。

登録されているクラスタごとに、これらのコマンドを実行します。

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

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

    kubectl apply -f config-management-operator.yaml
    

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

  3. すべてのクライアントの nomos または nomos.exe コマンドを新しいバージョンに置き換えます。これにより、nomos コマンドによって、登録されたすべてのクラスタのステータスを確実に取得し、それらのコンフィグを検証できるようになります。

クラスタからの Operator のアンインストール

クラスタから Operator をアンインストールするには、次の手順に従ってください。Anthos Config Management を使用して管理する必要がなくなったクラスタごとに、これらの手順を行う必要があります。

  1. クラスタから ConfigManagement オブジェクトを削除します。

    kubectl delete configmanagement --all

    このコマンドを実行すると、次のことが起こります。

    • Anthos Config Management によってクラスタに作成された ClusterRole と ClusterRoleBinding がクラスタからすべて削除されます。
    • Anthos Config Management によってインストールされたアドミッション コントローラの構成がすべて削除されます。
    • config-management-system 名前空間の内容は、git-creds Secret を除いてすべて削除されます。Anthos Config Management は、config-management-system 名前空間なしでは機能しません。Anthos Config Management によって作成または変更された CustomResourceDefinition は、それらが作成または変更されたクラスタからすべて削除されます。Operator の実行に必要な CustomResourceDefinition(CRD)は、Kubernetes の観点からは Operator をインストールしたユーザーが追加したものとみなされるため、削除されずに残ります。これらを削除する方法については、次のステップで説明します。
  2. この時点で、Operator はまだクラスタに存在しますが、何も行いません。GKE On-Prem を使用している場合、Operator を手動で削除することはできません。

    GKE を使用していて、Anthos Config Management を今後まったく使用しない場合は、次の手順に従って Operator をアンインストールできます。

    1. 前の手順で ConfigManagement オブジェクトを削除した後、config-management-system 名前空間が空であることを確認します。kubectl -n config-management-system get all コマンドによって No resources found. が返されるまで待ちます。

    2. config-management-system 名前空間を削除します。

      kubectl delete ns config-management-system
      
    3. ConfigManagement CustomResourceDefinition を削除します。

      kubectl delete crd configmanagements.configmanagement.gke.io
      
    4. kube-system 名前空間からすべての Anthos Config Management オブジェクトを削除します。

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

次のステップ

  • Anthos Config Management を構成するための gcloud コマンドについて学習する。