Cluster Connection

Overview

Orphelix connects to Kubernetes clusters using your local kubeconfig file. Switch between multiple clusters and contexts seamlessly from the dashboard. Cluster Connection

How Cluster Connection Works

Orphelix uses the standard Kubernetes authentication method:

Read Kubeconfig

Loads ~/.kube/config on server startupLocation can be overridden with KUBECONFIG env var

List Contexts

Extracts all available contexts from kubeconfigEach context represents a cluster + user + namespace combination

Select Context

User selects context from dropdown in header

Authenticate

Uses credentials from selected context:

Client certificates
Bearer tokens
Cloud provider auth (AWS, GCP, Azure)
Service account tokens

Connect to API Server

Establishes connection to Kubernetes API serverAll resource queries use this connection

Kubeconfig File

Standard Kubernetes configuration file:

Location

Default
Custom
Multiple Files

Path: ~/.kube/config

# Check if exists
ls -la ~/.kube/config

Environment variable: KUBECONFIG

export KUBECONFIG=/path/to/custom-config
npm run orphelix start

Merged configs:

export KUBECONFIG=~/.kube/config:~/.kube/cluster2.yaml
npm run orphelix start

Orphelix merges all files

Structure

apiVersion: v1
kind: Config
clusters:
- name: production-cluster
  cluster:
    server: https://prod-k8s.example.com
    certificate-authority-data: LS0tLS...

- name: staging-cluster
  cluster:
    server: https://staging-k8s.example.com
    certificate-authority-data: LS0tLS...

users:
- name: admin-user
  user:
    client-certificate-data: LS0tLS...
    client-key-data: LS0tLS...

- name: developer-user
  user:
    token: eyJhbGci...

contexts:
- name: prod
  context:
    cluster: production-cluster
    user: admin-user
    namespace: default

- name: staging
  context:
    cluster: staging-cluster
    user: developer-user
    namespace: staging

current-context: prod

Key Components

Clusters

Kubernetes API server endpointsRequired fields:

server: API server URL
certificate-authority-data: CA certificate (or path)

Optional:

insecure-skip-tls-verify: Skip TLS verification (not recommended)
tls-server-name: Server name for TLS

Users

Authentication credentialsMethods:

Client certificates (cert + key)
Bearer tokens
Username + password (deprecated)
Cloud provider auth plugins
Exec plugins (custom auth)

Examples:

# Certificate auth
user:
  client-certificate-data: LS0tLS...
  client-key-data: LS0tLS...

# Token auth
user:
  token: eyJhbGci...

# AWS EKS
user:
  exec:
    apiVersion: client.authentication.k8s.io/v1beta1
    command: aws
    args:
      - eks
      - get-token
      - --cluster-name
      - my-cluster

Contexts

Cluster + User + Namespace combinationFields:

cluster: Which cluster to connect to
user: Which credentials to use
namespace: Default namespace (optional)

Purpose: Quick switching between environments

Context Selector

Switch contexts from the Orphelix header: Context Selector

Features

Quick Switch

Click dropdown to change contexts instantly

Search

Filter contexts by name

Connection Status

Visual indicator shows connection health

Test Connection

Verify connectivity before switching

Context Display

Each context shows:

Name: Context identifier
Cluster: Cluster name
Server: API server URL (truncated)
Namespace: Default namespace
Status: Connection indicator

Connection Status Icons:

🟢 Connected: Active, healthy connection
🟡 Connecting: Establishing connection
🔴 Disconnected: Cannot connect
⚪ Unknown: Not yet tested

Switching Contexts

Click Context Dropdown

In the top header, click current context name

Select New Context

Click desired context from list

Wait for Connection

Orphelix connects to new cluster (1-2 seconds)

Page Refreshes

Data reloads for new cluster

Deployments list updates
Pods list updates
Dashboard shows new cluster stats

Context selection persists across browser sessions (stored in cookies)

Testing Connection

Verify cluster connectivity before using: Test Connection

Test Connection Dialog

Open Dialog

Click context dropdown → “Test Connection” button

Select Context

Choose context to test

Run Tests

Orphelix performs checks:

DNS Resolution: Can resolve API server hostname?
TCP Connection: Can reach API server port?
TLS Handshake: Valid certificates?
Authentication: Valid credentials?
Authorization: Can list namespaces?
API Version: Compatible Kubernetes version?

View Results

Each test shows:

✅ Pass: Test succeeded
❌ Fail: Test failed (with error message)
⏭️ Skipped: Test not applicable

Test Results

All Pass
Some Failures
Complete Failure

Indicator: Green checkmark

✅ DNS Resolution: success
✅ TCP Connection: success (123ms)
✅ TLS Handshake: success
✅ Authentication: success (admin user)
✅ Authorization: can list namespaces
✅ API Version: v1.28.3

Connection is healthy!

Indicator: Yellow warning

✅ DNS Resolution: success
✅ TCP Connection: success
❌ TLS Handshake: certificate verify failed
   Error: x509: certificate signed by unknown authority

Connection has issues - check certificates

Indicator: Red error

✅ DNS Resolution: success
❌ TCP Connection: timeout
   Error: dial tcp 10.0.0.1:6443: i/o timeout

Cannot connect to cluster - check network/firewall

Cluster Aliases

Give clusters friendly names: Cluster Aliases

Creating Aliases

Open Settings

Navigate to Settings → Cluster Configuration tab

Add Alias

Click “Add Alias” button

Configure Alias

Context Name: Select from dropdown
Friendly Name: Enter display name
Icon: Choose emoji/icon (optional)
Description: Add notes (optional)

Example:

Context: arn:aws:eks:us-east-1:123456:cluster/prod
Friendly Name: 🚀 Production (US East)
Description: Main production cluster

Save

Click “Save” - alias appears in context selector

Alias Benefits

Readability

Replace long, cryptic context names with readable labelsBefore: gke_my-project_us-central1-a_cluster-1After: 🌎 GKE Production

Safety

Prevent accidental operations on wrong clusterClear visual distinction between prod/staging/dev

Team Consistency

Everyone sees same cluster namesShared aliases configuration via settings file

Multi-Cluster Management

Manage multiple clusters simultaneously:

Common Scenarios

Multi-Environment
Multi-Region
Multi-Tenant

Setup: Dev, Staging, Production

contexts:
- name: dev
  context:
    cluster: dev-cluster
    namespace: default

- name: staging
  context:
    cluster: staging-cluster
    namespace: default

- name: prod
  context:
    cluster: prod-cluster
    namespace: default

Workflow:

Test changes in dev
Promote to staging
Deploy to production

Setup: Different geographic regions

contexts:
- name: us-east
  context:
    cluster: eks-us-east-1
    namespace: default

- name: eu-west
  context:
    cluster: eks-eu-west-1
    namespace: default

- name: ap-south
  context:
    cluster: eks-ap-south-1
    namespace: default

Use case: Monitor global infrastructure

Setup: Different customer clusters

contexts:
- name: customer-a
  context:
    cluster: cluster-customer-a
    namespace: default

- name: customer-b
  context:
    cluster: cluster-customer-b
    namespace: default

Use case: Managed Kubernetes service

Switching Best Practices

Verify Before Actions

Always check current context before:

Restarting deployments
Editing YAML
Scaling resources

Context shown in header - confirm it’s correct

Use Clear Naming

Context names should indicate:

Environment (dev/staging/prod)
Region (if multi-region)
Purpose (monitoring/management)

Example: prod-us-east-1-monitoring

Limit Production Access

Separate kubeconfig files for production:

# Development clusters
export KUBECONFIG=~/.kube/dev-config

# Production clusters (separate terminal)
export KUBECONFIG=~/.kube/prod-config

Prevents accidental production changes

Authentication Methods

Orphelix supports all standard Kubernetes authentication:

Client Certificates

Most common method:

users:
- name: admin
  user:
    client-certificate-data: LS0tLS1CRUd...
    client-key-data: LS0tLS1CRUdJT...

Pros:

Widely supported
No token expiration
Offline authentication

Cons:

Certificate rotation needed
Key must be kept secure

Bearer Tokens

Service account or OAuth tokens:

users:
- name: sa-user
  user:
    token: eyJhbGciOiJSUzI1NiIsImtpZCI6Ik...

Pros:

Easy to distribute
Can have expiration
Revocable

Cons:

May expire
Must be refreshed

Cloud Provider Auth

AWS, GCP, Azure authentication:

AWS EKS
GCP GKE
Azure AKS

users:
- name: aws-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws
      args:
        - eks
        - get-token
        - --cluster-name
        - my-cluster
        - --region
        - us-east-1

Requirements:

AWS CLI installed
AWS credentials configured
IAM permissions for EKS

users:
- name: gcp-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: gke-gcloud-auth-plugin
      installHint: Install gke-gcloud-auth-plugin
      provideClusterInfo: true

Requirements:

gcloud CLI installed
Authenticated with gcloud
GKE cluster access

users:
- name: azure-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubelogin
      args:
        - get-token
        - --environment
        - AzurePublicCloud
        - --server-id
        - <client-id>
        - --tenant-id
        - <tenant-id>

Requirements:

Azure CLI installed
kubelogin installed
Azure AD authentication

Troubleshooting

Cannot List Contexts

Symptom: Context dropdown is empty Causes:

Kubeconfig Not Found

ls ~/.kube/config
# If missing, create one

Invalid Kubeconfig

kubectl config view
# Check for syntax errors

Wrong KUBECONFIG Path

echo $KUBECONFIG
# Verify path is correct

Solutions:

Create valid kubeconfig file
Fix YAML syntax errors
Set correct KUBECONFIG environment variable

Connection Failed

Symptom: “Failed to connect to cluster” Diagnostic Steps:

Test with kubectl

kubectl cluster-info
kubectl get nodes

If kubectl fails, issue is with cluster/credentials, not Orphelix

Check Network

# Test API server connectivity
curl -k https://api-server-url:6443

Should return error (expected), but confirms connectivity

Verify Credentials

kubectl config view --minify
# Check current context credentials

Check Certificates

# Verify certificates are valid
openssl x509 -in cert.pem -text -noout

Authentication Failed

Symptom: “Unauthorized” or “Forbidden” errors Common Issues:

Expired Tokens

Token-based auth expiredSolution: Refresh token:

# For cloud providers
aws eks update-kubeconfig --name cluster-name
gcloud container clusters get-credentials cluster-name
az aks get-credentials --name cluster-name --resource-group rg

Insufficient Permissions

User lacks RBAC permissionsSolution: Grant necessary permissions:

kubectl create clusterrolebinding orphelix-admin \
  --clusterrole=cluster-admin \
  --user=myuser

Wrong User

Context using incorrect userSolution: Update context:

kubectl config set-context <context> --user=<correct-user>

Certificate Errors

Symptom: TLS handshake failures Solutions:

Untrusted CA

# Option 1: Add CA to system trust store
# Option 2: Skip verification (not recommended)
kubectl config set-cluster <cluster> --insecure-skip-tls-verify=true

Certificate Name Mismatch

# Set correct TLS server name
kubectl config set-cluster <cluster> --tls-server-name=kubernetes.example.com

Expired Certificate
- Renew cluster certificates
- Update kubeconfig with new certificates

Next Steps

Namespaces

Configure namespace filtering

Demo Mode

Try demo mode without cluster

Settings

Configure Orphelix settings

Dashboard

View cluster resources

Features

GitHub Integration

Configuration

​Overview

​How Cluster Connection Works

​Kubeconfig File

​Location

​Structure

​Key Components

​Context Selector

​Features

Quick Switch

Search

Connection Status

Test Connection

​Context Display

​Switching Contexts

​Testing Connection

​Test Connection Dialog

​Test Results

​Cluster Aliases

​Creating Aliases

​Alias Benefits

​Multi-Cluster Management

​Common Scenarios

​Switching Best Practices

​Authentication Methods

​Client Certificates

​Bearer Tokens

​Cloud Provider Auth

​Troubleshooting

​Cannot List Contexts

​Connection Failed

​Authentication Failed

​Certificate Errors

​Next Steps

Namespaces

Demo Mode

Settings

Dashboard

Overview

How Cluster Connection Works

Kubeconfig File

Location

Structure

Key Components

Context Selector

Features

Context Display

Switching Contexts

Testing Connection

Test Connection Dialog

Test Results

Cluster Aliases

Creating Aliases

Alias Benefits

Multi-Cluster Management

Common Scenarios

Switching Best Practices

Authentication Methods

Client Certificates

Bearer Tokens

Cloud Provider Auth

Troubleshooting

Cannot List Contexts

Connection Failed

Authentication Failed

Certificate Errors

Next Steps