GitLab-managed Kubernetes resources
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
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:
- You must have a configured GitLab agent for Kubernetes.
- You have authorized the agent to access relevant projects or groups.
- (Optional) You have configured agent impersonation to prevent privilege escalations. The default environment template assumes you have configured
ci_job
impersonation.
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:
Category | Variable | Description |
---|---|---|
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:
Key | Description |
---|---|
environment_id | The GitLab environment ID. |
environment_name | The GitLab environment name. |
environment_slug | The GitLab environment slug. |
environment_page_url | The link to the GitLab environment page. |
environment_tier | The GitLab environment deployment tier. |
agent_id | The agent ID. |
agent_name | The agent name. |
agent_url | The agent URL in the agent registration project. |
project_id | The GitLab project ID. |
project_slug | The GitLab project slug. |
project_path | The full GitLab project path. |
project_url | The link to the GitLab project. |
template_name | The 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
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support