homelab/ansible/KUBECONFIG_MANAGEMENT.md

Kubeconfig Management - Modular & Repeatable

This document explains the modular kubeconfig management system for your homelab's multiple Kubernetes clusters.

Overview

The kubeconfig management has been refactored into reusable, modular components that can handle multiple clusters seamlessly:

• FastPass (Vanilla Kubernetes)
• Hub Cluster (OpenShift SNO)
• Internal Cluster (OpenShift)
• Future clusters (easily extensible)

Architecture

ansible/playbooks/roles/
├── kubeconfig-manager/          # Core reusable role
│   ├── tasks/main.yml          # Main entry point
│   ├── tasks/merge-kubeconfig.yml  # Merging logic
│   ├── defaults/main.yml       # Default variables
│   └── README.md               # Role documentation
├── cluster-kubeconfig/         # Generic wrapper role
└── fastpass-first-control-plane/  # Uses kubeconfig-manager

Quick Usage

1. Using the Script (Easiest)

cd ansible

# Setup FastPass cluster kubeconfig
./scripts/setup-kubeconfig.sh fastpass fastpass_control_plane[0]

# Setup Hub cluster kubeconfig  
./scripts/setup-kubeconfig.sh hub hub_cluster

# Setup Internal cluster kubeconfig
./scripts/setup-kubeconfig.sh internal internal_cluster[0]

2. Direct Ansible Usage

# Single cluster
ansible-playbook -i inventory.yml \
  playbooks/examples/multi-cluster-kubeconfig.yml \
  --limit fastpass_control_plane[0] \
  -e target_cluster_name=fastpass

# Multiple clusters at once
ansible-playbook -i inventory.yml \
  playbooks/examples/multi-cluster-kubeconfig.yml

3. In Your Own Playbooks

- name: Setup kubeconfig for any cluster
  hosts: my_cluster_nodes[0]
  roles:
    - role: kubeconfig-manager
      vars:
        cluster_name: "my-cluster"
        kubeconfig_source_path: "/etc/kubernetes/admin.conf"

Features

✅ Modular & Reusable

• Single role works with any Kubernetes cluster
• Easy to extend for new clusters
• Consistent behavior across all clusters

✅ Safe Operations

• Automatic backups before merging
• Non-destructive merging
• Preserves existing contexts

✅ Multi-Cluster Ready

• Unique naming: cluster-name-admin
• No conflicts between clusters
• Easy context switching

✅ Homelab Optimized

• Works with vanilla Kubernetes
• Works with OpenShift
• Handles different kubeconfig paths

Generated Structure

After running the kubeconfig management:

~/.kube/
├── config                      # Merged config with all clusters
├── config-fastpass            # Individual cluster configs
├── config-hub
├── config-internal
└── config.backup.1697123456   # Timestamped backups

Context Management

# List all available contexts
kubectl config get-contexts

# Switch between clusters
kubectl config use-context fastpass-admin
kubectl config use-context hub-admin
kubectl config use-context internal-admin

# Check current context
kubectl config current-context

# Test connectivity
kubectl cluster-info
kubectl get nodes

Integration with Existing Roles

Before (Monolithic)

# fastpass-first-control-plane/tasks/main.yml
- name: 50+ lines of kubeconfig logic
  # Lots of repetitive code

After (Modular)

# fastpass-first-control-plane/tasks/main.yml
- name: Setup kubeconfig for FastPass cluster
  ansible.builtin.include_role:
    name: kubeconfig-manager
  vars:
    cluster_name: "{{ cluster_name }}"

Adding New Clusters

To add a new cluster (e.g., "edge-cluster"):

1. Add to inventory:

edge_cluster:
  hosts:
    edge-node-01:

2. Use the script:

./scripts/setup-kubeconfig.sh edge edge_cluster[0]

3. Or add to playbook:

- name: Setup kubeconfig for Edge cluster
  hosts: edge_cluster[0]
  roles:
    - role: kubeconfig-manager
      vars:
        cluster_name: "edge"

Customization

Different Kubeconfig Paths

- role: kubeconfig-manager
  vars:
    cluster_name: "openshift-cluster"
    kubeconfig_source_path: "/etc/kubernetes/static-pod-resources/kube-apiserver-certs/secrets/node-kubeconfigs/localhost.kubeconfig"

Custom Context Names

- role: kubeconfig-manager
  vars:
    cluster_name: "prod"
    context_suffix: "system:admin"  # Results in "prod-system:admin"

Troubleshooting

Common Issues

1. Permission Denied

   # Fix ownership
   sudo chown -R $USER:$USER ~/.kube/
   

2. Context Not Found

   # List available contexts
   kubectl config get-contexts
   
   # Check if cluster was added
   kubectl config view
   

3. Backup Recovery

   # Restore from backup
   cp ~/.kube/config.backup.1697123456 ~/.kube/config
   

Debug Mode

# Run with verbose output
ansible-playbook -vvv playbooks/examples/multi-cluster-kubeconfig.yml

Benefits for Your Homelab

1. Consistency: Same process for all clusters
2. Maintainability: Single role to update/fix
3. Scalability: Easy to add new clusters
4. Safety: Automatic backups and safe merging
5. Flexibility: Works with different Kubernetes distributions

Next Steps

1. Test the modular approach with your FastPass cluster
2. Extend to Hub and Internal clusters using the same pattern
3. Create cluster-specific variables in group_vars if needed
4. Add monitoring/validation tasks to verify kubeconfig health

This modular approach makes your homelab's multi-cluster management much more maintainable and repeatable!