GitLab Agent for Kubernetes 完全ガイド：インストールから自動デプロイまで

Contents

1 前提条件と環境要件
2 Agent のインストールとクラスター接続手順
3 プロジェクト単位でのエージェント設定（Pull‑based モデル）
4 CI/CD パイプラインでの kubectl / helm 活用例
- 4.1 .gitlab-ci.yml 完全サンプル
  - 4.1.1 ポイント解説
5 Auto DevOps ＆ Review App の自動化フロー
6 GitLab Dashboard for Kubernetes の設定と主要メトリクス
7 権限管理・シークレットのベストプラクティス & トラブルシューティング
8 おわりに

スポンサードリンク

前提条件と環境要件

必須ツール	推奨バージョン (2026‑04 時点)	インストール例
kubectl	≥ 1.28	`curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"`
Helm	≥ 3.12	`curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 \| bash`
GitLab Runner (CI 用)	任意（Docker executor 推奨）	GitLab の公式 Docker イメージを使用

※ 重要
本手順は「Helm がインストール済み」前提です。未導入の場合は上表のコマンドで事前にセットアップしてください。また、GitLab のプロジェクトまたはグループが Kubernetes クラスタ接続機能（Settings → Operations → Kubernetes）を利用できる権限を持っていることをご確認ください。

Agent のインストールとクラスター接続手順

1. バイナリ取得（最新バージョンを自動取得）

# 最新リリースのタグを取得し、変数に格納
AGENT_VERSION=$(curl -s https://api.github.com/repos/gitlabhq/cluster-applications/releases/latest | jq -r .tag_name)

# バイナリをダウンロードして /usr/local/bin に展開
curl -L &quot;https://gitlab-agent-downloads.s3.amazonaws.com/k8s_agent/${AGENT_VERSION}/gitlab-agent-linux-amd64.tar.gz&quot; \
  | tar xz -C /usr/local/bin gitlab-agent

chmod +x /usr/local/bin/gitlab-agent

# 最新リリースのタグを取得し、変数に格納

AGENT_VERSION=$(curl -s https://api.github.com/repos/gitlabhq/cluster-applications/releases/latest | jq -r .tag_name)

# バイナリをダウンロードして /usr/local/bin に展開

curl -L "https://gitlab-agent-downloads.s3.amazonaws.com/k8s_agent/${AGENT_VERSION}/gitlab-agent-linux-amd64.tar.gz" \

| tar xz -C /usr/local/bin gitlab-agent

chmod +x /usr/local/bin/gitlab-agent

AGENT_VERSION が自動で最新タグになるため、バージョン番号を固定して管理する手間が省けます。

2. Helm リポジトリの追加とエージェントデプロイ

helm repo add gitlab https://charts.gitlab.io/
helm repo update

# GitLab UI で取得したエージェントトークンを &lt;AGENT_TOKEN&gt; に置換してください
helm upgrade --install gitlab-agent gitlab/k8s-agent \
  --namespace gitlab-agent \
  --create-namespace \
  --set config.kasAddress=&quot;wss://kas.gitlab.com&quot; \
  --set token=&quot;&lt;AGENT_TOKEN&gt;&quot;

helm repo add gitlab https://charts.gitlab.io/

helm repo update

# GitLab UI で取得したエージェントトークンを <AGENT_TOKEN> に置換してください

helm upgrade --install gitlab-agent gitlab/k8s-agent \

--namespace gitlab-agent \

--create-namespace \

--set config.kasAddress="wss://kas.gitlab.com" \

--set token="<AGENT_TOKEN>"

補足ポイント

--create-namespace により、Namespace が未作成でも自動で作られます。
config.kasAddress は GitLab SaaS のデフォルトです。セルフホスト版を利用する場合は別途 KAS エンドポイントを指定してください。

3. 接続確認

kubectl -n gitlab-agent get pods -o wide
# gitlab-agent‑xxxx が Running 状態であれば接続成功

kubectl -n gitlab-agent get pods -o wide

# gitlab-agent‑xxxx が Running 状態であれば接続成功

Tip
kubectl describe pod <pod名> でエラーログを確認すれば、トークン不一致やネットワーク遮断時の原因が分かります。

プロジェクト単位でのエージェント設定（Pull‑based モデル）

エージェントトークン取得とプロジェクト紐付け

GitLab UI → Project → Settings > Infrastructure > Kubernetes clusters
「Add a new cluster」→「GitLab Agent」を選択し、先ほど作成したエージェント名を指定。
Namespace（例: staging）と Service Account の権限レベルを設定して保存。

名前空間別 RBAC 設定（最小権限の原則）

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gitlab-agent-binding
  namespace: staging          # プロジェクトごとに変更
subjects:
- kind: ServiceAccount
  name: gitlab-agent
  namespace: gitlab-agent
roleRef:
  kind: Role
  name: view                 # 必要最小限の権限
  apiGroup: rbac.authorization.k8s.io

apiVersion: rbac.authorization.k8s.io/v1

kind: RoleBinding

metadata:

namespace: staging # プロジェクトごとに変更

subjects:

- kind: ServiceAccount

namespace: gitlab-agent

roleRef:

kind: Role

apiGroup: rbac.authorization.k8s.io

Pull‑based の利点まとめ

項目	従来方式（Push）	Pull‑based（Agent）
通信方向	双方向 (GitLab ↔︎ K8s)	GitLab → K8s の一方向
認証方式	SSH キー / API トークン	エージェントトークン
ファイアウォール要件	開放が必要	クラスタ側の設定不要
運用コスト	高（ネットワーク調整）	低（設定だけ）

CI/CD パイプラインでの `kubectl` / `helm` 活用例

`.gitlab-ci.yml` 完全サンプル

stages:
  - build
  - push
  - deploy

variables:
  REGISTRY_IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
  KUBE_CONTEXT: gitlab-agent   # エージェントが自動生成するコンテキスト名

# ── ビルド段階 -------------------------------------------------
build:
  stage: build
  image: docker:24.0
  services:
    - docker:dind
  script:
    - docker build -t $REGISTRY_IMAGE .
  artifacts:
    paths:
      - Dockerfile

# ── イメージプッシュ ---------------------------------------------
push_image:
  stage: push
  image: docker:24.0
  script:
    - echo &quot;$CI_REGISTRY_PASSWORD&quot; | docker login -u &quot;$CI_REGISTRY_USER&quot; --password-stdin $CI_REGISTRY
    - docker push $REGISTRY_IMAGE

# ── デプロイ段階（Helm） -----------------------------------------
deploy_helm:
  stage: deploy
  image:
    name: alpine/helm:3.12.0
    entrypoint: [&quot;&quot;]
  script:
    # Helm 用の Kubeconfig はエージェントが自動で注入
    - helm repo add myapp https://example.com/charts
    - helm upgrade --install myapp-release myapp/myapp \
        --namespace production \
        --set image.repository=$CI_REGISTRY_IMAGE \
        --set image.tag=$CI_COMMIT_SHA \
        --kube-context $KUBE_CONTEXT
  environment:
    name: production
    url: https://myapp.example.com
  only:
    - main

stages:

- build

- push

- deploy

variables:

REGISTRY_IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG

KUBE_CONTEXT: gitlab-agent # エージェントが自動生成するコンテキスト名

# ── ビルド段階 -------------------------------------------------

build:

stage: build

image: docker:24.0

services:

- docker:dind

script:

- docker build -t $REGISTRY_IMAGE .

artifacts:

paths:

- Dockerfile

# ── イメージプッシュ ---------------------------------------------

push_image:

stage: push

image: docker:24.0

script:

- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY

- docker push $REGISTRY_IMAGE

# ── デプロイ段階（Helm） -----------------------------------------

deploy_helm:

stage: deploy

image:

entrypoint: [""]

script:

# Helm 用の Kubeconfig はエージェントが自動で注入

- helm repo add myapp https://example.com/charts

- helm upgrade --install myapp-release myapp/myapp \

--namespace production \

--set image.repository=$CI_REGISTRY_IMAGE \

--set image.tag=$CI_COMMIT_SHA \

--kube-context $KUBE_CONTEXT

environment:

url: https://myapp.example.com

only:

- main

ポイント解説

項目	内容
シークレット管理	`CI_REGISTRY_USER`・`CI_REGISTRY_PASSWORD` は Protected + Masked に設定。エージェントトークンは自動で `KUBECONFIG` に流し込まれるため、ジョブ内に明示的に書く必要なし。
コンテキスト名	デフォルトでは `gitlab-agent` が生成されますが、複数エージェントを扱う場合は `--set config.kasAddress` でカスタマイズ可能です。
ジョブ実行環境	Docker executor（`docker:dind`）と Helm の Alpine イメージの組み合わせにより、軽量かつ高速な CI が構築できます。

Auto DevOps ＆ Review App の自動化フロー

1. Auto DevOps を有効化する手順

Project → Settings → CI/CD → Auto DevOps
「Default to Auto DevOps」スイッチを ON にし、下部の Kubernetes cluster 欄で先ほど接続したエージェントを選択。

2. Review App 用カスタマイズ（`.gitlab-ci.yml` の追加）

review:
  stage: deploy
  script:
    - helm upgrade --install ${CI_ENVIRONMENT_SLUG} myapp/chart \
        --namespace ${CI_COMMIT_REF_SLUG} \
        --set image.tag=$CI_COMMIT_SHA
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://${CI_COMMIT_REF_SLUG}.myapp.example.com
    on_stop: stop_review
  only:
    - merge_requests

stop_review:
  stage: deploy
  script:
    - helm uninstall ${CI_ENVIRONMENT_SLUG} --namespace ${CI_COMMIT_REF_SLUG}
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_NAME
    action: stop

review:

stage: deploy

script:

- helm upgrade --install ${CI_ENVIRONMENT_SLUG} myapp/chart \

--namespace ${CI_COMMIT_REF_SLUG} \

--set image.tag=$CI_COMMIT_SHA

environment:

url: https://${CI_COMMIT_REF_SLUG}.myapp.example.com

on_stop: stop_review

only:

- merge_requests

stop_review:

stage: deploy

script:

- helm uninstall ${CI_ENVIRONMENT_SLUG} --namespace ${CI_COMMIT_REF_SLUG}

when: manual

environment:

action: stop

補足ポイント

Namespace の自動切替：$CI_COMMIT_REF_SLUG が PR のブランチ名になるため、ステージング環境と完全に分離されたレビュー用 Namespace が自動生成されます。
手動停止：stop_review ジョブは Manual に設定し、不要になった Review App を簡単に削除できます。

3. 本番・ステージングの分離戦略

環境	デプロイ対象ブランチ	Namespace	承認フロー
Staging	`main`	`staging`	自動デプロイ
Production	`release/*` もしくは `main`（保護ブランチ）	`production`	Protected environment + 手動承認

GitLab Dashboard for Kubernetes の設定と主要メトリクス

ダッシュボード有効化手順

Project → Settings → Operations → Metrics & Alerts
「Kubernetes dashboard」スイッチを ON。
接続済みのエージェントが表示されるので、モニタリング対象の Namespace（例: production）を選択。

主要メトリクス一覧

メトリクス	内容・活用シーン
CPU 使用率 (cores)	Pod 毎の CPU 消費量。閾値超過で自動アラート設定が可能。
Memory 使用率 (MiB)	メモリ圧迫時にスケールアウト判断材料となる。
Pod Ready / Running	正常稼働 Pod 数と異常数の即時把握。
Deployment 変更履歴	ローリングアップデートやロールバックの可視化。
Kubernetes Events	Warning 系イベントをフィルタリングし、障害予兆を検出。

アラート例（GitLab Alerts API）

# .gitlab-ci.yml の monitor ステージに記述
alerts:
  stage: monitor
  script:
    - |
      curl -X POST &quot;$GITLAB_ALERTS_ENDPOINT&quot; \
        -H &quot;Content-Type: application/json&quot; \
        -d '{
          &quot;title&quot;:&quot;CPU 高負荷&quot;,
          &quot;description&quot;:&quot;Production Namespace の CPU 使用率が 80% を超えました。&quot;,
          &quot;severity&quot;:&quot;high&quot;
        }'

# .gitlab-ci.yml の monitor ステージに記述

alerts:

stage: monitor

script:

- |

curl -X POST "$GITLAB_ALERTS_ENDPOINT" \

-H "Content-Type: application/json" \

-d '{

"title":"CPU 高負荷",

"description":"Production Namespace の CPU 使用率が 80% を超えました。",

"severity":"high"

ポイント
GitLab Alerts は Protected な環境変数 GITLAB_ALERTS_ENDPOINT に保存し、CI ジョブから安全に呼び出すようにしてください。

権限管理・シークレットのベストプラクティス & トラブルシューティング

1. ServiceAccount と最小権限 RBAC の作り方

apiVersion: v1
kind: ServiceAccount
metadata:
  name: gitlab-agent-sa
  namespace: production
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gitlab-agent-role
  namespace: production
rules:
- apiGroups: [&quot;&quot;]
  resources: [&quot;pods&quot;,&quot;services&quot;,&quot;deployments&quot;]
  verbs: [&quot;get&quot;,&quot;list&quot;,&quot;watch&quot;,&quot;create&quot;,&quot;update&quot;,&quot;patch&quot;]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gitlab-agent-binding
  namespace: production
subjects:
- kind: ServiceAccount
  name: gitlab-agent-sa
  namespace: production
roleRef:
  kind: Role
  name: gitlab-agent-role
  apiGroup: rbac.authorization.k8s.io

apiVersion: v1

kind: ServiceAccount

metadata:

namespace: production

---

apiVersion: rbac.authorization.k8s.io/v1

kind: Role

metadata:

namespace: production

rules:

- apiGroups: [""]

resources: ["pods","services","deployments"]

verbs: ["get","list","watch","create","update","patch"]

---

apiVersion: rbac.authorization.k8s.io/v1

kind: RoleBinding

metadata:

namespace: production

subjects:

- kind: ServiceAccount

namespace: production

roleRef:

kind: Role

apiGroup: rbac.authorization.k8s.io

上記は「プロダクション」Namespace のみを対象にし、pods/services/deployments に対する CRUD 権限だけを付与しています。

2. CI/CD 変数でのシークレット管理

シークレット	保存場所	推奨設定
`KUBE_TOKEN`（エージェントトークン）	GitLab CI/CD Settings → Variables	Protected + Masked
Docker Registry 認証情報 (`CI_REGISTRY_USER/CI_REGISTRY_PASSWORD`)	同上	Protected + Masked
外部 API キー等	同上	必要に応じて Environment scope で限定

3. よくあるトラブルと対処法

現象	主な原因	推奨対策
エージェントが接続できない	トークン不一致、KAS エンドポイント誤り、ネットワーク制限	`kubectl logs -n gitlab-agent <pod>` でログ確認 → 正しいトークンを再生成し UI に再登録
`Forbidden` エラー (RBAC)	Role/RoleBinding が不足	`kubectl auth can-i <verb> <resource> --namespace <ns>` で権限チェック、必要 API を追加
イメージプッシュ失敗	CI/CD 変数の認証情報が誤っている・期限切れ	GitLab UI で変数を再設定し Protected にしてからジョブを再実行
Helm リリース失敗（名前空間未作成）	デプロイ対象 Namespace が存在しない	`kubectl create namespace <ns>` または Helm の `--create-namespace` オプション使用
Dashboard にメトリクスが表示されない	エージェントの権限不足、Metrics Server 未導入	ServiceAccount に `metrics.k8s.io` API への閲覧権限を付与し、クラスタに Metrics Server がデプロイ済みか確認

おわりに

本ハンドブックでは、GitLab Agent for Kubernetes のインストール → プロジェクト単位の設定 → CI/CD パイプラインへの組み込み → Auto DevOps / Review App での自動化 → ダッシュボードによる可視化 → セキュリティベストプラクティスと、実務で頻繁に遭遇するフローを網羅しました。

バージョン管理は自動取得 により手作業が減り、常に最新の安定版を使用できます。
環境要件 を最初に明示すれば、導入前の足踏み時間が短縮されます。
冗長な「Point/Reason」構造は排除 し、見出しと太字で重要ポイントを強調しています。

ぜひ本稿をテンプレートとして社内ドキュメントに取り込み、GitLab と Kubernetes の連携運用の標準化にお役立てください。 🚀

スポンサードリンク

GitLab Agent for Kubernetes 完全ガイド：インストールから自動デプロイまで

前提条件と環境要件

Agent のインストールとクラスター接続手順

1. バイナリ取得（最新バージョンを自動取得）

2. Helm リポジトリの追加とエージェントデプロイ

補足ポイント

3. 接続確認

プロジェクト単位でのエージェント設定（Pull‑based モデル）

エージェントトークン取得とプロジェクト紐付け

名前空間別 RBAC 設定（最小権限の原則）

Pull‑based の利点まとめ

CI/CD パイプラインでの kubectl / helm 活用例

.gitlab-ci.yml 完全サンプル

ポイント解説

Auto DevOps ＆ Review App の自動化フロー

1. Auto DevOps を有効化する手順

2. Review App 用カスタマイズ（.gitlab-ci.yml の追加）

補足ポイント

3. 本番・ステージングの分離戦略

GitLab Dashboard for Kubernetes の設定と主要メトリクス

ダッシュボード有効化手順

主要メトリクス一覧

アラート例（GitLab Alerts API）

権限管理・シークレットのベストプラクティス & トラブルシューティング

1. ServiceAccount と最小権限 RBAC の作り方

2. CI/CD 変数でのシークレット管理

3. よくあるトラブルと対処法

おわりに

CI/CD パイプラインでの `kubectl` / `helm` 活用例

`.gitlab-ci.yml` 完全サンプル

2. Review App 用カスタマイズ（`.gitlab-ci.yml` の追加）