KubernetesクラスターでGitLab CI/CDを使用する

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

GitLab CI/CDを使用して、Kubernetesクラスターに安全に接続、デプロイ、および更新できます。

そのためには、クラスターにエージェントをインストールします。完了すると、Kubernetesコンテキストが作成され、GitLab CI/CDパイプラインでKubernetes APIコマンドを実行できます。

クラスターへのアクセスを安全にするには:

各エージェントには、個別のコンテキスト(kubecontext)があります。
エージェントが設定されているプロジェクトと、承認した追加のプロジェクトのみが、クラスター内のエージェントにアクセスできます。

GitLab CI/CDを使用してクラスターとやり取りするには、RunnerをGitLabに登録する必要があります。ただし、これらのRunnerは、エージェントが存在するクラスター内にある必要はありません。

前提要件:

GitLab CI/CDが有効になっていることを確認してください。

クラスターでGitLab CI/CDを使用する

GitLab CI/CDを使用してKubernetesクラスターを更新するには:

Kubernetesクラスターが動作しており、マニフェストがGitLabプロジェクトにあることを確認します。
同じGitLabプロジェクトで、Kubernetes向けGitLabエージェントを登録してインストールします。
.gitlab-ci.ymlファイルを更新して、エージェントのKubernetesコンテキストを選択し、Kubernetes APIコマンドを実行します。
パイプラインを実行して、クラスターにデプロイするか、クラスターを更新します。

Kubernetesマニフェストを含む複数のGitLabプロジェクトがある場合:

独自のGitLabプロジェクトで、またはKubernetesマニフェストを保持するGitLabプロジェクトの1つでKubernetes向けGitLabエージェントをインストールします。
GitLabプロジェクトでエージェントアクセスを承認します。
オプション。セキュリティを強化するには、代理を使用します。
.gitlab-ci.ymlファイルを更新して、エージェントのKubernetesコンテキストを選択し、Kubernetes APIコマンドを実行します。
パイプラインを実行して、クラスターにデプロイするか、クラスターを更新します。

エージェントアクセスを承認する

複数のプロジェクトにKubernetesマニフェストがある場合は、これらのプロジェクトがエージェントにアクセスできるように承認する必要があります。個々のプロジェクト、グループ、またはサブグループに対してエージェントアクセスを承認し、すべてのプロジェクトがアクセスできるようにすることができます。セキュリティを強化するために、代理を使用することもできます。

認証設定が反映されるまでに1 - 2分かかることがあります。

エージェントにアクセスするようにプロジェクトを承認する

Kubernetesマニフェストを保持するGitLabプロジェクトに、エージェントへのアクセスをを承認するには:

左側のサイドバーで、検索または移動先を選択して、エージェント設定ファイル(config.yaml)を含むプロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
config.yamlファイルを編集します。ci_accessキーワードの下に、projects属性を追加します。
idには、プロジェクトへのパスを追加します。
```
ci_access:
  projects:
    - id: path/to/project
```
- インスタンスレベルの承認アプリケーション設定が有効になっていない限り、承認されたプロジェクトは、エージェントの設定プロジェクトと同じトップレベルグループまたはユーザーネームスペースを持っている必要があります。
- 追加の階層に対応するために、同じクラスターに追加のエージェントをインストールできます。
- 最大500個のプロジェクトを承認できます。

これらの変更を行った後:

すべてのCI/CDジョブに、すべての共有エージェント接続のコンテキストを含むkubeconfigファイルが含まれるようになりました。
kubeconfigパスは、$KUBECONFIG環境変数で使用できます。
CI/CDスクリプトからkubectlコマンドを実行するコンテキストを選択します。

エージェントにアクセスするようグループ内のプロジェクトを承認する

エージェントにアクセスするようにグループまたはサブグループ内のすべてのGitLabプロジェクトを承認するには:

左側のサイドバーで、検索または移動先を選択して、エージェント設定ファイル(config.yaml)を含むプロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
config.yamlファイルを編集します。ci_accessキーワードの下に、groups属性を追加します。
idには、パスを追加します:
```
ci_access:
  groups:
    - id: path/to/group/subgroup
```
- インスタンスレベルの承認アプリケーション設定が有効になっていない限り、承認されたグループは、エージェントの設定プロジェクトと同じトップレベルグループを持っている必要があります。
- 追加の階層に対応するために、同じクラスターに追加のエージェントをインストールできます。
- 承認されたグループのすべてのサブグループも、（個別に指定されなくても）同じエージェントにアクセスできます。
- 最大500個のグループを承認できます。

これらの変更を行った後:

グループとそのサブグループに属するすべてのプロジェクトが、エージェントにアクセスできるようになりました。
すべてのCI/CDジョブに、すべての共有エージェント接続のコンテキストを含むkubeconfigファイルが含まれるようになりました。
kubeconfigパスは、$KUBECONFIG環境変数で使用できます。
CI/CDスクリプトからkubectlコマンドを実行するコンテキストを選択します。

エージェントにアクセスするようGitLabインスタンス内のすべてのプロジェクトを承認する

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

前提要件:

管理者である必要があります。

GitLabインスタンス内のすべてのプロジェクトを承認するようにエージェントを設定できるようにするには:

管理者エリアで、設定 > 一般を選択し、GitLab Agent for Kubernetesセクションを展開します。
インスタンスレベルの認証を有効にするを選択します。
変更を保存を選択します。

アプリケーション設定を更新して、organization_cluster_agent_authorization_enabledをtrueにします。

すべてのGitLabプロジェクトにアクセスするようにエージェントを承認するには:

左側のサイドバーで、検索または移動先を選択して、エージェント設定ファイル(config.yaml)を含むプロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
config.yamlファイルを編集します。ci_accessキーワードの下に、instance属性を追加します:
```
ci_access:
  instance: {}
```

エージェント設定ファイルにこれらの変更を加えた後:

お使いのインスタンス内のすべてのプロジェクトのすべてのCI/CDジョブは、エージェントへのアクセスを承認されています。必要に応じて、RBACでCI/CDジョブの代理を使用して、アクセスを許可または制限できます。詳細については、Restrict project and group access by using impersonation（代理を使用したプロジェクトおよびグループアクセス制限）を参照してください。
すべてのCI/CDジョブに、すべての共有エージェント接続のコンテキストを含むkubeconfigファイルが含まれるようになりました。
kubeconfigパスは、$KUBECONFIG環境変数で使用できます。
CI/CDスクリプトからkubectlコマンドを実行するコンテキストを選択します。

`.gitlab-ci.yml`ファイルを更新して`kubectl`コマンドを実行する

Kubernetesコマンドを実行するプロジェクトで、プロジェクトの.gitlab-ci.ymlファイルを編集します。

scriptキーワードの下の最初のコマンドで、エージェントのコンテキストを設定します。<path/to/agent/project>:<agent-name>形式を使用します。次に例を示します:

deploy:
  image: debian:13-slim
  variables:
    KUBECTL_VERSION: v1.34
    DEBIAN_FRONTEND: noninteractive
  script:
    # Follows https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#install-using-native-package-management
    - apt-get update
    - apt-get install -y --no-install-recommends apt-transport-https ca-certificates curl gnupg
    - curl --fail --silent --show-error --location "https://pkgs.k8s.io/core:/stable:/${KUBECTL_VERSION}/deb/Release.key" | gpg --dearmor --output /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    - chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    - echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/${KUBECTL_VERSION}/deb/ /" | tee /etc/apt/sources.list.d/kubernetes.list
    - chmod 644 /etc/apt/sources.list.d/kubernetes.list
    - apt-get update
    - apt-get install -y --no-install-recommends kubectl
    - kubectl config get-contexts
    - kubectl config use-context path/to/agent/project:agent-name
    - kubectl get pods

エージェントのコンテキストが不明な場合は、エージェントにアクセスするCI/CDジョブからkubectl config get-contextsを実行します。

Auto DevOpsを使用する環境

Auto DevOpsが有効になっている場合は、CI/CD変数KUBE_CONTEXTを定義する必要があります。Auto DevOpsで使用するエージェントのコンテキストにKUBE_CONTEXTの値を設定します:

deploy:
  variables:
    KUBE_CONTEXT: path/to/agent/project:agent-name

異なるエージェントを別々のAuto DevOpsジョブに割り当てることができます。インスタンスのために、Auto DevOpsでは、stagingジョブに1つのエージェントを使用し、productionジョブに別のエージェントを使用できます。複数のエージェントを使用するには、各エージェントに環境スコープのCI/CD変数を定義します。次に例を示します:

KUBE_CONTEXTという名前の2つの変数を定義します。
最初の変数:
1. environmentをstagingに設定します。
2. 値をステージングエージェントのコンテキストに設定します。
2番目の変数:
1. environmentをproductionに設定します。
2. 値を本番環境エージェントのコンテキストに設定します。

証明書ベースの接続とエージェントベースの接続の両方を使用する環境

証明書ベースのクラスター（非推奨）とエージェント接続の両方がある環境にデプロイする場合:

証明書ベースのクラスターのコンテキストはgitlab-deployと呼ばれます。このコンテキストは、デフォルトで常に選択されます。
エージェントのコンテキストは$KUBECONFIGに含まれています。それらはkubectl config use-context <path/to/agent/project>:<agent-name>を使用して選択できます。

証明書ベースの接続が存在する場合にエージェント接続を使用するには、新しいkubectl設定コンテキストを手動で設定できます。次に例を示します:

deploy:
  variables:
    KUBE_CONTEXT: my-context # The name to use for the new context
    AGENT_ID: 1234 # replace with your agent's numeric ID
    K8S_PROXY_URL: https://<KAS_DOMAIN>/k8s-proxy/ # For agent server (KAS) deployed in Kubernetes cluster (for gitlab.com use kas.gitlab.com); replace with your URL
    # K8S_PROXY_URL: https://<GITLAB_DOMAIN>/-/kubernetes-agent/k8s-proxy/ # For agent server (KAS) in Omnibus
    # Include any additional variables
  before_script:
    - kubectl config set-credentials agent:$AGENT_ID --token="ci:${AGENT_ID}:${CI_JOB_TOKEN}"
    - kubectl config set-cluster gitlab --server="${K8S_PROXY_URL}"
    - kubectl config set-context "$KUBE_CONTEXT" --cluster=gitlab --user="agent:${AGENT_ID}"
    - kubectl config use-context "$KUBE_CONTEXT"
  # Include the remaining job configuration

自己署名証明書を使用するKASを使用する環境

KASを使用する環境と自己署名証明書を使用する場合は、証明書に署名した認証局（CA）を信頼するようにKubernetesクライアントを設定する必要があります。

クライアントを設定するには、次のいずれかを実行します:

PEM形式でKAS証明書を使用してCI/CD変数SSL_CERT_FILEを設定します。
--certificate-authority=$KAS_CERTIFICATEでKubernetesクライアントを設定します。ここで、KAS_CERTIFICATEはKASのCA証明書を持つCI/CD変数です。
コンテナイメージを更新するか、Runner経由でマウントして、ジョブコンテナ内の適切な場所に証明書を配置します。
推奨されません。--insecure-skip-tls-verify=trueでKubernetesクライアントを設定します。

代理を使用してプロジェクトとグループのアクセスを制限する

プラン: Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

デフォルトでは、CI/CDジョブは、クラスターにエージェントをインストールするために使用されるサービスアカウントからすべての権限を継承します。クラスターへのアクセスを制限するには、代理を使用します。

代理を指定するには、エージェント設定ファイルでaccess_as属性を使用し、Kubernetes RBACルールを使用して代理アカウントの権限を管理します。

代理にできるもの:

エージェント自体（デフォルト）。
クラスターにアクセスするCI/CDジョブ。
クラスター内で定義された特定のユーザーまたはシステムアカウント。

認証設定が反映されるまでに1 - 2分かかることがあります。

エージェントを代理化する

エージェントはデフォルトで代理化されます。代理化するために何かする必要はありません。

クラスターにアクセスするCI/CDジョブを代理化する

クラスターにアクセスするCI/CDジョブを代理化するには、access_asキーの下にci_job: {}キーと値を追加します。

エージェントが実際のKubernetes APIにリクエストを行う場合、次の方法で代理認証情報を設定します:

UserNameがgitlab:ci_job:<job id>に設定されます。例: gitlab:ci_job:1074499489。
Groupsは以下に設定されます:
- CIジョブからのすべてのリクエストを識別するためにgitlab:ci_job。
- プロジェクトが存在するグループのIDのリスト。
- プロジェクトID。
- このジョブが属する環境のslugとプラン。
  group1/group1-1/project1のCIジョブの例:
  - グループgroup1のIDは23です。
  - グループgroup1/group1-1のIDは25です。
  - プロジェクトgroup1/group1-1/project1のIDは150です。
  - production環境プランを持つprod環境で実行されているジョブ。
グループリストは[gitlab:ci_job, gitlab:group:23, gitlab:group_env_tier:23:production, gitlab:group:25, gitlab:group_env_tier:25:production, gitlab:project:150, gitlab:project_env:150:prod, gitlab:project_env_tier:150:production]になります。
Extraは、リクエストに関する追加情報を伝えます。代理化されたIDには、次のプロパティが設定されます:

プロパティ	説明
`agent.gitlab.com/id`	エージェントIDが含まれています。
`agent.gitlab.com/config_project_id`	エージェントの設定プロジェクトIDが含まれています。
`agent.gitlab.com/project_id`	CIプロジェクトIDが含まれています。
`agent.gitlab.com/ci_pipeline_id`	CIパイプラインIDが含まれています。
`agent.gitlab.com/ci_job_id`	CIジョブIDが含まれています。
`agent.gitlab.com/username`	CIジョブが実行されているユーザーのユーザー名が含まれています。
`agent.gitlab.com/environment_slug`	環境のslugが含まれています。環境で実行されている場合にのみ設定されます。
`agent.gitlab.com/environment_tier`	環境のプランが含まれています。環境で実行されている場合にのみ設定されます。

CI/CDジョブのIDでアクセスを制限する例config.yaml:

ci_access:
  projects:
    - id: path/to/project
      access_as:
        ci_job: {}

CI/CDジョブを制限するRBACの例

次のRoleBindingリソースは、すべてのCI/CDジョブを読み取り権限のみに制限します。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ci-job-view
roleRef:
  name: view
  kind: ClusterRole
  apiGroup: rbac.authorization.k8s.io
subjects:
  - name: gitlab:ci_job
    kind: Group

静的なIDを代理化する

特定の接続では、代理化に静的なIDを使用できます。

access_asキーの下に、impersonateキーを追加して、提供されたIDを使用してリクエストを行います。

IDは、次のキーで指定できます:

username（必須）
uid
groups
extra

詳細については、Kubernetesの公式ドキュメントを参照してください。

特定の環境へのプロジェクトとグループのアクセスを制限する

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

デフォルトでは、エージェントがプロジェクトで利用できる場合、プロジェクトのすべてのCI/CDジョブはそのエージェントを使用できます。

特定環境でのジョブのみにエージェントへのアクセスを制限するには、environmentsをci_access.projectsまたはci_access.groupsに追加します。次に例を示します:

ci_access:
  projects:
    - id: path/to/project-1
    - id: path/to/project-2
      environments:
        - staging
        - review/*
  groups:
    - id: path/to/group-1
      environments:
        - production

この例では:

project-1のすべてのCI/CDジョブがエージェントにアクセスできます。
project-2のstagingまたはreview/*環境下にあるCI/CDジョブはエージェントにアクセスできます。
- *はワイルドカードのため、review/*はreview配下のすべての環境と一致します。
group-1配下のプロジェクトのproduction環境用のCI/CDジョブは、エージェントにアクセスできます。

保護ブランチへのエージェントへのアクセスを制限

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed、GitLab Dedicated

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。この機能はテストには利用できますが、本番環境での使用には適していません。

保護ブランチで実行されるジョブのみにエージェントへのアクセスを制限するには:

protected_branches_only: trueをci_access.projectsまたはci_access.groupsに追加します。次に例を示します:

ci_access:
  projects:
    - id: path/to/project-1
      protected_branches_only: true
  groups:
    - id: path/to/group-1
      protected_branches_only: true
      environments:
        - production

デフォルトでは、protected_branches_onlyがfalseに設定され、エージェントには保護されていないブランチと保護ブランチからアクセスできます。

セキュリティを強化するために、この機能を環境制限と組み合わせることができます。

プロジェクトに複数の設定がある場合、最も具体的な設定のみが使用されます。たとえば、次の設定では、exampleグループが保護ブランチへのアクセスのみを許可するように設定されている場合でも、example/my-projectの保護されていないブランチへのアクセスが許可されます:

# .gitlab/agents/my-agent/config.yaml
ci_access:
  project:
    - id: example/my-project # Project of the group below
      protected_branches_only: false # This configuration supersedes the group configuration
      environments:
        - dev
  groups:
    - id: example
      protected_branches_only: true
      environments:
        - dev

詳細については、CI/CDからKubernetesへのアクセスを参照してください。

自己ペースの教室ワークショップ（AWS EKSを使用していますが、他のKubernetesクラスターにも使用できます）
Auto DevOpsを設定する

トラブルシューティング

`~/.kube/cache`に書き込み権限を付与する

kubectl、Helm、kpt、kustomizeなどのツールは、クラスターに関する情報を~/.kube/cacheにキャッシュします。このディレクトリが書き込み可能でない場合、ツールは呼び出すたびに情報をフェッチするため、インタラクションが遅くなり、クラスターの読み込みに不要な負荷がかかります。最良のエクスペリエンスを得るために、.gitlab-ci.ymlファイルで使用するイメージで、このディレクトリが書き込み可能であることを確認してください。

TLSを有効にする

GitLab Self-Managedを使用している場合は、インスタンスがトランスポートレイヤーセキュリティ（TLS）で設定されていることを確認してください。

TLSなしでkubectlを使用しようとすると、次のようなエラーが発生する可能性があります:

$ kubectl get pods
error: You must be logged in to the server (the server has asked for the client to provide credentials)

サーバーに接続できません: 不明な認証局によって署名された証明書

KASを使用する環境で、自己署名証明書を使用している場合、kubectlの呼び出しで次のエラーが返されることがあります:

kubectl get pods
Unable to connect to the server: x509: certificate signed by unknown authority

このエラーは、ジョブがKAS証明書に署名した認証局（CA）を信頼しないために発生します。

問題を解決するには、CAを信頼するようにkubectlを設定します。

検証エラー

kubectlのバージョンv1.27.0またはv.1.27.1を使用している場合、次のエラーが発生する可能性があります:

error: error validating "file.yml": error validating data: the server responded with the status code 426 but did not return more information; if you choose to ignore these errors, turn validation off with --validate=false

このイシューは、共有Kubernetesライブラリを使用するkubectlおよびその他のツールのバグによって発生します。

問題を解決するには、別のバージョンのkubectlを使用してください。