Contents
GitLab Kubernetes Agent の概要とインストール手順
GitLab 16 系列で標準化された Kubernetes Agent は、GitLab とクラスター間の双方向 TLS 通信を実現し、CI/CD を安全かつスケーラブルに動作させます。本セクションでは、公式ドキュメント（2026 年版）に沿ったインストールフローと、バージョン管理のベストプラクティスを示します。
エージェント登録情報の取得
GitLab UI からエージェントを作成し、トークンと config.yaml を入手します。
- 操作手順
- プロジェクト → Settings → Infrastructure → Kubernetes clusters → Add Kubernetes cluster → Connect a cluster with the Agent
- 「Agent name」を入力し Create agent をクリックすると、
config.yamlと Static Token が生成されます。
マニフェスト取得と適用（動的バージョン参照）
固定バージョン v1.13.0 は古くなる恐れがあるため、最新リリースを自動で取得できる URL を推奨します。
|
1 2 3 4 |
# 最新リリースのマニフェストを取得（GitLab のリポジトリでタグが更新されれば自動的に新バージョンになる） curl -L "https://gitlab.com/-/kubernetes-agent/k8s-manifests/latest/kubernetes-agent.yaml" \ -o agent.yaml |
※ バージョン確認
curl -s https://gitlab.com/api/v4/projects/gitlab-org%2Fkubernetes-agent/releases | jq '.[0].tag_name'で最新タグを取得し、スクリプトに組み込むことも可能です。
名前空間とトークンの差し替え
以下の点に注意して agent.yaml を編集します。
- 名前空間：
gitlab-agent（以降すべて同一） - トークン置換：
AGENT_TOKEN_PLACEHOLDER→ 取得した Static Token
|
1 2 3 |
sed -i "s|AGENT_TOKEN_PLACEHOLDER|${YOUR_AGENT_TOKEN}|g" agent.yaml sed -i "s|namespace: default|namespace: gitlab-agent|g" agent.yaml |
クラスターへデプロイ
|
1 2 |
kubectl apply -f agent.yaml |
適用後、GitLab の Kubernetes clusters ページに Connected が表示されれば完了です。
ServiceAccount と RBAC の最小権限設定
エージェントが必要とする API のみを許可し、過剰権限によるリスクを排除します。以下では gitlab-agent 名前空間に限定した構成例を示します。
ServiceAccount と ClusterRole/Binding（概要）
ServiceAccount を作成し、最低限の ClusterRole をバインドします。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
apiVersion: v1 kind: ServiceAccount metadata: name: gitlab-agent-sa namespace: gitlab-agent --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: gitlab-agent-role rules: - apiGroups: [""] resources: ["pods", "services", "secrets"] verbs: ["get", "list", "watch"] - apiGroups: ["apps"] resources: ["deployments"] verbs: ["get", "list", "watch"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: gitlab-agent-binding roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: gitlab-agent-role subjects: - kind: ServiceAccount name: gitlab-agent-sa namespace: gitlab-agent |
Namespace‑Scoped Role の追加例
本番環境で機密リソースへのアクセスをさらに絞り込みます。
|
1 2 3 4 5 6 7 8 9 10 |
apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: gitlab-agent-ns-role namespace: production rules: - apiGroups: [""] resources: ["configmaps", "secrets"] verbs: ["get", "update"] |
この Role を同様に RoleBinding で gitlab-agent-sa に付与すれば、クラスター全体ではなく対象 Namespace のみが操作可能になります。
GitLab CI/CD パイプライン（.gitlab-ci.yml）
CI/CD では ビルド → テスト → デプロイ の三段階を一貫して定義し、GitLab の変数と Kubernetes Secret を安全に連携させます。
ビルド・テストステージ（概要）
コンテナイメージの作成とユニットテストを自動化します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
stages: - build - test - deploy variables: IMAGE_TAG: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" build: stage: build image: docker:23.0 services: [docker:dind] script: - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - docker build -t "$IMAGE_TAG" . - docker push "$IMAGE_TAG" test: stage: test image: node:20-alpine script: - npm ci - npm run lint - npm test |
Helm デプロイステージ（概要）
helm upgrade --install により新規インストールとローリングアップデートを統一します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
deploy: stage: deploy image: alpine/helm:3.14.0 script: - helm repo add myrepo https://example.com/charts - helm dependency update ./chart - | helm upgrade --install myapp ./chart \ --namespace production \ --set image.repository=$CI_REGISTRY_IMAGE \ --set image.tag=$CI_COMMIT_SHORT_SHA \ --values values.yaml \ --set env.SECRET_KEY=${SECRET_KEY} only: - main |
機密情報の安全な参照方法（概要）
GitLab の CI/CD 変数 と Kubernetes Secret を組み合わせ、平文がコードに残らないようにします。
- GitLab → Settings → CI/CD → Variables に
SECRET_KEY（Protected, Masked）を登録。 - デプロイジョブで
--set env.SECRET_KEY=${SECRET_KEY}と展開。 - Helm Chart 側の
templates/secret.yamlでは以下のように参照します。
|
1 2 3 4 5 6 7 8 |
apiVersion: v1 kind: Secret metadata: name: myapp-secret type: Opaque data: SECRET_KEY: {{ .Values.env.SECRET_KEY | b64enc }} |
Helm Chart によるパラメータ化と環境別デプロイ
Helm を IaC として活用し、values.yaml で共通設定を管理、環境ごとの差分は上書きファイルで提供します。
Chart ディレクトリ構成（概要）
再利用性と可読性を高める標準的な配置例です。
|
1 2 3 4 5 6 7 8 9 10 |
myapp/ ├── Chart.yaml ├── values.yaml # すべての環境で共通 ├── values-staging.yaml # ステージング固有 ├── values-prod.yaml # 本番固有 └── templates/ ├── deployment.yaml ├── service.yaml └── secret.yaml |
values.yaml の抜粋：
|
1 2 3 4 5 6 7 8 9 |
replicaCount: 2 image: repository: registry.gitlab.com/group/project pullPolicy: IfNotPresent tag: latest env: LOG_LEVEL: info SECRET_KEY: "" # CI が上書き |
CI から Helm コマンドを呼び出す例（概要）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
deploy_staging: stage: deploy image: alpine/helm:3.14.0 script: - helm repo update - | helm upgrade --install myapp ./chart \ --namespace staging \ -f values.yaml -f values-staging.yaml \ --set image.tag=$CI_COMMIT_SHORT_SHA \ --set env.LOG_LEVEL=debug only: [develop] deploy_production: stage: deploy image: alpine/helm:3.14.0 script: - helm repo update - | helm upgrade --install myapp ./chart \ --namespace production \ -f values.yaml -f values-prod.yaml \ --set image.tag=$CI_COMMIT_SHORT_SHA \ --set env.LOG_LEVEL=error only: [main] |
環境ごとに values-*.yaml を組み合わせ、GitLab の変数で上書きすれば、同一パイプラインで安全なマルチステージデプロイが実現します。
GitOps フロー：マージリクエストで自動デプロイ
MR が作成・更新されたときにプレビュー環境を自動生成し、本番への変更はコードレビューと同時にインフラへ反映させます。
MR トリガー設定（概要）
.gitlab-ci.yml に only: [merge_requests] を記述すると、MR 発行ごとにデプロイジョブが走ります。
|
1 2 3 4 5 6 7 8 9 10 11 |
deploy_preview: stage: deploy image: alpine/helm:3.14.0 script: - helm upgrade --install preview-${CI_COMMIT_SHORT_SHA} ./chart \ --namespace preview-${CI_MERGE_REQUEST_IID} \ -f values.yaml \ --set image.tag=$CI_COMMIT_SHORT_SHA only: - merge_requests |
この設定により、preview-<MR_IID> 名前空間が自動作成され、プレビュー環境が即座に利用可能になります。
ブランチ戦略と名前空間マッピング（概要）
| ブランチ | デプロイ対象 Namespace | CI 条件 |
|---|---|---|
main |
production |
only: [master] |
develop |
staging |
only: [develop] |
| MR | preview-<MR_IID> |
only: [merge_requests] |
この 1‑to‑1 の対応により、変更がどの環境へ反映されたかを容易に追跡できます。
最新セキュリティベストプラクティスとトラブルシューティング
Kubernetes 標準の Pod Security Standards (PSS) と NetworkPolicy を用いて、最小権限・ネットワーク分離をコードとして管理します。
Pod Security Standards の適用例（概要）
PodSecurityPolicy は Kubernetes 1.25 以降非推奨です。代わりに Admission コントローラで PSS を有効化し、Namespace にラベル付与する方法を示します。
|
1 2 3 4 5 6 7 8 9 10 |
# production Namespace に restricted プロファイルを適用 apiVersion: v1 kind: Namespace metadata: name: production labels: pod-security.kubernetes.io/enforce: "restricted" pod-security.kubernetes.io/audit: "restricted" pod-security.kubernetes.io/warn: "restricted" |
このラベルにより、特権コンテナやホストネットワークの使用が自動的にブロックされます。
NetworkPolicy の実装例（概要）
内部ネットワークは 10.0.0.0/16 と仮定し、Agent 以外からの通信を遮断します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: restrict-to-agent namespace: production spec: podSelector: {} # 全Pod対象 policyTypes: - Ingress - Egress ingress: - from: - namespaceSelector: matchLabels: name: gitlab-agent # Agent が所属する Namespace のみ許可 egress: - to: - ipBlock: cidr: 10.0.0.0/16 # 社内ネットワークへの通信のみ許可 |
ログ・ジョブの確認手順（概要）
- Agent Pod の取得
bash
kubectl get pods -n gitlab-agent -l app=gitlab-agent - リアルタイムログ表示
bash
kubectl logs -f <agent-pod> -n gitlab-agent - GitLab ジョブの Trace を確認
GitLab の CI/CD > Jobs で失敗ジョブを開き、Trace タブに出力されたエラーメッセージを参照します。
典型的なエラー例
- failed to get Kubernetes version → ServiceAccount の RBAC が不足している可能性。
- TLS handshake timeout → TLS 証明書の期限切れ、または Secret マウントミス。
まとめ
| 項目 | 主なポイント |
|---|---|
| Agent インストール | 最新リリース URL を使用し、gitlab-agent 名前空間にデプロイ。 |
| 認証方式 | Static Token が手軽、必要に応じて自前 TLS に切替可能。 |
| RBAC 設計 | ServiceAccount + 最小権限 ClusterRole、Namespace‑Scoped Role でリスク最小化。 |
| CI/CD パイプライン | ビルド・テスト・Helm デプロイを統合し、GitLab 変数と Kubernetes Secret を安全に連携。 |
| Helm Chart 管理 | values.yaml と環境別上書きファイルでパラメータ化、CI から動的に注入。 |
| GitOps フロー | MR トリガーでプレビュー Namespace を自動生成し、ブランチ⇔Namespace の 1 対 1 マッピングを実現。 |
| セキュリティ | PSS ラベル付与と NetworkPolicy による最小権限・ネットワーク分離。 |
| トラブルシューティング | Agent Pod ログ + GitLab Job Trace の併用で迅速に原因特定。 |
以上の手順を踏むことで、GitLab 16 系列と最新 Kubernetes クラスター間の安全な連携が実現し、DevOps チームは高い信頼性とスピードで CI/CD を運用できるようになります。