# k4s

A CLI tool for managing installations and Kubernetes operations.

It helps install and operate:

- **VM-based products** over SSH (systemd services, OS packages, file layout)
- **Kubernetes-based products** via Helm (with safer targeting via k8s contexts)

## Installation

Recommended (isolated install):

```bash
pipx install k4s
```

Alternative:

```bash
pip install --upgrade k4s
```

## Quick start

Initialize local state:

```bash
k4s init
```

Add a **VM** context (SSH target) and set it as current:

```bash
k4s context add prod-vm --type vm --host 10.0.0.10 --username root --password '...'
k4s context use-context prod-vm
k4s context ping
```

Add a **K8s** context and set it as current:

```bash
k4s context add demo-k8s --type k8s --kubeconfig ~/.kube/config --kubectl-context gke_demo --namespace sep
k4s context use-context demo-k8s
k4s context ping
```

## Core concepts

### Contexts (targets)

`k4s` always operates against a **context**:

- **VM contexts**: SSH connection info (host, username, auth)
- **K8s contexts**: kubeconfig + kubectl context + (optional) default namespace

If `--context` is omitted, `k4s` uses the **current context** (set via `k4s context use-context`).

### Verbosity

- **`-q/--quiet`**: only final results and errors (also suppresses update notices)
- **default**: concise step output
- **`-v`**: show step logs
- **`-vv`**: debug output

### Dry run

Most commands support `--dry-run` to print the plan without applying changes.

## Products and commands

### VM products (SSH)

- **Docker Engine**: `k4s install docker`
- **Nexus**: `k4s install nexus`
- **Dataiku**: `k4s install dataiku`
- **R integration (for an existing Dataiku install)**: `k4s install r`

Health checks (works even if the product was not installed by k4s):

```bash
k4s status nexus
k4s status dataiku --context prod-vm
```

### TLS:

```bash
k4s tls enable nexus --issuer self-signed --domain nexus.example.com
k4s tls enable dataiku --issuer acme --domain dss.example.com --email admin@example.com
```

### Kubernetes products (Helm)

- **ingress-nginx**: `k4s install ingress-nginx`
- **Starburst Enterprise**: `k4s install starburst`
- **Starburst components**: `k4s install hive|ranger|cache`
- **Datafloem**: `k4s install datafloem`

Upgrades:

```bash
k4s upgrade starburst --force
k4s upgrade datafloem
```

Example Helm values files:

- See `examples/helm-values/`

## Kubernetes clusters (RKE2)

Create an RKE2 cluster using **VM node contexts**:

```bash
k4s cluster preflight --control-plane cp1 --worker w1
k4s cluster create --name lab --type rke2 --control-plane cp1 --worker w1 --cni canal
k4s cluster kubeconfig --name lab --control-plane cp1
```

## Updates

When installed from PyPI, `k4s` checks once per day for a newer version and prints a notice:

```text
Update available: 0.0.1a1 → 0.0.2  (run: pip install --upgrade k4s)
```

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
pytest
```

## Security notes

- Do **not** commit license files, JWT secrets, or registry credentials.
- Prefer environment variables for credentials when supported by the command.