Connecting Kubernetes Clusters - Step-by-Step Guide | Nife Deploy

Learn how to connect your Kubernetes clusters to Nife using standalone or BYOC options.

Before You Begin#

Requirements:

  • Admin access to your Kubernetes cluster
  • Kubeconfig file (for standalone clusters)
  • Cloud credentials (for BYOC)
  • Network connectivity to your cluster

Connecting a Standalone Cluster#

A standalone cluster is your own Kubernetes cluster that you manage.

Step 1: Prepare Your Kubeconfig#

  1. Get your kubeconfig file from your cluster administrator
  2. The file typically contains:
    • Cluster endpoint
    • Authentication credentials
    • Context information

Location of kubeconfig:

  • Linux/Mac: ~/.kube/config
  • Windows: %USERPROFILE%\.kube\config

Step 2: Start the Connection#

  1. Go to Clusters page
  2. Click Connect Cluster button
  3. Select Standalone Cluster

Step 3: Fill in Details#

Cluster Name:

  • Give your cluster a descriptive name
  • Example: "Production API Cluster"
  • Used for easy identification

Region Code:

  • Select the region where your cluster runs
  • Examples: us-east-1, eu-west-1
  • Important for global deployments

Kubeconfig Content:

  • Paste your kubeconfig file content
  • OR upload the kubeconfig file directly

Step 4: Verify Connection#

  1. Nife will validate the kubeconfig
  2. Test connection to the cluster
  3. Once confirmed, cluster appears in your list

Troubleshooting Connection#

Problem: Connection Failed

Possible causes:

  • Invalid kubeconfig format
  • Cluster unreachable
  • Authentication failed
  • Network connectivity issue

Solutions:

  1. Verify kubeconfig is valid
  2. Check cluster is running and accessible
  3. Verify network allows outbound connections
  4. Check credentials in kubeconfig
  5. Try uploading kubeconfig file again

Connecting with BYOC (Cloud Providers)#

BYOC allows you to connect cloud infrastructure directly.

Supported Cloud Providers#

Amazon Web Services (AWS)#

What you need:

  • AWS account with cluster access
  • IAM credentials (Access Key & Secret Key)

Steps:

  1. Go to Clusters → Connect Cluster
  2. Select BYOC → AWS
  3. Enter AWS credentials:
    • Access Key ID
    • Secret Access Key
  4. Choose existing cluster or create new
  5. Click Connect

Permissions Required:

  • EC2 access
  • EKS cluster access
  • IAM role permissions

Google Cloud Platform (GCP)#

What you need:

  • GCP project with GKE cluster
  • Service account JSON key

Steps:

  1. Go to Clusters → Connect Cluster
  2. Select BYOC → GCP
  3. Upload service account JSON key
  4. Select cluster from dropdown
  5. Click Connect

Permissions Required:

  • GKE cluster access
  • Container API enabled
  • Service account with cluster admin

Microsoft Azure#

What you need:

  • Azure subscription with AKS cluster
  • Service principal or managed identity

Steps:

  1. Go to Clusters → Connect Cluster
  2. Select BYOC → Azure
  3. Enter credentials:
    • Subscription ID
    • Tenant ID
    • Client ID
    • Client Secret
  4. Select cluster from list
  5. Click Connect

Permissions Required:

  • AKS cluster access
  • Azure Role-Based Access Control (RBAC)

After Connecting#

What Happens Next#

  1. Validation: Nife validates cluster access
  2. Registration: Cluster is registered to your organization
  3. Agent Deployment: You can now deploy agents
  4. Monitoring: Cluster appears in your dashboard

Next Steps#

  1. Deploy an Agent: Enable monitoring and additional features
  2. Configure Cluster: Set region and other preferences
  3. Deploy Applications: Start deploying to your cluster

Managing Connected Clusters#

View Cluster Details#

  1. Go to Clusters page
  2. Click cluster name or View Details
  3. See:
    • Cluster configuration
    • Deployed agents
    • Connected status
    • Resource information

Set Default Cluster#

  1. Select cluster from list
  2. Click Set as Default
  3. Default cluster is used for new deployments

Disconnect a Cluster#

  1. Find cluster in list
  2. Click menu (three dots) → Disconnect
  3. Confirm disconnection
  4. Cluster is removed from Nife (but not deleted from your infrastructure)

Warning: Disconnecting doesn't delete your cluster, only removes it from Nife.

Update Cluster Configuration#

  1. Click Edit on cluster
  2. Update:
    • Cluster name
    • Region
    • Additional settings
  3. Click Save

Cluster List View Modes#

Card View (Default)#

Shows clusters as cards with:

  • Cluster name and status
  • Region information
  • Agent count
  • Quick action buttons

Best for:

  • Visual overview
  • Quick status checks
  • Small number of clusters

Grid View#

Shows clusters in a table format with:

  • Columns for name, region, status
  • Sortable headers
  • Detailed information

Best for:

  • Large number of clusters
  • Comparing details
  • Quick data lookup

Switch View Mode#

  1. Top right: Click Grid or Card button
  2. View mode updates immediately
  3. Your preference is saved

Common Cluster Connection Issues#

Issue: Invalid Kubeconfig#

Symptoms:

  • Connection fails immediately
  • Error message about invalid format

Solution:

  1. Verify kubeconfig syntax
  2. Check file is not corrupted
  3. Try different kubeconfig version
  4. Test with kubectl command first

Issue: Authentication Failed#

Symptoms:

  • Connection succeeds but operations fail
  • Permission denied errors

Solution:

  1. Verify credentials in kubeconfig
  2. Check token hasn't expired
  3. Verify user has cluster admin
  4. Try refreshing credentials

Issue: Cluster Unreachable#

Symptoms:

  • Connection timeout
  • Network unreachable errors

Solution:

  1. Check cluster is running
  2. Verify network allows outbound HTTPS
  3. Check firewall rules
  4. Test ping/curl to cluster endpoint

Issue: Region Not Available#

Symptoms:

  • Cannot select desired region
  • Region dropdown is empty

Solution:

  1. Request region in Requested tab
  2. Wait for region approval
  3. Select from available regions
  4. Use closest available region temporarily

Best Practices#

1. Naming Convention#

Use clear, descriptive names:

  • ✅ "Production API Cluster - US East"
  • ✅ "Staging Database Cluster - EU"
  • ❌ "Cluster 1"
  • ❌ "Test"

2. Organize by Region#

Keep clusters organized geographically for easier management.

3. Regular Verification#

Periodically check that clusters are still connected and healthy.

4. Credential Security#

  • Store credentials securely
  • Rotate credentials regularly
  • Don't share kubeconfig files
  • Use IAM roles when possible

5. Network Security#

  • Use private endpoints when available
  • Restrict cluster access by IP
  • Enable encryption for connections
  • Monitor access logs

Next Steps#

  1. Deploy Agents - Enable monitoring
  2. Manage Resources - Monitor cluster health
  3. Deploy Applications - Start using your cluster

Support#

Having trouble connecting?

  • Check the troubleshooting section above
  • Review your cloud provider's documentation
  • Contact support: [email protected]