Skip to main content

Kubeconfig Management

This guide covers downloading and using kubeconfig files to access Kubernetes clusters with kubectl and other Kubernetes tools.

Overview​

The kubeconfig file contains the credentials and configuration needed to access clusters with kubectl and other Kubernetes tools. This file provides secure authentication and cluster endpoint information.

What is Kubeconfig?​

  • Authentication: Contains cluster access credentials and certificates
  • Configuration: Cluster endpoint URLs and connection settings
  • Context: Cluster context information for kubectl
  • Security: Encrypted credentials for secure cluster access

Download Requirements​

Before downloading kubeconfig, ensure you meet these requirements:

Prerequisites​

  • Cluster Status: Must be in "Active" state
  • Permissions: Appropriate access permissions to the cluster
  • Browser: Modern browser with download capabilities
  • Network Access: Stable internet connection

Access Verification​

  1. Cluster Health: Verify cluster is operational and healthy
  2. User Permissions: Confirm you have cluster access rights
  3. Browser Compatibility: Ensure browser supports file downloads
  4. Security Settings: Check browser security settings allow downloads

Download Process​

Step-by-Step Instructions​

1. Navigate to Cluster Overview​

  1. Go to the Kubernetes service dashboard
  2. Click on Clusters → Cluster Management
  3. Click on the cluster name to access cluster details
  4. Navigate to the cluster overview page

2. Verify Cluster Status​

  1. Check the cluster status in the overview page
  2. Ensure the status shows "Active" with green indicator
  3. Verify worker nodes and master status are healthy
  4. Confirm ingress status is operational

3. Download Kubeconfig​

  1. Locate the "Download Kubeconfig" button in the page header
  2. Verify the button is enabled (not grayed out)
  3. Click the "Download Kubeconfig" button
  4. The file will download automatically to the browser's download folder

Download Behavior​

File Information​

  • File Name: Typically named after your cluster (e.g., KubeConfig.yaml)
  • File Format: YAML configuration file
  • File Location: Browser default download folder

Using Kubeconfig​

# Set the kubeconfig file path
export KUBECONFIG=/path/to/downloaded/kubeconfig.yaml

# Verify connection
kubectl get nodes

# Check cluster information
kubectl cluster-info

Option 2: Direct File Reference​

# Use kubeconfig directly without setting environment variable
kubectl --kubeconfig=/path/to/kubeconfig.yaml get nodes

# Check cluster status
kubectl --kubeconfig=/path/to/kubeconfig.yaml get pods -A

Option 3: Copy to Default Location​

# Copy to kubectl's default location
cp /path/to/downloaded/kubeconfig.yaml ~/.kube/config

# Verify connection
kubectl get nodes

# No additional configuration needed

Verifying Access​

Connection Tests​

# Test basic connectivity
kubectl cluster-info

# List all nodes in the cluster
kubectl get nodes -o wide

# Check cluster component status
kubectl get componentstatuses

# List running pods across all namespaces
kubectl get pods -A

Expected Output​

# Successful connection example
$ kubectl get nodes
NAME                                          STATUS   ROLES    AGE   VERSION
k8s-c-berniepro-zpr90x-worker-0329b8b2        Ready    worker   2d    v1.32.0
k8s-c-berniepro-zpr90x-worker-19e99c41        Ready    worker   2d    v1.32.0
k8s-c-berniepro-zpr90x-worker-aa3e2cdd        Ready    master   2d    v1.32.0

Troubleshooting Access​

Common Issues​

Connection Timeouts

# Symptoms
kubectl get nodes
# Error: Unable to connect to the server: dial tcp: i/o timeout

# Solutions
1. Verify cluster is active in dashboard
2. Check internet connectivity
3. Verify kubeconfig file path
4. Re-download kubeconfig if expired

Authentication Failures

# Symptoms  
kubectl get nodes
# Error: error validating data: couldn't get version/kind

# Solutions
1. Re-download fresh kubeconfig file
2. Verify file wasn't corrupted during download
3. Check file permissions are readable
4. Ensure cluster certificates haven't expired

Permission Denied

# Symptoms
kubectl get nodes  
# Error: forbidden: User cannot list resource "nodes"

# Solutions
1. Verify user has appropriate cluster permissions
2. Contact administrator for access rights
3. Check RBAC configuration
4. Re-download kubeconfig with proper permissions

Kubeconfig Security​

Security Best Practices​

File Security​

  1. Secure Storage: Store kubeconfig files in secure locations
  2. File Permissions: Set restrictive file permissions
  3. Access Control: Limit access to authorized personnel only
  4. Backup Security: Secure backup of important kubeconfig files

Permission Management​

# Set secure permissions on kubeconfig file
chmod 600 ~/.kube/config

# Verify permissions
ls -la ~/.kube/config
# Should show: -rw------- (600 permissions)

# Remove group and other access
chmod go-rwx /path/to/kubeconfig.yaml

Regular Maintenance​

  1. Regular Rotation: Re-download kubeconfig periodically for security
  2. Access Review: Regularly review who has kubeconfig access
  3. Cleanup: Remove old or unused kubeconfig files
  4. Monitoring: Monitor kubectl usage and access patterns

Security Warnings​

Never Share Kubeconfig​

  • Individual Access: Each user should have their own kubeconfig
  • No Sharing: Never share kubeconfig files with unauthorized users
  • Version Control: Never commit kubeconfig files to version control
  • Public Storage: Never store kubeconfig in public locations

Secure Transmission​

  • Encrypted Channels: Only transmit kubeconfig over encrypted channels
  • Secure Storage: Use encrypted storage for kubeconfig files
  • Time Limits: Consider kubeconfig as time-sensitive credentials
  • Revocation: Know how to revoke access if kubeconfig is compromised

Advanced Usage​

Multiple Clusters​

Managing Multiple Kubeconfigs​

# Set up multiple cluster contexts
export KUBECONFIG=~/.kube/cluster1-config:~/.kube/cluster2-config

# List available contexts
kubectl config get-contexts

# Switch between clusters
kubectl config use-context cluster1-context
kubectl config use-context cluster2-context

# Check current context
kubectl config current-context

Context Management​

# Rename context for clarity
kubectl config rename-context old-name production-cluster

# Set default namespace for context
kubectl config set-context production-cluster --namespace=production

# View full kubeconfig
kubectl config view

Integration with Tools​

IDE Integration​

  • VS Code: Kubernetes extension uses kubeconfig automatically
  • IntelliJ: Kubernetes plugin supports kubeconfig files
  • Terminal: Export KUBECONFIG for all terminal sessions

CI/CD Integration​

  • Secure Storage: Store kubeconfig in secure CI/CD secrets
  • Limited Scope: Use service accounts with limited permissions
  • Rotation: Regularly rotate CI/CD kubeconfig files