GitLab-managed Kubernetes resources

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
History

Use GitLab-managed Kubernetes resources to provision Kubernetes resources with environment templates. An environment template can:

  • Create namespaces and service accounts automatically for new environments
  • Manage access permissions through role bindings
  • Configure other required Kubernetes resources

When developers deploy applications, GitLab creates the resources based on the environment template.

Configure GitLab-managed Kubernetes resources

Prerequisites:

Turn on Kubernetes resource management

To turn on resource management, modify the agent configuration file to include the required permissions:

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

Create environment templates

Environment templates define what Kubernetes resources are created, updated, or removed.

The default environment template creates a Namespace and configures a RoleBinding for the CI/CD job.

To overwrite the default template, add a template configuration file called default.yaml in the agent directory:

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

Supported Kubernetes resources

The following Kubernetes resources (kind) are supported:

  • Namespace
  • ServiceAccount
  • RoleBinding
  • FluxCD Source Controller objects:
    • GitRepository
    • HelmRepository
    • HelmChart
    • Bucket
    • OCIRepository
  • FluxCD Kustomize Controller objects:
    • Kustomization
  • FluxCD Helm Controller objects:
    • HelmRelease
  • FluxCD Notification Controller objects:
    • Alert
    • Provider
    • Receiver

Example environment template

The following example creates a namespace and grants a group administrator access to a cluster.

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

Template variables

Environment templates support limited variable substitution. The following variables are available:

CategoryVariableDescription
Agent{{ .agent.id }}The agent identifier.
Agent{{ .agent.name }}The agent name.
Agent{{ .agent.url }}The agent URL.
Environment{{ .environment.name }}The environment name.
Environment{{ .environment.slug }}The environment slug.
Environment{{ .environment.url }}The environment URL.
Environment{{ .environment.tier }}The environment tier.
Project{{ .project.id }}The project identifier.
Project{{ .project.slug }}The project slug.
Project{{ .project.path }}The project path.
Project{{ .project.url }}The project URL.
CI Pipeline{{ .ci_pipeline.id }}The pipeline identifier.
CI Job{{ .ci_job.id }}The CI/CD job identifier.
User{{ .user.id }}The user identifier.
User{{ .user.username }}The username.

All variables should be referenced using the double curly brace syntax, for example: {{ .project.id }}. See text/template documentation for more information on the templating system used.

Managed resource labels and annotations

The resources created by GitLab use a series of labels and annotations for tracking and troubleshooting purposes.

The following labels are defined on every resource created by GitLab. The values are intentionally left empty:

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

On every resource created by GitLab, an agent.gitlab.com/env-<kubernetes_namespace> annotation is defined. The value of the annotation is a JSON object with the following keys:

KeyDescription
environment_idThe GitLab environment ID.
environment_nameThe GitLab environment name.
environment_slugThe GitLab environment slug.
environment_page_urlThe link to the GitLab environment page.
environment_tierThe GitLab environment deployment tier.
agent_idThe agent ID.
agent_nameThe agent name.
agent_urlThe agent URL in the agent registration project.
project_idThe GitLab project ID.
project_slugThe GitLab project slug.
project_pathThe full GitLab project path.
project_urlThe link to the GitLab project.
template_nameThe name of the template used.

Troubleshooting

Any errors related to managed Kubernetes resources can be found on:

  • The environment page in your GitLab project
  • The CI/CD job logs when using the feature in pipelines