docs: update Kubernetes Operator docs for v2.7.0 and v2.8.1 releases

mintlify[bot] · web-flow · commit ec5d76d5a19f · 2026-07-20T07:12:28.000Z
diff --git a/docs/changelog/operator.mdx b/docs/changelog/operator.mdx
@@ -7,11 +7,90 @@ rss: true
 
 {/* GENERATED by scripts/generate-changelog.js — do not edit by hand. */}
 
+<Update label="2026-07-14" description="Kubernetes Operator v2.8.1">
+### Highlights
+
+- **CRDs now ship as a Helm subchart** — the chart's CRDs (`RestateCluster`, `RestateDeployment`, `RestateCloudEnvironment`) ship via an optional `restate-operator-crds` subchart placed in Helm's native `crds/` directory. Installation is gated by the `installCrds` value (default `true`). Fresh installs get all three CRDs automatically. Set `installCrds: false` to manage CRDs out-of-band (GitOps, ArgoCD).
+
+### CRD installation via Helm subchart
+
+The chart now ships CRDs via a dedicated `restate-operator-crds` subchart. This resolves the longstanding issue of CRD ownership conflicts and simplifies upgrades.
+
+- **Fresh installs**: CRDs are installed automatically by default.
+- **GitOps / out-of-band management**: Set `installCrds: false` to skip CRD installation.
+
+```yaml
+# values.yaml
+installCrds: false  # manage CRDs externally
+```
+
+Upgrading from v2.7 and earlier is straightforward — existing CRDs are left untouched, no ownership adoption or `--take-ownership` step is needed:
+
+```bash
+helm upgrade restate-operator restatedev/restate-operator --version 2.8.1
+```
+
+**Note on CRD schema updates**: Helm's native `crds/` directory is install-only on upgrade (this is deliberate Helm behavior). To apply CRD schema changes on an existing install, apply the new CRDs explicitly or let a GitOps tool re-apply them:
+
+```bash
+kubectl apply -f crd/restateclusters.yaml -f crd/restatedeployments.yaml -f crd/restatecloudenvironments.yaml
+```
+
+[View on GitHub](https://github.com/restatedev/restate-operator/releases/tag/v2.8.1)
+</Update>
+
 <Update label="2026-07-07" description="Kubernetes Operator v2.7.0">
-### What's Changed
-* chore(deps-dev): bump esbuild from 0.25.12 to 0.28.1 in /examples/services/greeter in the npm_and_yarn group across 1 directory by @dependabot[bot] in https://github.com/restatedev/restate-operator/pull/149
-* Align generated Pkl bindings; pin and fix the Pkl generator by @pcholakov in https://github.com/restatedev/restate-operator/pull/152
-* Release 2.7.0: RestateCluster pod lifecycle, sidecars, extra volumes by @pcholakov in https://github.com/restatedev/restate-operator/pull/156
+### Highlights
+
+- **Pod lifecycle, sidecars, and extra volumes on `RestateCluster`** — five new optional `spec.compute` fields (`lifecycle`, `sidecars`, `terminationGracePeriodSeconds`, `extraVolumes`, `extraVolumeMounts`) are passed through to the StatefulSet pod template, enabling graceful-shutdown hooks, companion containers, and mounting reusable content next to Restate.
+
+### Pod lifecycle, sidecars, termination grace period, and extra volumes
+
+Five new optional fields on `RestateCluster` `spec.compute` pass through to the underlying StatefulSet pod template:
+
+- `lifecycle` — container lifecycle hooks (`postStart` / `preStop`) for the Restate container.
+- `sidecars` — native sidecar containers that run alongside Restate (started before it, terminated after it). Requires Kubernetes 1.29+ (GA in 1.33).
+- `terminationGracePeriodSeconds` — overrides the pod termination grace period (previously hardcoded to 60 seconds).
+- `extraVolumes` — additional pod volumes alongside the operator-managed ones.
+- `extraVolumeMounts` — additional volume mounts for the Restate container.
+
+These let you wire in graceful-shutdown hooks, run companion containers (log shippers, proxies, metrics exporters), and tune the shutdown window for your workload.
+
+```yaml
+spec:
+  compute:
+    image: docker.restate.dev/restatedev/restate:latest
+    terminationGracePeriodSeconds: 120
+    extraVolumes:
+      - name: hooks
+        configMap:
+          name: node-state-control
+          defaultMode: 0755
+    extraVolumeMounts:
+      - name: hooks
+        mountPath: /node-state-control
+        readOnly: true
+    lifecycle:
+      preStop:
+        exec:
+          command: ["/bin/sh", "/node-state-control/pre-stop.sh"]
+    sidecars:
+      - name: log-shipper
+        image: log-shipper:latest
+        volumeMounts:
+          - name: hooks
+            mountPath: /node-state-control
+```
+
+All five fields are optional — omitting them preserves previous behavior (no lifecycle hooks, no sidecars, no extra volumes, 60s grace period). Volume and mount name collisions with operator-managed resources are rejected at reconcile time with a clear error.
+
+### Upgrading
+
+Apply the updated CRDs and upgrade the operator via Helm:
+
+```bash
+helm upgrade restate-operator restatedev/restate-operator --version 2.7.0
+```
 
 [View on GitHub](https://github.com/restatedev/restate-operator/releases/tag/v2.7.0)
 </Update>
diff --git a/docs/server/deploy/kubernetes.mdx b/docs/server/deploy/kubernetes.mdx
@@ -154,6 +154,78 @@ Both fields are propagated to the `StatefulSet` pod template and are merged with
 
 This is useful for integrations that rely on pod-level metadata, such as GKE ComputeClass scheduling (cloud.google.com/compute-class), Vault agent injection, Datadog, Prometheus scraping, and custom scheduling constraints.
 
+### Pod lifecycle hooks, sidecars, and extra volumes
+
+`RestateCluster` `spec.compute` supports several optional fields for advanced pod configuration:
+
+- `lifecycle` — container lifecycle hooks (`postStart` / `preStop`) for the Restate container.
+- `sidecars` — native sidecar containers that start before and stop after the Restate container (requires Kubernetes 1.29+).
+- `terminationGracePeriodSeconds` — overrides the pod termination grace period (default: 60s).
+- `extraVolumes` — additional pod volumes mounted alongside operator-managed volumes.
+- `extraVolumeMounts` — additional volume mounts on the Restate container.
+
+These fields are useful for running log shippers, metrics exporters, or proxies alongside Restate, and for wiring graceful-shutdown scripts:
+
+```yaml
+spec:
+  compute:
+    image: docker.restate.dev/restatedev/restate:latest
+    terminationGracePeriodSeconds: 120
+    extraVolumes:
+      - name: hooks
+        configMap:
+          name: node-state-control
+          defaultMode: 0755
+    extraVolumeMounts:
+      - name: hooks
+        mountPath: /node-state-control
+        readOnly: true
+    lifecycle:
+      preStop:
+        exec:
+          command: ["/bin/sh", "/node-state-control/pre-stop.sh"]
+    sidecars:
+      - name: log-shipper
+        image: log-shipper:latest
+        volumeMounts:
+          - name: hooks
+            mountPath: /node-state-control
+```
+
+All five fields are optional. Volume and mount names that conflict with operator-managed resources are rejected at reconcile time with a clear error.
+
+### Automatic cluster provisioning
+
+Set `spec.cluster.autoProvision: true` to have the operator automatically provision the Restate cluster once the pods are running. This calls the gRPC `ProvisionCluster` API and tracks the result in `status.provisioned` to prevent repeated calls.
+
+```yaml
+spec:
+  cluster:
+    autoProvision: true
+  config: |
+    # when using autoProvision, disable Restate's own auto-provision to avoid split brain
+    auto-provision = false
+    # ... rest of your config
+```
+
+<Warning>
+When `cluster.autoProvision: true` is set, you must also set `auto-provision = false` in your Restate config to avoid a split-brain situation where both the operator and Restate try to provision the cluster simultaneously.
+</Warning>
+
+### Trusted CA certificates
+
+When Restate needs to call services that use a private certificate authority, you can configure custom trusted CA certificates via `spec.security.trustedCaCerts`:
+
+```yaml
+spec:
+  security:
+    trustedCaCerts:
+      - secretName: internal-ca
+        key: ca.pem
+```
+
+The operator adds an init container that merges your custom CAs with the system CA bundle and sets `SSL_CERT_FILE` on the Restate container.
+
 ## Helm Chart
 
 For a more bare-bone deployment of a Restate cluster, you can use the Helm chart.
diff --git a/docs/services/deploy/kubernetes.mdx b/docs/services/deploy/kubernetes.mdx
@@ -75,7 +75,31 @@ The Restate Operator can help you connect your services to Restate Cloud by mana
     Or check out the [Restate Cloud documentation](/cloud/connecting-services#kubernetes-services) for more information.
 </Info>
 
-### Automatic Service Versioning
+### In-process tunnel mode
+
+For services running in private networks that need to connect to a Restate Cloud environment without inbound networking, set `spec.restate.tunnelMode: in-process`. With this mode, your pods hold their own outbound tunnel connections to Restate Cloud — for example using the `@restatedev/restate-sdk-tunnel` npm package — instead of being reached through the tunnel-client sidecar and each version's Service.
+
+```yaml
+spec:
+  restate:
+    register:
+      cloud: my-cloud-environment
+    tunnelMode: in-process
+```
+
+When `tunnelMode: in-process` is set, the operator injects these environment variables into every container:
+- `RESTATE_INPROC_TUNNEL_NAME` — the versioned name of the revision
+- `RESTATE_INPROC_ENVIRONMENT_ID` — the Restate Cloud environment ID
+- `RESTATE_INPROC_CLOUD_REGION` — the cloud region
+- `RESTATE_INPROC_SIGNING_PUBLIC_KEY` — for request verification
+
+Mount your API key Secret and point `RESTATE_INPROC_AUTH_TOKEN_FILE` at it — this variable is reserved for your own Secret mount and is not injected by the operator.
+
+<Note>
+In-process tunnel mode is not supported with Knative deployments.
+</Note>
+
+### Automatic service versioning
 Versioning gets handled automatically by the operator by keeping old ReplicaSets around with an associated Service object so that in-flight invocations can drain against the old code versions.
 
 Have a look at the [versioning documentation](/services/versioning#automatic-versioning-with-kubernetes-operator) to learn more.
@@ -151,9 +175,49 @@ Note that there is no need for routing to be sticky, because each invocation is
 No context is assumed to be sticky on the node.
 However, if you wish to do so, you can do sticky routing via the invocation ID in your request headers (`x-restate-invocation-id`).
 
-## Knative Deployment
+## Knative deployment
+
+Restate supports Knative Serving as a deployment target. Knative enables scale-to-zero when there are no in-flight invocations and automatically configures an L7 load balancer.
+
+### Knative with the Restate Operator (recommended)
+
+The Restate Operator supports Knative Serving as an alternative to ReplicaSet mode. This gives you the operator's automatic registration and versioning on top of Knative's autoscaling capabilities.
+
+Set `spec.serving.knative: true` in your `RestateDeployment`:
+
+```yaml
+apiVersion: restate.dev/v1beta1
+kind: RestateDeployment
+metadata:
+  name: service
+spec:
+  serving:
+    knative: true
+  restate:
+    register:
+      cluster: restate
+  template:
+    spec:
+      containers:
+        - name: service
+          image: path.to/yourrepo:yourtag
+          ports:
+            - containerPort: 9080
+              name: h2c
+```
+
+**Tag-based versioning**: use the `tag` field to control whether a pod template change creates a new versioned revision or updates in place:
+- **Same tag**: updates are applied in-place (no new version, no drain cycle).
+- **Changed tag**: treated as a new version — old revision drains while new revision handles new requests.
+- **No tag**: auto-versioning (every pod template change creates a new version).
+
+<Note>
+Knative Serving must be installed on the cluster. In-process tunnel mode (`tunnelMode: in-process`) is not supported with Knative deployments.
+</Note>
+
+### Knative without the operator
 
-Restate supports Knative services. Knative allows scaling to zero when there are no in-flight invocations and automatically configures an L7 load balancer. There are no special requirements to deploy a service deployment container with Knative:
+There are no special requirements to deploy a Restate service container with Knative directly:
 
 ```shell
 kn service create service-name --port h2c:9080 --image path.to/yourrepo:yourtag
@@ -176,9 +240,9 @@ spec:
               containerPort: 9080
 ```
 
-The service will be accessible at `http://<service-name>.<namespace>` but to handle [versioning](/services/configuration), it is preferable to register the new revision url like `http://<service-name>-0001.<namespace>` as part of your deployment workflow.
+The service will be accessible at `http://<service-name>.<namespace>`. To handle [versioning](/services/versioning), register the revision-specific URL (e.g. `http://<service-name>-0001.<namespace>`) as part of your deployment workflow.
 
-By default Knative exposes the service through the Ingress. This is not required by Restate, and you can disable this behavior adding the argument `--cluster-local` to the aforementioned creation command.
+By default Knative exposes the service through the Ingress. This is not required by Restate, and you can disable this behavior by adding the `--cluster-local` argument to the creation command.
 
 <Info>
     Learn more about deploying Restate services with Knative by reading this [blog post](https://www.restate.dev/blog/building-stateful-serverless-applications-with-knative-and-restate) and the [Golang example](https://github.com/restatedev/examples/tree/main/go/integrations/knative-go).
diff --git a/docs/services/versioning.mdx b/docs/services/versioning.mdx
@@ -62,6 +62,30 @@ The operator handles the complete versioning lifecycle:
 
 For complete examples and specifications, see [Restate Operator git repo](https://github.com/restatedev/restate-operator).
 
+### Per-version autoscaling during drain
+
+By default, draining versions hold their full replica count for the entire drain window, which can last hours for long-running workflows. To reduce compute cost during drains, add a `spec.autoscaling` block to your `RestateDeployment`. The operator creates a `HorizontalPodAutoscaler` per non-latest version while it is still active, and removes it once the version is fully drained.
+
+```yaml
+spec:
+  autoscaling:
+    minReplicas: 1
+    maxReplicas: 10
+    metrics:
+      - type: Resource
+        resource:
+          name: cpu
+          target:
+            type: Utilization
+            averageUtilization: 70
+```
+
+The `spec.autoscaling` block is optional. When omitted, draining versions stay at their full `replicas` count as before. The **latest** version is not covered here — use a separate HPA targeting the `RestateDeployment` scale subresource for the latest version.
+
+<Note>
+Per-version autoscaling is only available in ReplicaSet mode. It is not supported in Knative mode, where Knative's own autoscaler manages scaling.
+</Note>
+
 ## Manual versioning
 
 For non-FaaS deployments, you can use either the UI or the CLI to manage deployments. The typical update flow looks like this:
diff --git a/docs/snippets/common/install-restate-operator.mdx b/docs/snippets/common/install-restate-operator.mdx
@@ -2,9 +2,11 @@ Install the Restate Operator via Helm:
 
 ```bash
 helm install restate-operator \
-  oci://ghcr.io/restatedev/restate-operator-helm \
+  restatedev/restate-operator \
   --namespace restate-operator \
   --create-namespace
 ```
 
+The Helm chart installs the CRDs (`RestateCluster`, `RestateDeployment`, `RestateCloudEnvironment`) automatically. To manage CRDs externally (GitOps / ArgoCD), set `installCrds: false` in your values.
+
 To install the operator, you need to be able to create namespaces and CRDs.
