Skip to content

Cluster access

Install the tools

On macOS with Homebrew:

brew install kubectl
brew install derailed/k9s/k9s
brew install kubelogin

For other platforms: kubectl, k9s and kubelogin. If you already use Krew, kubectl krew install oidc-login installs the login plugin instead.

Less typing with k

Add alias k=kubectl to ~/.zshrc (or ~/.bashrc for Bash). Open a new terminal, or run the alias command in your current terminal, then use k wherever these guides use kubectl.

Set up your kubeconfig

Download the combined kubeconfig or view its YAML. Everyone uses the same file; it contains connection details and login configuration, with no embedded credentials. Your Authentik account and groups determine your access.

Keep the work kubeconfig in its own file so it stays separate from your other cluster configurations:

mkdir -p ~/.kube
chmod 700 ~/.kube
cp ~/Downloads/kubeconfig-oidc.yaml ~/.kube/work-config
chmod 600 ~/.kube/work-config
export KUBECONFIG="$HOME/.kube/work-config"

Save the export in your shell configuration so new terminals use it too. Run the command for your shell once:

echo 'export KUBECONFIG="$HOME/.kube/work-config"' >> ~/.zshrc

echo 'export KUBECONFIG="$HOME/.kube/work-config"' >> ~/.bashrc

The export above already applies to your current terminal. Both kubectl and k9s will use this file. Without KUBECONFIG, they normally use ~/.kube/config.

Authentication happens automatically when a tool contacts the cluster. Sign in through Authentik and MFA when prompted; subsequent commands reuse the cached login.

Choose a cluster and start working

A context selects the cluster. First, list the available contexts:

kubectl config get-contexts

Switch to trackpac, then specify the namespace with -n (short for --namespace) when running commands:

kubectl config use-context trackpac
kubectl get -n trackpac pods

Switch to connectiot or bovisen-us the same way. Run kubectl config current-context to check the selected cluster. Continue with working with clusters for k9s and making changes.

Permissions and login problems

Ask an administrator for the required Authentik groups:

Group Access
k8s-readonly Read across all clusters, including nodes; excludes Secrets.
k8s-trackpac-maintainer Admin permissions across namespaces in trackpac, including Secrets.
k8s-bovisen-maintainer Admin permissions across namespaces in bovisen-us, including Secrets.
k8s-connectiot-maintainer Manage selected workloads in monitoring; no direct Secret access.
k8s-<cluster>-admin Full access on the corresponding cluster.

Group permissions add together. Maintainers also need k8s-readonly for cluster diagnostics. A Forbidden response means your permissions do not allow that operation.

To force a fresh login after a group change or authentication problem:

rm -rf ~/.kube/cache/oidc-login
kubectl auth whoami

If switching accounts, also log out of Authentik in your browser. If oidc-login is not found, check that kubelogin is installed with kubectl oidc-login --help.

Continue with working with clusters.