Dashboard for Kubernetes

Version history
  • Introduced in GitLab 16.1, with flags named environment_settings_to_graphql, kas_user_access, kas_user_access_project, and expose_authorized_cluster_agents. This feature is in Beta.
  • Feature flag environment_settings_to_graphql removed in GitLab 16.2.
  • Feature flags kas_user_access, kas_user_access_project, and expose_authorized_cluster_agents removed in GitLab 16.2.

Use the Dashboard for Kubernetes to understand the status of your clusters with an intuitive visual interface. The dashboard works with every connected Kubernetes cluster, whether you deployed them with CI/CD or GitOps.

Configure a dashboard

Version history
  • Filtering resources by namespace introduced in GitLab 16.2 with a flag named kubernetes_namespace_for_environment. Disabled by default.
  • Filtering resources by namespace enabled by default in GitLab 16.3. Feature flag kubernetes_namespace_for_environment removed.
  • Selecting the related Flux resource introduced in GitLab 16.3 with a flag named flux_resource_for_environment.
  • Selecting the related Flux resource generally available in GitLab 16.4. Feature flag flux_resource_for_environment removed.

Configure a dashboard to use it for a given environment. You can configure dashboard for an environment that already exists, or add one when you create an environment.

Prerequisites:

  • The agent for Kubernetes must be shared with the environment’s project, or its parent group, using the user_access keyword.
  • Self-managed only. KAS is running on the GitLab subdomain. For example, kas.example.com and example.com.

The environment already exists

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Operate > Environments.
  3. Select the environment to be associated with the agent for Kubernetes.
  4. Select Edit.
  5. Select a GitLab agent for Kubernetes.
  6. Optional. From the Kubernetes namespace dropdown list, select a namespace.
  7. Optional. From the Flux resource dropdown list, select a Flux resource.
  8. Select Save.

The environment doesn’t exist

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Operate > Environments.
  3. Select New environment.
  4. Complete the Name field.
  5. Select a GitLab agent for Kubernetes.
  6. Optional. From the Kubernetes namespace dropdown list, select a namespace.
  7. Optional. From the Flux resource dropdown list, select a Flux resource.
  8. Select Save.

View a dashboard

To view a configured dashboard:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Operate > Environments.
  3. Expand the environment associated with the agent for Kubernetes.
  4. Expand Kubernetes overview.

Flux sync status

Version history
  • Introduced in GitLab 16.3.
  • Customizing the name of the Flux resource introduced in GitLab 16.3 with a flag named flux_resource_for_environment.
  • Customizing the name of the Flux resource generally available in GitLab 16.4. Feature flag flux_resource_for_environment removed.

You can review the sync status of your Flux deployments from a dashboard. To display the deployment status, your dashboard must be able to retrieve the Kustomization and HelmRelease resources, which requires a namespace to be configured for the environment.

By default, GitLab searches the Kustomization and HelmRelease resources for the name of the project slug. You can specify the resource names with the Flux resource dropdown list in the environment settings.

A dashboard displays one of the following status badges:

StatusDescription
ReconciledThe deployment successfully reconciled with its environment.
ReconcilingA reconciliation is in progress.
StalledA reconciliation is stuck because of an error that cannot be resolved without human intervention.
FailedThe deployment couldn’t reconcile because of an unrecoverable error.
UnknownThe sync status of the deployment couldn’t be retrieved.
UnavailableThe Kustomization or HelmRelease resource couldn’t be retrieved.

Troubleshooting

When working with the Dashboard for Kubernetes, you might encounter the following issues.

User cannot list resource in API group

You might get an error that states Error: services is forbidden: User "gitlab:user:<user-name>" cannot list resource "<resource-name>" in API group "" at the cluster scope.

This error happens when a user is not allowed to do the specified operation in the Kubernetes RBAC.

To resolve, check your RBAC configuration. If the RBAC is properly configured, contact your Kubernetes administrator.