# 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:

   ```bash
   scp -P 22 -i ~/.ssh/id_rsa <login>@<server>:~/.kube/config /tmp/kubeconfig
   ```
2. Verify cluster access:

   ```bash
   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\]](https://kubernetes.io/docs/tasks/tools/)
* 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\]](https://helm.sh/)
* `k9s` for terminal-based Kubernetes management [\[4\]](https://k9scli.io/topics/install/)

## Access cluster from the server (SSH)

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

```bash
~/.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:

```bash
export KUBECONFIG=/tmp/kubeconfig
```

Verify cluster access:

```bash
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:

{% hint style="warning" %}
This will overwrite your existing `~/.kube/config` file.
{% endhint %}

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

#### Merge with an existing kubeconfig

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

```bash
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

```bash
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

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

Example output:

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

### Verify cluster connection

```bash
kubectl get namespaces
kubectl get pods -A
```

### Common troubleshooting commands

Check current Kubernetes context:

```bash
kubectl config current-context
```

Check cluster connectivity:

```bash
kubectl cluster-info
```

Check Kubernetes API permissions:

```bash
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/>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.opencrvs.org/v2.0/technical/guides/installation/advanced-topics/kubernetes-cluster-access.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.