feat: add Helm chart for installing the operator

.github/workflows/helm.yml

@@ -0,0 +1,44 @@
+name: Helm
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint chart
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up Helm
+        uses: azure/setup-helm@bf6a7d304bc2fdb57e0331155b7ebf2c504acf0a # v4
+
+      - name: helm lint
+        run: helm lint deploy/charts/marimo-operator
+
+      - name: helm template
+        run: helm template marimo-operator deploy/charts/marimo-operator --include-crds > /dev/null
+
+  crd-sync:
+    name: CRD in sync with generated manifests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go.mod
+
+      - name: Regenerate manifests
+        run: make manifests
+
+      - name: Check chart CRDs match config/crd/bases
+        run: |
+          if ! git diff --exit-code config/crd/bases deploy/charts/marimo-operator/crds; then
+            echo "::error::CRDs are out of sync. Run 'make manifests' and commit the result."
+            exit 1
+          fi

.pre-commit-config.yaml

@@ -5,6 +5,8 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        # Helm templates are not valid standalone YAML.
+        exclude: ^deploy/charts/.*/templates/
       - id: check-merge-conflict
 
   - repo: https://github.com/astral-sh/ruff-pre-commit

CONTRIBUTING.md

@@ -38,7 +38,7 @@ go test ./internal/controller/... -run TestReconcile -v
 make test
 ```
 
-**Important:** After modifying types in `api/v1alpha1/`, always run `make manifests && make generate` and commit the generated files.
+**Important:** After modifying types in `api/v1alpha1/`, always run `make manifests && make generate` and commit the generated files. `make manifests` also syncs the Helm chart's CRD copy (`deploy/charts/marimo-operator/crds/`), so commit that too.
 
 ### Plugin (Python)
 

Makefile

@@ -44,6 +44,7 @@ help: ## Display this help.
 .PHONY: manifests
 manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
 	"$(CONTROLLER_GEN)" rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+	cp config/crd/bases/*.yaml deploy/charts/marimo-operator/crds/
 
 .PHONY: generate
 generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.

README.md

@@ -32,6 +32,10 @@ kubectl apply -f https://raw.githubusercontent.com/marimo-team/marimo-operator/m
 # Option 2: Install via kustomize
 kubectl apply -k https://github.com/marimo-team/marimo-operator/config/default
 
+# Option 3: Install via Helm
+helm install marimo-operator ./deploy/charts/marimo-operator \
+  --namespace marimo-operator-system --create-namespace
+
 # Verify installation
 kubectl get pods -n marimo-operator-system
 # Should show: marimo-operator-controller-manager-xxx  Running

deploy/charts/marimo-operator/.helmignore

@@ -0,0 +1,11 @@
+# Patterns to ignore when building Helm packages.
+.DS_Store
+.git/
+.gitignore
+.idea/
+.vscode/
+*.tmproj
+*.bak
+*.swp
+*.orig
+ci/

deploy/charts/marimo-operator/Chart.yaml

@@ -0,0 +1,21 @@
+apiVersion: v2
+name: marimo-operator
+description: A Helm chart for the marimo-operator, a Kubernetes operator that manages MarimoNotebook custom resources.
+type: application
+# Chart version: independent SemVer, bumped on any chart change.
+version: 0.1.0
+# Tracks the operator release this chart deploys by default.
+appVersion: "v0.3.0"
+kubeVersion: ">=1.21.0-0"
+keywords:
+  - marimo
+  - operator
+  - notebooks
+home: https://github.com/marimo-team/marimo-operator
+sources:
+  - https://github.com/marimo-team/marimo-operator
+maintainers:
+  - name: marimo-team
+    url: https://github.com/marimo-team
+annotations:
+  artifacthub.io/operator: "true"

deploy/charts/marimo-operator/README.md

@@ -0,0 +1,88 @@
+# marimo-operator Helm chart
+
+Installs the [marimo-operator](https://github.com/marimo-team/marimo-operator) — a Kubernetes
+operator that manages `MarimoNotebook` custom resources — including its CRD, controller
+`Deployment`, and RBAC.
+
+## Prerequisites
+
+- Kubernetes >= 1.21
+- Helm 3
+- Permission to create cluster-scoped resources (CRD, ClusterRole) on first install
+
+## Install
+
+```sh
+helm install marimo-operator ./deploy/charts/marimo-operator \
+  --namespace marimo-operator-system --create-namespace
+```
+
+The operator installs into the release namespace — set `--namespace` to deploy it anywhere.
+
+Pin a specific operator image:
+
+```sh
+helm install marimo-operator ./deploy/charts/marimo-operator \
+  --namespace marimo-operator-system --create-namespace \
+  --set image.tag=v0.3.0
+```
+
+## CRD lifecycle
+
+The `MarimoNotebook` CRD ships in the chart's `crds/` directory. Helm installs it on first
+install but **does not upgrade or delete it** on `helm upgrade` / `helm uninstall`. When a new
+operator release changes the CRD, apply it manually:
+
+```sh
+kubectl apply -f https://raw.githubusercontent.com/marimo-team/marimo-operator/<tag>/deploy/charts/marimo-operator/crds/marimo.io_marimos.yaml
+```
+
+The CRD is generated from the Go API types by `make manifests` and copied into the chart by the
+same target, so it stays in lockstep with `config/crd/bases`.
+
+## Values
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `replicaCount` | `1` | Operator replicas (leader election elects the active one). |
+| `image.repository` | `ghcr.io/marimo-team/marimo-operator` | Controller image repository. |
+| `image.tag` | `""` | Image tag; defaults to the chart `appVersion`. |
+| `image.pullPolicy` | `IfNotPresent` | Image pull policy. |
+| `imagePullSecrets` | `[]` | Image pull secrets. |
+| `nameOverride` / `fullnameOverride` | `""` | Override generated resource names. |
+| `serviceAccount.create` | `true` | Create the controller ServiceAccount. |
+| `serviceAccount.name` | `""` | ServiceAccount name (generated when empty). |
+| `serviceAccount.annotations` | `{}` | ServiceAccount annotations (e.g. IRSA). |
+| `rbac.create` | `true` | Create ClusterRole/Role and bindings. |
+| `leaderElection.enabled` | `true` | Enable leader election. |
+| `healthProbe.bindAddress` | `:8081` | Health probe bind address. |
+| `metrics.enabled` | `true` | Serve the controller metrics endpoint. |
+| `metrics.bindAddress` | `:8443` | Metrics bind address. |
+| `metrics.secure` | `true` | Serve metrics over HTTPS with authn/authz. |
+| `metrics.enableHTTP2` | `false` | Enable HTTP/2 on the metrics server. |
+| `metrics.service.type` | `ClusterIP` | Metrics Service type. |
+| `metrics.service.port` | `8443` | Metrics Service port. |
+| `metrics.serviceMonitor.enabled` | `false` | Create a Prometheus Operator ServiceMonitor. |
+| `metrics.serviceMonitor.labels` | `{}` | Extra ServiceMonitor labels (e.g. Prometheus release selector). |
+| `metrics.serviceMonitor.interval` | `""` | Scrape interval. |
+| `metrics.serviceMonitor.scrapeTimeout` | `""` | Scrape timeout. |
+| `metrics.serviceMonitor.insecureSkipVerify` | `true` | Skip TLS verification when scraping. |
+| `metrics.serviceMonitor.tlsConfig` | `{}` | Full `tlsConfig` override (replaces `insecureSkipVerify`). |
+| `networkPolicy.enabled` | `false` | Restrict metrics ingress with a NetworkPolicy. |
+| `networkPolicy.metricsPort` | `8443` | Metrics port allowed by the policy. |
+| `networkPolicy.fromNamespaceLabels` | `{metrics: enabled}` | Namespace selector allowed to scrape. |
+| `operatorImages.initImage` | `busybox:1.36` | `DEFAULT_INIT_IMAGE` env. |
+| `operatorImages.gitImage` | `alpine/git:latest` | `GIT_IMAGE` env. |
+| `operatorImages.alpineImage` | `alpine:latest` | `ALPINE_IMAGE` env. |
+| `operatorImages.s3fsImage` | `ghcr.io/marimo-team/marimo-operator/s3fs:latest` | `S3FS_IMAGE` env. |
+| `extraArgs` | `[]` | Extra controller args. |
+| `extraEnv` | `[]` | Extra controller env. |
+| `extraVolumes` / `extraVolumeMounts` | `[]` | Extra volumes / mounts. |
+| `resources` | req `10m`/`64Mi`, lim `500m`/`128Mi` | Controller resources. |
+| `livenessProbe` / `readinessProbe` | see `values.yaml` | Controller probes. |
+| `podSecurityContext` | `runAsNonRoot`, `RuntimeDefault` | Pod security context. |
+| `securityContext` | restricted | Container security context. |
+| `terminationGracePeriodSeconds` | `10` | Pod termination grace period. |
+| `podAnnotations` / `podLabels` | `{}` | Extra pod annotations / labels. |
+| `nodeSelector` / `tolerations` / `affinity` / `topologySpreadConstraints` | empty | Scheduling controls. |
+| `priorityClassName` | `""` | Pod priority class. |