GitLab管理のKubernetesリソース

GitLab管理のKubernetesリソースを使用して、環境テンプレートでKubernetesリソースをプロビジョニングします。環境テンプレートでできること:

• 新しい環境のネームスペースとサービスアカウントを自動的に作成します
• ロールバインディングを通じてアクセス許可を管理します
• 必要なその他のKubernetesリソースを構成します

デベロッパーがアプリケーションをデプロイすると、GitLabは環境テンプレートに基づいてリソースを作成します。

GitLab管理のKubernetesリソースの設定

前提要件:

• 構成済みのKubernetes向けGitLabエージェントが必要です。
• 関連するプロジェクトまたはグループにアクセスするためにエージェントを承認しました。
• （オプション）特権エスカレーションを防ぐために代理エージェントを構成しました。デフォルトの環境テンプレートは、ci_job代理が構成されていることを前提としています。

Kubernetesリソース管理を有効にする

エージェント設定ファイル内

リソース管理を有効にするには、必要な権限を含めるようにエージェント設定ファイルを変更します:

ci_access:
  projects:
    - id: <your_group/your_project>
      access_as:
        ci_job: {}
      resource_management:
        enabled: true
  groups:
    - id: <your_other_group>
      access_as:
        ci_job: {}
      resource_management:
        enabled: true

CI/CDジョブ内

エージェントが環境のリソースを管理できるようにするには、デプロイメントジョブでエージェントを指定します。例:

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    kubernetes:
      agent: path/to/agent/project:agent-name

CI/CD変数は、エージェントパスで使用できます。詳細については、変数が使用できる場所を参照してください。

環境テンプレートの作成

環境テンプレートは、作成、更新、または削除されるKubernetesリソースを定義します。

デフォルト環境テンプレートは、Namespaceを作成し、CI/CDジョブのRoleBindingを構成します。

デフォルトのテンプレートを上書きするには、default.yamlというテンプレート設定ファイルをエージェントディレクトリに追加します:

.gitlab/agents/<agent-name>/environment_templates/default.yaml

サポートされているKubernetesリソース

次のKubernetesリソース（kind）がサポートされています:

• Namespace
• ServiceAccount
• RoleBinding
• FluxCDソースコントローラーオブジェクト:
  • GitRepository
  • HelmRepository
  • HelmChart
  • Bucket
  • OCIRepository
• FluxCD Kustomizeコントローラーオブジェクト:
  • Kustomization
• FluxCD Helmコントローラーオブジェクト:
  • HelmRelease
• FluxCD通知コントローラーオブジェクト:
  • Alert
  • Provider
  • Receiver

環境テンプレートの例

次の例では、ネームスペースを作成し、グループ管理者にクラスタリングへのアクセスを許可します。

objects:
  - apiVersion: v1
    kind: Namespace
    metadata:
      name: '{{ .environment.slug }}-{{ .project.id }}-{{ .agent.id }}'
  - apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: bind-{{ .environment.slug }}-{{ .project.id }}-{{ .agent.id }}
      namespace: '{{ .environment.slug }}-{{ .project.id }}-{{ .agent.id }}'
    subjects:
      - kind: Group
        apiGroup: rbac.authorization.k8s.io
        name: gitlab:project_env:{{ .project.id }}:{{ .environment.slug }}
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: admin

# Resource lifecycle configuration
apply_resources: on_start    # Resources are applied when environment is started/restarted
delete_resources: on_stop    # Resources are removed when environment is stopped

テンプレート変数

環境テンプレートは、制限された変数の置換をサポートします。次の変数を使用できます:

すべての変数は、二重波括弧構文を使用して参照する必要があります（例：{{ .project.id }}）。使用されているテンプレートシステムの詳細については、text/templateドキュメントを参照してください。

テンプレート関数

環境テンプレートは、変数の値を操作するための制限された関数をサポートしています。次の関数を使用できます:

変数をKubernetes値に準拠させるために、関数の数は、ネームスペース名やラベルなど、意図的に最小限の関数セットに制限されています。

リソースライフサイクル管理

Kubernetesリソースを削除するタイミングを構成するには、次の設定を使用します:

# Never delete resources
delete_resources: never

# Delete resources when environment is stopped
delete_resources: on_stop

デフォルト値はon_stopであり、デフォルト環境テンプレートで指定されています。

管理対象リソースのラベルと注釈

GitLabによって作成されたリソースは、追跡とトラブルシューティングの目的で一連のラベルと注釈を使用します。

次のラベルは、GitLabによって作成されたすべてのリソースで定義されています。値は意図的に空のままになっています:

• agent.gitlab.com/id-<agent_id>: ""
• agent.gitlab.com/project_id-<project_id>: ""
• agent.gitlab.com/env-<gitlab_environment_slug>-<project_id>-<agent_id>: ""
• agent.gitlab.com/environment_slug-<gitlab_environment_slug>: ""

GitLabによって作成されたすべてのリソースで、agent.gitlab.com/env-<gitlab_environment_slug>-<project_id>-<agent_id>注釈が定義されています。注釈の値は、次のキーを持つJSONオブジェクトです:

GitLabで管理されたKubernetesリソースを無効にする

ダッシュボードなどの他のKubernetes機能を引き続き使用しながら、特定の環境に対してGitLab管理のKubernetesリソースを無効にすることができます。管理対象リソースを無効にすると、デフォルトで管理対象リソースが有効になっているグローバルエージェントを操作する場合に役立ちますが、特定のプロジェクトまたは環境をオプトアウトする必要があります。

環境の管理対象リソースを無効にするには、managed_resources.enabled: false構成を追加します:

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    kubernetes:
      agent: path/to/agent/project:agent-name
      managed_resources:
        enabled: false

トラブルシューティング

管理対象のKubernetesリソースに関連するエラーは、次の場所にあります:

• GitLabプロジェクトの環境ページ
• パイプラインで機能を使用する場合のCI/CDジョブログ