Kubernetes cluster access

Overview

This guide explains how to connect to an OpenCRVS Kubernetes cluster using kubectl. After completing this guide, you should be able to:

• Authenticate against the cluster

• Run kubectl commands

• Access OpenCRVS namespaces and workloads

• Deploy and troubleshoot OpenCRVS services

OpenCRVS cluster access is typically provided using a Kubernetes kubeconfig file generated by the cluster administrator.

Quick Start

1. Copy the Kubernetes configuration file (kubeconfig) from the server:

   scp -P 22 -i ~/.ssh/id_rsa <login>@<server>:~/.kube/config /tmp/kubeconfig

2. Verify cluster access:

   export KUBECONFIG=/tmp/kubeconfig
   kubectl get namespaces

If the command succeeds, your Kubernetes access is configured correctly.

Prerequisites

Before connecting to the cluster, ensure you have:

• SSH access to the server

• kubectl installed locally [2]

• VPN or network access to the cluster (if required)

• Network access to Kubernetes API port 6443/TCP

Optional utilities:

• helm if you plan to deploy or upgrade OpenCRVS services [3]

• k9s for terminal-based Kubernetes management [4]

Access cluster from the server (SSH)

The Kubernetes kubeconfig file is stored in the user's home directory:

~/.kube/config

All users defined in the infrastructure inventory files (infrastructure/server-setup/inventory) already have Kubernetes access configured.

Once logged in to the server via SSH, you can use kubectl or k9s to manage OpenCRVS workloads and troubleshoot issues from the terminal. Both utilities are installed and preconfigured by default.

Use kubectl from your laptop

Copy kubeconfig from the server

Copy the Kubernetes kubeconfig file from the server to your laptop:

scp -P 22 -i ~/.ssh/id_rsa <login>@<server>:~/.kube/config /tmp/kubeconfig

Use kubeconfig temporarily

Configure kubectl to use the downloaded configuration file:

export KUBECONFIG=/tmp/kubeconfig

Verify cluster access:

kubectl get namespaces

If the command succeeds, your Kubernetes access is configured correctly.

Optional: Configure kubeconfig for long-term use

Most users only need one of the following options.

Replace your default kubeconfig

Use this option if this cluster should become your default Kubernetes context:

This will overwrite your existing ~/.kube/config file.

mkdir -p ~/.kube
mv /tmp/kubeconfig ~/.kube/config

Merge with an existing kubeconfig

Use this option if you already work with multiple Kubernetes clusters:

KUBECONFIG=~/.kube/config:/tmp/kubeconfig kubectl config view --merge --flatten > /tmp/merged.kubeconfig
cp ~/.kube/config ~/.kube/config.$(date +%F)
mv /tmp/merged.kubeconfig ~/.kube/config

Useful commands

List available Kubernetes contexts

kubectl config get-contexts

Example output:

CURRENT   NAME                                     CLUSTER                                  AUTHINFO                                 NAMESPACE
          docker-desktop                           docker-desktop                           docker-desktop
*         bob@public-k8s-prod-k8s-master-01        public-k8s-prod-k8s-master-01            bob                                      opencrvs-prod
          bob@public-k8s-qa-k8s-server             public-k8s-qa-k8s-server                 bob

Switch Kubernetes context

kubectl config use-context bob@public-k8s-qa-k8s-server

Example output:

Switched to context "bob@public-k8s-qa-k8s-server".

Verify cluster connection

kubectl get namespaces
kubectl get pods -A

Common troubleshooting commands

Check current Kubernetes context:

kubectl config current-context

Check cluster connectivity:

kubectl cluster-info

Check Kubernetes API permissions:

kubectl auth can-i get pods

Links

[1] https://kubernetes.io/docs/reference/kubectl/quick-reference/

[2] https://kubernetes.io/docs/tasks/tools/

[3] https://helm.sh/

[4] https://k9scli.io/topics/install/