Kubernetes用エージェントをインストールする

KubernetesクラスターをGitLabに接続するには、クラスターにエージェントをインストールする必要があります。

前提要件

クラスターにエージェントをインストールする前に必要な項目は以下のとおりです:

• ローカルターミナルから接続できる既存のKubernetesクラスター。クラスターがない場合は、以下のようなクラウドプロバイダーで作成できます:
  • Amazon Elastic Kubernetes Service（EKS）
  • Azure Kubernetes Service（AKS）
  • Digital Ocean
  • Google Kubernetes Engine（GKE）
  • インフラストラクチャリソースを大規模管理するには、Infrastructure as Codeの手法を使用する必要があります。
• エージェントサーバーへのアクセス:
  • GitLab.comでは、エージェントサーバーはwss://kas.gitlab.comで利用できます。
  • GitLab Self-Managedでは、GitLab管理者がエージェントサーバーをセットアップする必要があります。その後、wss://gitlab.example.com/-/kubernetes-agent/でデフォルトで使用できます。
  • GitLab Dedicatedでは、エージェントサーバーはwss://kas.<instance-domain>で利用できます（例: wss://kas.example.gitlab-dedicated.com）。GitLab Dedicatedインスタンスにカスタムホスト名を使用している場合は、KASサービスにカスタムホスト名を選択することもできます。

Fluxサポートでエージェントをブートストラップする（推奨）

GitLab CLI（glab）とFluxでブートストラップすることにより、エージェントをインストールできます。

前提要件:

• 以下のコマンドラインツールがインストールされている必要があります:
  • glab
  • kubectl
  • flux
• kubectlおよびfluxで動作するローカルクラスター接続が必要です。
• 事前にflux bootstrapでFluxをクラスターにブートストラップしておく必要があります。
  • 互換性のあるディレクトリにFluxとエージェントをブートストラップしてください。--pathオプションでFluxをブートストラップした場合は、glab cluster agent bootstrapコマンドの--manifest-pathオプションに同じ値を渡す必要があります。

エージェントをインストールするには、次のいずれかの方法を実行します:

• glab cluster agent bootstrapを対象プロジェクトのGitリポジトリのディレクトリ内で実行します:

  glab cluster agent bootstrap <agent-name> --manifest-path <same_path_used_in_flux_bootstrap>

• コマンドを対象プロジェクトのGitリポジトリ外で実行する必要がある場合は、glab -R path-with-namespace cluster agent bootstrapを実行します:

  glab -R <full/path/to/project> cluster agent bootstrap <agent-name> --manifest-path <same_path_used_in_flux_bootstrap>

デフォルトでは、コマンドは以下の動作を行います:

1. エージェントを登録します。
2. エージェントを設定します。
3. エージェントのダッシュボードで環境を設定します。
4. エージェントトークンを作成します。
5. クラスター内に、エージェントトークンでKubernetesシークレットを作成します。
6. Flux HelmリソースをGitリポジトリにコミットします。
7. Fluxの調整をトリガーします。

カスタマイズオプションについては、glab cluster agent bootstrap --helpを実行してください。少なくとも--path <flux_manifests_directory>オプションを使用することをお勧めします。

手動でエージェントをインストールする

クラスターにエージェントをインストールするには、3つのステップが必要です:

1. オプション。エージェント設定ファイルを作成します。
2. GitLabにエージェントを登録します。
3. クラスターにエージェントをインストールします。

このプロセスのウォークスルーをご覧ください。

エージェント設定ファイルを作成する

設定については、エージェントはGitLabプロジェクトのYAMLファイルを使用します。エージェント設定ファイルの追加は任意です。このファイルは、以下の場合に作成する必要があります:

• GitLab CI/CDワークフローを使用していて、別のプロジェクトまたはグループにエージェントへのアクセスを承認する場合。
• 特定のプロジェクトまたはグループメンバーにKubernetesへのアクセスを許可する場合。

エージェント設定ファイルを作成するには:

1. エージェントの名前を選択します。エージェント名は、RFC 1123のDNSラベル標準に従います。名前は以下の条件を満たす必要があります:

   • プロジェクト内で一意である。
   • 含める文字は最大63字である。
   • 小文字の英数字または-のみを含む。
   • 英数字で始まる。
   • 英数字で終わる。

2. リポジトリのデフォルトブランチで、次の場所にエージェント設定ファイルを作成します:

   .gitlab/agents/<agent-name>/config.yaml

当面ファイルは空白のままにしておき、後で設定することもできます。

GitLabにエージェントを登録する

オプション1: エージェントがGitLabに接続する

GitLab UIから直接新しいエージェントレコードを作成できます。エージェント設定ファイルを作成せずにエージェントを登録できます。

クラスターにエージェントをインストールする前に、エージェントを登録する必要があります。エージェントを登録するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。エージェント設定ファイルがある場合、このプロジェクトに存在する必要があります。クラスターマニフェストファイルもこのプロジェクトに存在する必要があります。

2. 操作 > Kubernetesクラスターを選択します。

3. **クラスターに接続(エージェント)**を選択します。

4. 新しいエージェント名フィールドに、エージェントの一意の名前を入力します。

   • この名前のエージェント設定ファイルがすでに存在する場合、その名前が使用されます。
   • この名前の設定が存在しない場合は、デフォルトの設定で新しいエージェントが作成されます。

5. 作成して登録を選択します。

6. GitLabは、エージェントのアクセストークンを生成します。クラスターにエージェントをインストールするには、このトークンが必要です。

   エージェントアクセストークンは安全な状態で保管してください。悪意のある第三者がこのトークンを使用して、エージェントの設定プロジェクトのソースコードにアクセスする、GitLabインスタンス上の任意のパブリックプロジェクトのソースコードにアクセスする、ごく特定の条件下でKubernetesマニフェストを取得するなどの可能性があります。

7. Recommended installation method（推奨されるインストール方法）の下にあるコマンドをコピーします。これは、ワンライナーインストールメソッドを使用してクラスターにエージェントをインストールする場合に必要になります。

オプション2: GitLabがエージェント（受容エージェント）に接続する

受容エージェントを使用すると、GitLabインスタンスへのネットワーク接続を確立できないがGitLabからは接続できるKubernetesクラスターと、GitLabを統合できます。

1. オプション1の手順に従って、クラスターにエージェントを登録します。エージェントトークンとインストールコマンドを後で使用するために保存します。ただし、まだエージェントはインストールしないでください。

2. 認証方法を準備します。

   GitLabからエージェントへの接続には、プレーンテキストのgRPC（grpc://）または暗号化されたgRPC（grpcs://、推奨）を使用できます。GitLabは、次の方法を使用してクラスター内のエージェントを認証できます:

   • JWTトークン。grpc://とgrpcs://の両方の設定で使用できます。この方法では、クライアント証明書を生成する必要はありません。

3. クラスターエージェントAPIを使用して、エージェントにURL設定を追加します。URL設定を削除すると、受容エージェントは通常のエージェントになります。受容エージェントは、一度に1つのURL設定のみに関連付けることができます。

4. エージェントをクラスターにインストールします。エージェントの登録時にコピーしたコマンドを使用しますが、--set config.kasAddress=...パラメータは削除します。

   JWTトークン認証の例を示します。追加されたconfig.receptive.enabled=trueおよびconfig.api.jwtの設定に注意してください:

   helm repo add gitlab https://charts.gitlab.io
   helm repo update
   helm upgrade --install my-agent gitlab/gitlab-agent \
    --namespace ns \
    --create-namespace \
    --set config.token=.... \
    --set config.receptive.enabled=true \
    --set config.api.jwtPublicKey=<public_key from the response>

GitLabが新しいエージェントへの接続の確立を試行するまでに、最大10分かかる場合があります。

エージェントをクラスターにインストールする

クラスターをGitLabに接続するには、Helmで登録済みのエージェントをインストールします。

受容エージェントをインストールするには、GitLabがエージェント（受容エージェント）に接続するの手順に従います。

Helmでエージェントをインストールする

Helmを使用してクラスターにエージェントをインストールするには:

1. Helm CLIをインストールします。

2. コンピューターでターミナルを開き、クラスターに接続します。

3. GitLabへのエージェント登録時にコピーしたコマンドを実行します。コマンドは次のようになります:

   helm repo add gitlab https://charts.gitlab.io
   helm repo update
   helm upgrade --install test gitlab/gitlab-agent \
       --namespace gitlab-agent-test \
       --create-namespace \
       --set image.tag=<current agentk version> \
       --set config.token=<your_token> \
       --set config.kasAddress=<address_to_GitLab_KAS_instance>

4. オプション。Helmインストールをカスタマイズします。本番環境システムにエージェントをインストールする場合は、Helmインストールをカスタマイズして、サービスアカウントの権限を制限する必要があります。以下で関連するカスタマイズオプションについて説明します。

Helmインストールをカスタマイズする

デフォルトでは、GitLabによって生成されたHelmインストールコマンドになります:

• デプロイメント用のネームスペースgitlab-agentを作成します（--namespace gitlab-agent）。--create-namespaceフラグを省略すると、ネームスペースの作成をスキップできます。
• エージェントのサービスアカウントを設定し、cluster-adminロールを割り当てます。次のコマンドを実行できます:
  • --set serviceAccount.create=falseをhelm installコマンドに追加して、サービスアカウントの作成をスキップします。この場合、serviceAccount.nameを既存のサービスアカウントに設定する必要があります。
  • --set rbac.useExistingRole <your role name>をhelm installコマンドに追加して、サービスアカウントに割り当てられたロールをカスタマイズします。この場合、サービスアカウントで使用可能な制限付き権限を持つ、事前作成済みのロールが必要です。
  • --set rbac.create=falseをhelm installコマンドに追加して、ロールの割り当てをすべてスキップします。この場合、ClusterRoleBindingを手動で作成する必要があります。
• エージェントのアクセストークン用のSecretリソースを作成します。トークン付きの独自のシークレットを使用する場合は、トークン（--set token=...）を省略して、その代わりに--set config.secretName=<your secret name>を使用します。
• agentkポッドのDeploymentリソースを作成します。

利用可能なカスタマイズの完全なリストについては、HelmチャートのREADMEを参照してください。

KASが自己署名証明書の背後にあるときにエージェントを使用する

KASが自己署名証明書の背後にある場合、config.kasCaCertの値を証明書に設定できます。例:

helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --set-file config.kasCaCert=my-custom-ca.pem

この例では、my-custom-ca.pemはKASで使用されるCA証明書を含むローカルファイルへのパスになっています。証明書は、設定マップに自動的に保存され、agentkポッドにマウントされます。

GitLabチャートでKASをインストールする場合、チャートが自動生成された自己署名ワイルドカード証明書を提供するように設定されていると、RELEASE-wildcard-tls-caシークレットからCA証明書を抽出できます。

HTTPプロキシの背後でエージェントを使用する

Helmチャートの使用時にHTTPプロキシを設定する際には、環境変数HTTP_PROXY、HTTPS_PROXY、およびNO_PROXYを使用できます。大文字と小文字の両方を使用できます。

これらの変数は、extraEnv値をnameおよびvalueのキーを持つオブジェクトのリストとして使用することで設定できます。たとえば、環境変数HTTPS_PROXYの値のみをhttps://example.com/proxyに設定するには、次のコマンドを実行します:

helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --set extraEnv[0].name=HTTPS_PROXY \
  --set extraEnv[0].value=https://example.com/proxy \
  ...

クラスターに複数のエージェントをインストールする

クラスターに2番目のエージェントをインストールするには、前の手順を再度実行します。クラスター内のリソース名の衝突を回避するには、次のいずれかを実行する必要があります:

• エージェントに別のリリース名を使用します（例: second-gitlab-agent）:

  helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ...

• または、エージェントを別のネームスペースにインストールします（例: different-namespace）:

  helm upgrade --install gitlab-agent gitlab/gitlab-agent \
    --namespace different-namespace \
    ...

クラスター内の各エージェントは独立して実行されるため、Fluxモジュールが有効になっているすべてのエージェントが調整をトリガーします。イシュー357516では、この動作を変更することを提案しています。

次の回避策を取ることができます:

• エージェントでRBACを設定し、エージェントに必要なFluxリソースのみにアクセスするようにします。
• Fluxモジュールを使用しないエージェントのFluxモジュールを無効化します。

プロジェクトの例

次のプロジェクトの例は、エージェントの使用を開始するのに役立ちます。

• 固有のアプリケーションおよびマニフェストリポジトリの例
• CI/CDワークフローを使用するAuto DevOps設定
• CI/CDワークフローを使用するクラスター管理プロジェクトテンプレートの例

更新とバージョンの互換性

GitLabは、エージェントのリストページで、クラスターにインストールされているエージェントバージョンを更新するように警告します。

ベストな操作性を実現するには、クラスターにインストールされているエージェントのバージョンが、GitLabのメジャーバージョンおよびマイナーバージョンと一致する必要があります。以前のマイナーバージョンや次期のマイナーバージョンもサポートされています。たとえば、GitLabのバージョンがv14.9.4（メジャーバージョン14、マイナーバージョン9）の場合、エージェントのバージョンはv14.9.0およびv14.9.1であるのが理想的ですが、バージョンがv14.8.xまたはv14.10.xのエージェントもサポートされています。the release page（GitLabエージェントfor Kubernetesのリリースページ）を参照してください。

エージェントバージョンを更新する

エージェントを最新バージョンに更新するには、次のコマンドを実行します:

helm repo update
helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --namespace gitlab-agent

特定のバージョンを設定する場合、image.tag値をオーバーライドできます。たとえば、バージョンv14.9.1をインストールする場合は、次のコマンドを実行します:

helm upgrade gitlab-agent gitlab/gitlab-agent \
  --namespace gitlab-agent \
  --set image.tag=v14.9.1

HelmチャートはKubernetesのエージェントとは別に更新されるため、エージェントの最新バージョンより更新が遅れる場合があります。helm repo updateの実行時にイメージタグ付けを指定しない場合、エージェントはチャートで指定されたバージョンを実行します。

Kubernetes用エージェントの最新リリースを使用するには、イメージタグ付けを最新のエージェントイメージと一致するように設定します。

エージェントをアンインストールする

Helmでエージェントをインストールした場合、Helmでアンインストールすることもできます。たとえば、リリースとネームスペースがいずれもgitlab-agentという名前の場合、次のコマンドでエージェントをアンインストールできます:

helm uninstall gitlab-agent \
    --namespace gitlab-agent

トラブルシューティング

Kubernetes用エージェントのインストール時に、次のイシューが発生することがあります。

エラー: failed to reconcile the GitLab Agent

glab cluster agent bootstrapコマンドが失敗し、failed to reconcile the GitLab Agentというメッセージが表示された場合、これはglabがFluxでエージェントを調整できなかったことを意味します。

このエラーについては次のような原因が考えられます:

• Fluxのセットアップで、glabがエージェント用のFluxマニフェストを配置したディレクトリを指していない。--pathオプションでFluxをブートストラップした場合は、glab cluster agent bootstrapコマンドの--manifest-pathオプションに同じ値を渡す必要があります。
• Fluxがkustomization.yamlのないプロジェクトのルートディレクトリを指しているため、サブディレクトリを走査してYAMLファイルを検索している。エージェントを使用するには、.gitlab/agents/<agent-name>/config.yamlにエージェント設定ファイルが必要ですが、これは有効なKubernetesmanifestではありません。そのためFluxはこのファイルの適用に失敗し、エラーが発生します。これを解決するには、Fluxにルートではなくサブディレクトリを指定する必要があります。