Connecting with kubectl

This guide walks you through connecting to Runway staging and production Kubernetes clusters so you can query the Kubernetes API with kubectl. Access goes through the GitLab Agent for Kubernetes (KAS) proxy hosted on ops.gitlab.net. You do not need direct network access or a cloud provider login.

• An account on ops.gitlab.net that has been added to the appropriate groups (see the note below).
• kubectl installed.
• glab (the GitLab CLI) installed.

When you update your kubeconfig, glab wires glab cluster agent get-token in as a kubectl exec credential plugin. When kubectl needs to authenticate, that plugin creates a short-lived personal access token with the k8s_proxy scope, valid until the end of the current day, and uses it to talk to the cluster through the KAS proxy. glab caches the token and reuses it while it’s still valid, so it only mints a new one once the cached token expires. Either way, these tokens are managed automatically, so you never handle them directly.

1. Create a personal access token.

   Create a personal access token on ops.gitlab.net with the api scope (see How authentication works for why this scope is required).

2. Configure glab for ops.gitlab.net.

   Point glab at ops.gitlab.net using the token from the previous step. Run the command below and paste the token when prompted, which keeps it out of your shell history:

   glab auth login --hostname ops.gitlab.net

   If you’d rather script it, read the token from standard input instead of passing it on the command line. First create token.txt without exposing the token in your shell history: restrict its permissions, then write the token using a text editor or cat > token.txt (paste the token, then press Ctrl+D):

   touch token.txt && chmod 600 token.txt

   Then authenticate by reading the token from the file, and delete it afterwards:

   glab auth login --hostname ops.gitlab.net --stdin < token.txt
   rm token.txt

3. Update your kubeconfig.

   Find the cluster you want to connect to on the kas-clusters agents page. That page is the source of truth for the available clusters. To get the exact command for a cluster, click the vertical dots menu (⋮) next to it and select Connect to <cluster>, which shows the glab cluster agent update-kubeconfig command (including the agent ID) ready to copy. For example, to configure access to the cluster served by agent 70:

   GITLAB_HOST=https://ops.gitlab.net glab cluster agent update-kubeconfig \
     --repo gitlab-com/gl-infra/platform/runway/kas-clusters \
     --agent 70 --use-context \
     --cache-mode keyring-filesystem-fallback

   The --use-context flag sets the newly added cluster as your current kubectl context. The GITLAB_HOST=https://ops.gitlab.net prefix is still required even after Step 2: it points update-kubeconfig at the ops.gitlab.net instance rather than the default gitlab.com. Include the https:// scheme here (unlike the --hostname flag in Step 2, which takes a bare hostname).

   The --cache-mode flag controls where glab caches the token, and its value is written into the exec-plugin config in ~/.kube/config. The default, force-keyring, fails on machines without a running keyring (headless Linux, CI, containers), so this example uses keyring-filesystem-fallback, which prefers the OS keyring when available and falls back to filesystem storage when it isn’t. The command copied from the Connect to UI omits this flag and inherits the force-keyring default, so add it yourself.

4. Verify connectivity.

   List pods across all namespaces:

   kubectl get pods -A

   A successful connection returns a listing of pods across the cluster’s namespaces.

• Token expiry: the short-lived k8s_proxy tokens are valid until the end of the current day. glab caches and reuses a token while it’s valid and mints a fresh one once it expires, so no action is needed from you.
• Bootstrap PAT expiry: if kubectl commands suddenly start failing with authentication errors, the ops.gitlab.net PAT you created in Step 1 may have expired. Once it does, glab can no longer mint new k8s_proxy tokens. Create a new PAT and re-run glab auth login (Step 2) to restore access.
• Keyring errors on headless machines: if kubectl or glab fails with a keyring, dbus, or secret-service style error, your kubeconfig is using the force-keyring cache mode (the default, and what the Connect to UI generates). Re-run update-kubeconfig with --cache-mode keyring-filesystem-fallback, or edit the --cache-mode value in ~/.kube/config. See the get-token options for the available modes.
• Read-only access: any write operation against a staging or production cluster will be denied. This is expected.
• Need help?: reach out in #f_runway.