Connect Kubernetes

• You are an owner of the Groundcrew workspace.
• You have kubectl with a cluster-admin context for the cluster, to apply the RBAC manifest.
• The cluster's API server has a public HTTPS address. Groundcrew reaches clusters over the internet and refuses private and loopback addresses.
• For deploys: Kubernetes 1.30 or later, an Ingress controller, and a registry the cluster can pull from.

Download k8s-readonly-rbac.yaml, read it, and apply it. It creates the namespace groundcrew, the service account groundcrew-reader, and a ClusterRole that can get, list, and watch namespaces, Deployments, ReplicaSets, StatefulSets, ControllerRevisions, Services, Ingresses, Pods, and events, and read pod logs.

kubectl apply -f k8s-readonly-rbac.yaml
kubectl -n groundcrew create token groundcrew-reader --duration=24h

Groundcrew accepts a kubeconfig with a service account token (or inline client certificate data) and the cluster's CA inline. It refuses exec plugins, auth providers, file paths, proxies, and plain HTTP.

SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
CA=$(kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')
TOKEN=<the token from the command above>
cat > groundcrew.kubeconfig <<EOF
apiVersion: v1
kind: Config
clusters:
  - name: cluster
    cluster:
      server: $SERVER
      certificate-authority-data: $CA
users:
  - name: groundcrew-reader
    user:
      token: $TOKEN
contexts:
  - name: groundcrew
    context: {cluster: cluster, user: groundcrew-reader}
current-context: groundcrew
EOF

In Groundcrew, open Connections and choose Upload kubeconfig. Give the cluster a name, upload groundcrew.kubeconfig or paste its contents, and choose Verify and connect. Groundcrew lists namespaces with it before saving, then stores it encrypted. Then run discovery.

A changed ConfigMap or Secret is a common cause of a broken rollout. The read-only manifest has two optional, commented-out rules that let Groundcrew see when the ones your workloads use changed. Groundcrew only ever asks for their metadata (names and change times), never their contents. Kubernetes has no metadata-only permission, though: the list right would let a client that asked differently read contents, so add them only if you accept that, and preferably with a RoleBinding in your app's namespaces.

Then choose Detect ConfigMap changes on the connection. Medic will show a changed ConfigMap as a possible cause, with a note to restore it, since it cannot restore what it does not read.

Apply k8s-operate-rbac.yaml to let the same service account roll a Deployment or StatefulSet back to its previous revision or restart it. It can only patch those two kinds and read their revisions. Then choose Enable emergency fixes on the connection; Groundcrew checks the permissions first. Every fix still waits for an approval.

A deployer account

For deploys, apply the deployer manifests from Groundcrew's repository, rbac.yaml and admission-policy.yaml. They create a groundcrew-deployer service account that can create only namespaces named gc-* labelled project=groundcrew, and work only inside them, enforced by a ValidatingAdmissionPolicy (Kubernetes 1.30 or later). Connect the cluster with that account's kubeconfig.

Deploy settings

Choose Deploy settings on the connection to set where images go and how apps are reached: the registry (with a push token, or Amazon ECR through an AWS connection that has deploys on), an optional image pull secret, the Ingress class, the app domain (apps answer at <app>.<domain>), and TLS with an optional cert-manager cluster issuer. Registry tokens are stored encrypted and never shown again.

• "Groundcrew only accepts a service account token or inline client certificate data". The kubeconfig uses an exec plugin or auth provider, which is what EKS, GKE, and AKS kubeconfigs do by default. Build one with a service account token as above.
• "Put the CA inline". The kubeconfig points at a CA file. Use certificate-authority-data, as the script above does with --raw.
• "The cluster's server … is a private or internal address". The API server is only reachable inside your network. Groundcrew cannot connect to it. Use a cluster with a public endpoint, or enable one with access limited by your provider's settings.
• "The cluster's server must use https". Plain HTTP API servers are refused.
• "rejected the kubeconfig's credentials (401)". The token expired or was revoked. Create a new one and connect again.
• "may not list … (403)". The service account's RBAC is missing that right. Apply the manifest again, or check you used the right service account.

To replace an expired token or change the service account, remove the connection and connect again with the new kubeconfig. To disconnect, remove the connection on the Connections page, which deletes everything Groundcrew discovered through it, then remove access in the cluster:

kubectl delete -f k8s-operate-rbac.yaml   # if you applied it
kubectl delete -f k8s-readonly-rbac.yaml

Apps Groundcrew deployed live in gc-* namespaces. Delete those namespaces to remove them.