For the complete documentation index, see llms.txt. This page is also available as Markdown.

kubectl Access

Point the standard kubectl, k9s or Lens at groundcover and read your clusters from groundcover's stored data, with groundcover RBAC deciding what each caller sees.

groundcover serves a read-only Kubernetes API for every cluster it monitors. You add it to your kubeconfig like any other cluster and use the tools you already have: kubectl, k9s, Lens or Freelens. No plugin or extra CLI is needed.

Setting up a groundcover kubectl context, then listing nodes and pods, reading current and previous logs, and a refused delete
Add a groundcover context, then use kubectl as usual

Requests are answered from the data groundcover already stores (entities, logs, events and resource usage), not from the cluster's API server. That means:

  • No cluster credentials to hand out. Engineers, CI jobs and coding agents get kubectl access through a groundcover API key instead of a cluster kubeconfig.

  • groundcover RBAC applies. The API key's policies decide which clusters, environments and namespaces the caller sees, the same as in the UI. Objects and kubectl top usage follow the policy's workloads scope, kubectl logs its logs scope, and events its events scope.

  • Read-only by design. Every write through the Kubernetes API is refused.

  • Logs outlive the node. kubectl logs reads groundcover's log storage, so it returns lines the node has already rotated away, and --previous keeps working after the node has cleaned up the previous container. What is returned follows your log pipelines, sampling and retention.

  • The cluster is not touched. Queries run against groundcover's storage, so heavy use puts no load on the cluster's control plane.

Set up

1. Create an API key

An API key sees what its service account's policies allow. To give kubectl access to the whole workspace, use a service account bound to the groundcover Read Only policy. To limit it to specific clusters or namespaces:

  1. Create a policy. Go to Settings > Policies and click Create Policy. Give it a Policy title and set Permissions Level to Read Only. Under Data Scope, keep Simple and fill in the conditions: Cluster in the clusters the key may see, and Namespace in the namespaces it may see. Use 'And' Condition to add another condition, such as Environment. Then click Create Policy.

  2. Create a service account. Go to Settings > Access > Service Accounts, click Create Service Account, and under Policies assign only this policy. See Service Accounts. A service account's access is the union of all its policies, so one broader policy widens what the key sees.

  3. Create the key. Go to Settings > Access > API Keys, click Create API Key, and choose that service account. See API Keys.

With such a key, kubectl lists only objects, logs, events and usage inside the scope. Other namespaces don't exist from kubectl's point of view, and cluster-wide kinds such as nodes and persistent volumes return nothing when the scope names a namespace.

2. Find your backend ID and cluster name

The server URL names a backend and a cluster. A backend is a groundcover deployment that stores data for one or more clusters. Most workspaces have one.

In the UI:

  • Backend ID: go to Settings > Access > API Keys. The backend ID is shown on that page.

  • Cluster name: open the cluster selector at the top of any page. The cluster names listed there are the names to use.

With the API, using the same API key. Replace api.groundcover.com with your own groundcover address if you are self-hosted:

3. Add a kubeconfig context

The server URL names the backend and the cluster:

Use your own groundcover address. The examples use https://api.groundcover.com. Self-hosted, on-prem and air-gapped deployments replace it with the address of their groundcover environment, and keep the rest of the path as is.

Set the three values, if you have not already, and add a context with kubectl config:

Or write the kubeconfig entries directly:

Add one context per cluster. They can share the same user entry.

Check the connection:

k9s, Lens and Freelens read the same kubeconfig. Select the groundcover context and they work without further setup.

Example commands

Browse resources

Filter and sort

Extract fields

Inspect

Logs

Logs are read from groundcover's log storage. Without --since, the last 24 hours are searched.

Resource usage

Watch

Custom resources

Custom resources that groundcover stores are discovered automatically and served like built-in kinds:

Check access

What is served

API group
Resources

core (v1)

pods (with log), nodes, namespaces, events, configmaps, persistentvolumes, persistentvolumeclaims

apps/v1

deployments, replicasets, statefulsets, daemonsets

batch/v1

jobs, cronjobs

metrics.k8s.io/v1beta1

pods, nodes (for kubectl top)

Custom resources

Every custom resource kind groundcover stores for the cluster

Resources support get, list and watch, with label selectors, field selectors, paging and table output. Events are listed per namespace.

Limitations

  • Read-only. apply, create, edit, delete, scale, patch, rollout restart, cordon and drain are refused.

  • No live connection to the cluster. exec, attach, port-forward and cp are not available.

  • Secrets are never served.

  • Only kinds groundcover stores are served. Other kinds, such as Services, Ingresses and RBAC objects, return "the server doesn't have a resource type".

  • kubectl explain is not available, since no OpenAPI schema is served.

  • Data is as fresh as groundcover's last update of the cluster, not the cluster's live state. --watch checks for changes about every 15 seconds.

  • Custom resources are not converted between versions. Each object is returned under the API version it was stored with.

  • kubectl auth can-i reflects what the API serves, not your groundcover policy. Which objects you see is decided by the API key's data scope.

Last updated