Cluster Access

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

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://id.fzymgc.house/realms/fzymgc
          - --oidc-client-id=kubernetes
          - --oidc-extra-scope=offline_access
          - --oidc-extra-scope=profile
          - --oidc-extra-scope=email
        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 Keycloak → 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 Keycloak group membership:

Keycloak 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 Keycloak 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.

Service Account Read-Only Access (Automation)

The sysadm/crew-homelab-ro read-only access model is managed by Ansible.

Apply or reconcile it with:

ansible-playbook -i ansible/inventory/hosts.yml ansible/k3s-playbook.yml \
  --tags k3s-readonly-access

Validate the effective permissions for the service account:

kubectl auth can-i --as=system:serviceaccount:sysadm:crew-homelab-ro list nodes
kubectl auth can-i --as=system:serviceaccount:sysadm:crew-homelab-ro list secrets -A
kubectl auth can-i --as=system:serviceaccount:sysadm:crew-homelab-ro get secrets -A

Expected:

list nodes -> yes
list secrets -A -> no
get secrets -A -> no

Troubleshooting

Browser Doesn’t Open

Try manual browser flow:

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

Token Expired During Long Operation

OIDC access tokens expire after 15 minutes. With offline_access scope configured, tokens refresh automatically. For very long streaming operations like kubectl logs -f, you may still need the admin kubeconfig if the stream outlasts the 8-hour refresh token.

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 Keycloak is accessible: https://id.fzymgc.house
Check browser for authentication errors
Review kubeconfig OIDC settings