Customize Agent Config and Staging Environment

In this guide, you'll learn how to tailor your GitLab Kubernetes agent configuration, set up a staging environment, and scope CI/CD variables to streamline deployments. By the end, your CI jobs will use kubectl against your cluster, and your team can view the Kubernetes dashboard directly in GitLab.

1. Configure the GitLab Agent

First, create a config.yaml for your Kubernetes agent to enable GitOps workflows, CI/CD deployments, and dashboard access. Place this file in your repository’s default branch under:

.gitlab/agents/<agent-name>/config.yaml

Note

Replace <agent-name> with your actual agent identifier, and ensure you commit to the branch marked as default in your project's Branches page.

The image shows a GitLab documentation page about installing an agent for Kubernetes, with instructions on creating an agent configuration file. The sidebar lists related topics and installation steps.

Check which branch is set as default (commonly main):

The image shows a GitLab repository page displaying active branches, including "feature/setting-up-gitlab-cicd" and "main," with details about recent commits and branch status.

Add the following content to config.yaml:

ci_access:
  projects:
    # Allow CI jobs to deploy manifests in this project
    - id: demos-group/solar-system

user_access:
  access_as:
    agent: {}
  projects:
    # Permit users to view the Kubernetes dashboard in this project
    - id: demos-group/solar-system

Commit and push to your default branch. After the push, confirm the agent status:

The image shows a GitLab interface displaying the status of a Kubernetes agent named "kk-gitlab-agent," which is connected and has a valid access token. The left sidebar includes various options like "Manage," "Plan," "Code," and "Kubernetes clusters."

Now, CI jobs receive a kubeconfig context for kubectl commands, and users can access the Kubernetes dashboard within GitLab environments.

You can verify the available contexts in any job script:

kubectl config get-contexts
CURRENT   NAME
*         vke-479a34c5-9e64-4042-aee3-8af8df9686dc

2. Enable the Kubernetes Dashboard

To visualize cluster resources, enable the Kubernetes dashboard in GitLab:

Dashboard for Kubernetes

The image shows a GitLab documentation page for the "Dashboard for Kubernetes," detailing its features and usage. It includes a sidebar with navigation options and a section on configuring and viewing the dashboard.

In your project, go to Operations > Environments and click New environment.
Set the Environment name to staging, select your GitLab agent, and optionally specify a Kubernetes namespace (leave blank to display all).
Click Save. The Overview dashboard now lists your Kubernetes services:
After deploying workloads, the dashboard reflects the live status and health:

On paid GitLab tiers, you’ll also see the extended Monitoring view:

The image shows a GitLab documentation page for the "Dashboard for Kubernetes," detailing features and configuration options for monitoring Kubernetes clusters. It includes a visual interface with status indicators for running, pending, succeeded, and failed pods.

3. Scope CI/CD Variables to Staging

Isolate settings for your staging environment by defining environment-scoped variables:

Navigate to Settings > CI/CD > Variables.
Click Add variable.
Enter your keys and values, then set Environment scope to staging:

Key: NAMESPACE
Value: staging

Key: REPLICAS
Value: "4"

The image shows a GitLab CI/CD settings page with a list of environment variables, some of which are masked. There's also a sidebar for adding a new variable with options for type, environment, and flags.

Warning

Scoped variables only apply to jobs that target the staging environment. Ensure your .gitlab-ci.yml uses the correct environment name.

With these steps complete, your agent is configured, your staging environment is ready, and your CI/CD variables are scoped for targeted deployments.

References

Watch Video

Watch video content