k8s-pulse/helm-chart/INSTALL.md

# k8s-pulse Helm Chart

This Helm chart provides a production-ready Kubernetes deployment for **k8s-pulse**, a Python web application that visualizes cluster metrics and resource usage.

## Prerequisites

- A running Kubernetes cluster (v1.19+ recommended).
- [Helm v3+](https://helm.sh/) installed.
- (Optional) Metrics Server installed in your cluster for detailed container CPU & memory usage.

## Kubeconfig & Secret Setup

To mirror the `docker-compose.yml` setup where `KUBECONFIG=/root/.kube/config` is mounted into the container, the Helm chart mounts a Kubernetes `Secret` containing your `kubeconfig` file to `/root/.kube/config` and sets the `KUBECONFIG` environment variable.

You can configure and set up the `kubeconfig` secret using one of the following methods:

### Method 1: Create a Kubernetes Secret manually with `kubectl` (Recommended)

1. Create a secret containing your `.kube/config` file:
   ```bash
   kubectl create secret generic k8s-pulse-kubeconfig --from-file=config=$HOME/.kube/config
   ```

2. Install or upgrade the Helm chart specifying the existing secret:
   ```bash
   helm install k8s-pulse ./helm-chart \
     --set kubeconfig.enabled=true \
     --set kubeconfig.secretName=k8s-pulse-kubeconfig
   ```

### Method 2: Create the Secret via Helm using `--set-file`

You can have Helm create the `Secret` resource directly from your local `kubeconfig` file during installation:

```bash
helm install k8s-pulse ./helm-chart \
  --set kubeconfig.enabled=true \
  --set kubeconfig.createSecret=true \
  --set-file kubeconfig.content=$HOME/.kube/config
```

### Method 3: Use a custom `values.yaml` file

Create a custom values file (e.g. `my-values.yaml`):

```yaml
kubeconfig:
  enabled: true
  createSecret: true
  secretName: "k8s-pulse-kubeconfig"
  secretKey: "config"
  mountPath: "/root/.kube/config"
  content: |
    apiVersion: v1
    clusters:
    - cluster:
        server: https://127.0.0.1:6443
      name: my-cluster
    ...
```

Then install the chart using:

```bash
helm install k8s-pulse ./helm-chart -f my-values.yaml
```

---

## Quick Start

### 1. Install the Chart

Default installation (uses `kubeconfig.enabled=true` with secret `<release-name>-kubeconfig`):

```bash
# 1. Create the secret
kubectl create secret generic k8s-pulse-kubeconfig --from-file=config=$HOME/.kube/config

# 2. Install the chart
helm install k8s-pulse ./helm-chart --set kubeconfig.secretName=k8s-pulse-kubeconfig
```

### 2. Custom Configuration

You can override default settings by passing a custom `values.yaml` file or using `--set`:

```bash
helm install k8s-pulse ./helm-chart -f custom-values.yaml
```

Example: Enable Ingress and change image tag:

```bash
helm install k8s-pulse ./helm-chart \
  --set image.tag="1.0.0" \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host="k8s-pulse.example.com"
```

### 3. Upgrade the Release

```bash
helm upgrade k8s-pulse ./helm-chart
```

### 4. Uninstall

```bash
helm uninstall k8s-pulse
```

---

## Configuration Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `replicaCount` | Number of application replicas | `1` |
| `image.repository` | Docker image repository | `k8s-pulse` |
| `image.tag` | Docker image tag | `latest` |
| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
| `kubeconfig.enabled` | Enable mounting kubeconfig Secret and `KUBECONFIG` env var | `true` |
| `kubeconfig.secretName` | Name of existing Secret containing kubeconfig file | `""` (defaults to `<release-fullname>-kubeconfig`) |
| `kubeconfig.createSecret` | Create Secret resource via Helm from `kubeconfig.content` | `false` |
| `kubeconfig.content` | Raw kubeconfig content when `createSecret` is true | `""` |
| `kubeconfig.secretKey` | Secret data key containing kubeconfig file content | `"config"` |
| `kubeconfig.mountPath` | Container path to mount kubeconfig file and set `KUBECONFIG` env | `"/root/.kube/config"` |
| `service.type` | Kubernetes service type | `ClusterIP` |
| `service.port` | Service port exposed | `80` |
| `service.targetPort` | Container application port | `5000` |
| `rbac.create` | Create ClusterRole & ClusterRoleBinding for K8s API access | `true` |
| `serviceAccount.create` | Create ServiceAccount for the deployment | `true` |
| `serviceAccount.name` | Explicit ServiceAccount name | `""` |
| `ingress.enabled` | Enable Ingress resource | `false` |
| `resources` | Pod CPU/Memory resource limits & requests | `{ limits: { cpu: 200m, memory: 256Mi }, requests: { cpu: 100m, memory: 128Mi } }` |
| `persistence.enabled` | Enable optional PersistentVolumeClaim | `false` |

---

## RBAC Requirements

`k8s-pulse` requires read access to cluster nodes, pods, and `metrics.k8s.io` custom objects. By default, `rbac.create: true` creates a `ClusterRole` and `ClusterRoleBinding` bound to the pod's `ServiceAccount`.

## Verification

Check the deployment status:

```bash
kubectl get pods -l app.kubernetes.io/name=k8s-pulse
kubectl get svc -l app.kubernetes.io/name=k8s-pulse
```