Cluster Access¶

This guide covers how to configure kubectl access to the Kubernetes cluster using OIDC authentication via Authentik.

Prerequisites¶

Tool	Installation
kubectl	`brew install kubectl`
kubelogin	`brew install kubelogin`
yq	`brew install yq`

Cross-platform: Linux/Windows users can download binaries from kubectl releases and kubelogin releases.

OIDC Authentication Setup¶

Create Kubeconfig¶

Create the kubeconfig file at ~/.kube/configs/fzymgc-house-oidc.yml:

apiVersion: v1
kind: Config
clusters:
  - name: fzymgc-house
    cluster:
      server: https://192.168.20.140:6443
      certificate-authority-data: <base64-encoded-ca>
contexts:
  - name: fzymgc-house-oidc
    context:
      cluster: fzymgc-house
      user: oidc
users:
  - name: oidc
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubectl
        args:
          - oidc-login
          - get-token
          - --oidc-issuer-url=https://auth.fzymgc.house/application/o/kubernetes/
          - --oidc-client-id=kubernetes
        interactiveMode: IfAvailable
current-context: fzymgc-house-oidc

Get the CA Certificate¶

Extract from any control plane node:

ssh tpi-alpha-1 'sudo cat /etc/rancher/k3s/k3s.yaml' | yq '.clusters[0].cluster.certificate-authority-data'

Set KUBECONFIG¶

export KUBECONFIG=~/.kube/configs/fzymgc-house-oidc.yml

Add to your shell profile for persistence.

Run any kubectl command to trigger browser authentication:

kubectl get nodes
# Browser opens → Login to Authentik → Return to terminal

Available Contexts¶

Context	Description
`fzymgc-house-oidc`	Standard user access via OIDC (default)
`fzymgc-house-admin`	Admin access (break-glass, static token)
`docker-desktop`	Local Docker Desktop cluster

Access Levels¶

Access is determined by Authentik group membership:

Authentik Group	Kubernetes Role	Permissions
k8s-admins	cluster-admin	Full cluster access
k8s-developers	edit	Create/modify workloads (no RBAC)
k8s-viewers	view	Read-only access

Token Lifecycle¶

Token	Lifetime	Behavior
Access	15 min	Auto-refreshes silently
Refresh	8 hours	Browser re-auth when expired

API Server Access¶

Endpoint	Address
API Server VIP	`192.168.20.140:6443`
Load balanced via	kube-vip

Break-Glass Access¶

When Authentik is unavailable, use the static admin kubeconfig:

export KUBECONFIG=~/.kube/configs/fzymgc-house-admin.yml
kubectl --context fzymgc-house get nodes

Warning: Admin kubeconfig has full cluster-admin privileges. Use only for emergencies.

Troubleshooting¶

Browser Doesn't Open¶

Try manual browser flow:

kubectl oidc-login get-token \
  --oidc-issuer-url=https://auth.fzymgc.house/application/o/kubernetes/ \
  --oidc-client-id=kubernetes

Token Expired During Long Operation¶

OIDC tokens expire after 15 minutes and cannot be refreshed mid-stream. Use admin kubeconfig for streaming operations like kubectl logs -f.

Group Membership Not Updated¶

Clear token cache and re-authenticate:

rm -rf ~/.kube/cache/oidc-login
kubectl get nodes  # Re-authenticates

Certificate Errors¶

Ensure the cluster CA is trusted. If testing, use --insecure-skip-tls-verify temporarily.

Verify Authentik is accessible: https://auth.fzymgc.house
Check browser for authentication errors
Review kubeconfig OIDC settings