Prerequisites¶
The Easy Way¶
Got a clean Ubuntu machine? Bootstrap everything with one command using just.
Install just:
Download the justfile and run setup:
curl -O https://raw.githubusercontent.com/charmarr/charmarr/track/1/justfiles/charmarr-primitives.just
just -f charmarr-primitives.just setup
This installs MicroK8s with required addons, bootstraps Juju, and creates a charmarr model.
Verify it worked:
To remove everything:
Manual Setup¶
Already have a cluster? Here's the shopping list.
| Category | Requirement | Status | Istio Support |
|---|---|---|---|
| Hardware | 8 GB RAM | Minimum | - |
| Hardware | 4 vCPUs | Minimum | - |
| OS | Ubuntu baremetal | Recommended | - |
| OS | Other Linux distros | Untested | - |
| OS | Virtualized setups | Untested | - |
| Kubernetes | MicroK8s | Recommended | Yes |
| Kubernetes | Minikube | Supported | Yes |
| Kubernetes | Other standard K8s | Supported | Yes |
| Kubernetes | K3s / k3d | Supported | Needs tweaks |
| Kubernetes | Cilium CNI | Supported | Needs tweaks |
| Kubernetes | LB with 3+ IPs | - | Required |
| Tools | Juju 3.6.x | Required | Required |
MicroK8s Addons¶
Juju Setup¶
Install via snap:
Juju 3.6.x is also available from nixpkgs and as a binary download.
Bootstrap with your cluster:
# Add your k8s cluster to Juju (pipe kubeconfig into add-k8s)
sudo microk8s config | juju add-k8s mcrk8s --client
# Bootstrap Juju on the cluster
juju bootstrap mcrk8s mcrk8s
# Create the charmarr model
juju add-model charmarr
See the Juju docs for add-k8s and bootstrap.
Ingress & Security¶
Charmarr lets you opt-in to Istio Ambient. Enabling Istio provides ingress to all Charmarr apps via the Istio ingress gateway, which is recommended if the cluster is compatible as it simplifies ingress setup. On top, it is possible to enable mesh which hardens internal traffic with zero-trust. See Networking for details.
Compatibility Checklist¶
- Used The Easy Way to setup the cluster
— OR —
- No Istiod already running on the cluster (if you don't know, it's probably not)
- Not using K3s or k3d (read the warning below)
- Not using Cilium CNI (or willing to configure it)
All checked? Enable Istio and mesh while deploying.
Not all checked? Disable Istio and handle ingress yourself. See Istio platform prerequisites for details.
Warning
K3s and k3d use non-standard CNI paths that can conflict with Istio Ambient. Adding Istio may disrupt the CNI chain and cause hard-to-debug networking issues. It can work with careful configuration: K3s docs, k3d docs. So if you want to use it with Istio Ambient, do it at your own discretion.
OpenTofu¶
Required for Quick Deploy. Skip if using Manual Deploy.
Install from opentofu.org, or via snap: