Dashboard for Kubernetes
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
- Status: Beta
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
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:
- A GitLab agent for Kubernetes is installed and
user_access
is configured for the environment’s project or its parent group.
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments.
- Select the environment to be associated with the agent for Kubernetes.
- Select Edit.
- Select a GitLab agent for Kubernetes.
- Optional. From the Kubernetes namespace dropdown list, select a namespace.
- Optional. From the Flux resource dropdown list, select a Flux resource.
- Select Save.
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments.
- Select New environment.
- Complete the Name field.
- Select a GitLab agent for Kubernetes.
- Optional. From the Kubernetes namespace dropdown list, select a namespace.
- Optional. From the Flux resource dropdown list, select a Flux resource.
- Select Save.
Configure a dashboard for a dynamic environment
To configure a dashboard for a dynamic environment:
- Specify the agent in your
.gitlab-ci.yml
file. You must specify the full path to the agent configuration project, followed by a colon and the name of the agent.
For example:
deploy_review_app:
stage: deploy
script: make deploy
environment:
name: review/$CI_COMMIT_REF_SLUG
kubernetes:
agent: path/to/agent/project:agent-name
For more information, see the CI/CD YAML syntax reference.
View a dashboard
View a dashboard to see the status of connected clusters.
If the k8s_watch_api
feature flag is enabled, the status of your
Kubernetes resources and Flux reconciliation updates in real time.
To view a configured dashboard:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments.
- Select the environment associated with the agent for Kubernetes.
- Select the Kubernetes overview tab.
A list of pods is displayed. Select a pod to view its details.
Flux sync status
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.
GitLab searches the Kustomization
and HelmRelease
resources specified by the Flux resource dropdown list in the environment settings.
A dashboard displays one of the following status badges:
Status | Description |
---|---|
Reconciled | The deployment successfully reconciled with its environment. |
Reconciling | A reconciliation is in progress. |
Stalled | A reconciliation is stuck because of an error that cannot be resolved without human intervention. |
Failed | The deployment couldn’t reconcile because of an unrecoverable error. |
Unknown | The sync status of the deployment couldn’t be retrieved. |
Unavailable | The Kustomization or HelmRelease resource couldn’t be retrieved. |
Trigger Flux reconciliation
You can manually reconcile your deployment with its Flux resources.
To trigger a reconciliation:
- On a dashboard, select the sync status badge of a Flux deployment.
- Select Actions ( ) > Trigger reconciliation ( ).
Suspend or resume Flux reconciliation
You can manually suspend or resume your Flux reconciliation from the UI.
To suspend or resume reconciliation:
- On a dashboard, select the sync status badge of a Flux deployment.
- Select Actions (
), then choose one of the following:
- Suspend reconciliation ( ) to pause the Flux reconciliation.
- Resume reconciliation ( ) to restart the Flux reconciliation.
View pod logs
View pod logs when you want to quickly understand and troubleshoot issues across your environments from a configured dashboard. You can view logs for each container in a pod.
- Select View logs, then select the container you want to view logs for.
You can also view pod logs from the pod details.
Delete a pod
To restart a failed pod, delete it from the Kubernetes dashboard.
To delete a pod:
- On the Kubernetes overview tab, find the pod you want to delete.
- Select Actions ( ) > Delete pod ( ).
You can also delete a pod from the pod details.
Detailed dashboard
The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
The detailed dashboard provides information about the following Kubernetes resources:
- Pods
- Services
- Deployments
- ReplicaSets
- StatefulSets
- DaemonSets
- Jobs
- CronJobs
Each dashboard displays a list of resources with their statuses, namespaces, and age. You can select a resource to open a drawer with more information, including labels and YAML-formatted status, annotations, and spec.
Because of the focus shift described in this issue, work on the detailed dashboard is paused.
To provide feedback on the detailed dashboard, see issue 460279.
View a detailed dashboard
Prerequisites:
- A GitLab agent for Kubernetes is configured and shared with the environment’s project, or its parent group, using the
user_access
keyword.
The detailed dashboard is not linked from the sidebar navigation. To view a detailed dashboard:
- Find your agent for Kubernetes ID:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Kubernetes clusters.
- Copy the numerical ID of the agent you want to access.
- Go to one of the following URLs, replacing
<agent_id>
with your agent ID:Resource type URL Pods https://myinstance.gitlab.com/-/kubernetes/<agent_id>/pods
Services https://myinstance.gitlab.com/-/kubernetes/<agent_id>/services
Deployments https://myinstance.gitlab.com/-/kubernetes/<agent_id>/deployments
ReplicaSets https://myinstance.gitlab.com/-/kubernetes/<agent_id>/replicaSets
StatefulSets https://myinstance.gitlab.com/-/kubernetes/<agent_id>/statefulSets
DaemonSets https://myinstance.gitlab.com/-/kubernetes/<agent_id>/daemonSets
Jobs https://myinstance.gitlab.com/-/kubernetes/<agent_id>/jobs
CronJobs https://myinstance.gitlab.com/-/kubernetes/<agent_id>/cronJobs
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.
GitLab agent dropdown list is empty
When you configure a new environment, the GitLab agent dropdown list might be empty, even if you have configured Kubernetes clusters.
To populate the GitLab agent dropdown list, grant an agent Kubernetes access with the user_access
keyword.
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