v2.5.1

Restate Operator v2.5.1 Release Notes

Highlights

• Fix: Knative deployments now work with Restate Cloud — The Knative reconciler was passing raw in-cluster Route URLs to the Restate admin API, which Restate Cloud cannot reach. Service URLs are now routed through the cloud tunnel, matching the existing ReplicaSet behavior.

Bug Fixes

Knative service URLs not tunneled for Restate Cloud

When using RestateDeployment in Knative mode with a Restate Cloud endpoint
(spec.restate.register.cloud), the operator passed the in-cluster Knative
Route URL directly to register_service_with_restate. Restate Cloud cannot
reach in-cluster URLs, so registration failed and the operator looped
indefinitely.

The fix extracts a maybe_tunnel_url() method from RestateAdminEndpoint and
calls it in the Knative reconciler after resolving the Route URL, matching how
the ReplicaSet reconciler already handled this case.

Impact on Users:

• Knative + Restate Cloud deployments: This was broken; it now works.
• Knative + non-Cloud deployments: No change; maybe_tunnel_url is a no-op
  when cloud is not set.
• ReplicaSet deployments: No change. The internal refactoring of
  service_url_for_deployment() is equivalent to the previous behavior.

Related: Issue #120, PR #122

---

Upgrading

No CRD changes in this release. Upgrade the operator via Helm:

helm upgrade restate-operator restatedev/restate-operator --version 2.5.1

v2.5.0

Restate Operator v2.5.0 Release Notes

Highlights

• Custom pod annotations and labels — RestateCluster now supports spec.compute.annotations and spec.compute.labels, enabling integrations that require pod-level metadata (GKE ComputeClass, Vault agent injection, Prometheus scraping, etc.).
• Default canary image changed to alpine:3.21 — Fixes trustedCaCerts (introduced in v2.4.0), which required a CA bundle that the previous busybox:uclibc default did not ship.
• Default tunnel client image bumped to 0.6.0 — Picks up the latest restate-cloud-tunnel-client release for new RestateCloudEnvironment deployments.

New Features

Custom pod annotations and labels

Added spec.compute.annotations and spec.compute.labels to the RestateCluster
CRD. Both fields are propagated to the Restate StatefulSet pod template.

User-specified annotations and labels are merged with any the operator sets
internally (e.g. for Workload Identity, trusted CA certs). In case of conflict,
operator-managed values take precedence.

This unblocks integrations that rely on pod-level metadata, including GKE
ComputeClass scheduling (cloud.google.com/compute-class), Vault agent
injection, Datadog, Prometheus scraping, and custom scheduling constraints.

Impact on Users:

• Existing deployments: No impact, both fields are optional.
• New deployments: Can now set annotations and labels for integrations that
  require them on the pod template.

Usage:

spec:
  compute:
    annotations:
      cloud.google.com/compute-class: "restate-workload"
    labels:
      team: "platform"

Related: Issue #45, PR #119

---

Bug Fixes

Default canary image now ships a CA bundle

The default canaryImage has changed from busybox:uclibc to alpine:3.21.

The trustedCaCerts feature added in v2.4.0 uses an init container (the canary
image) to concatenate system CA certificates with custom trusted CAs. The init
container reads the system CA bundle from /etc/ssl/certs/ca-certificates.crt,
but busybox:uclibc does not ship a CA bundle at that path, causing the init
container to fail with:

cat: can't open '/etc/ssl/certs/ca-certificates.crt': No such file or directory

This made trustedCaCerts non-functional with the default canary image.

Impact on Users:

• Existing deployments using trustedCaCerts: Will work after upgrading. If
  you previously worked around this by setting canaryImage to an image with a
  CA bundle, you can remove that override.
• Existing deployments not using trustedCaCerts: No impact. The canary
  image is also used for Pod Identity and Workload Identity canary jobs, which
  do not depend on the CA bundle and will continue to work with alpine:3.21.
• Custom canaryImage overrides: If you use a custom canary image, ensure
  it includes a CA bundle at /etc/ssl/certs/ca-certificates.crt if you plan to
  use trustedCaCerts.

Migration Guidance:
No action required. The default will change automatically on upgrade.

If you override canaryImage in your Helm values and want to use
trustedCaCerts, ensure your image includes a CA certificate bundle:

# Image must have /etc/ssl/certs/ca-certificates.crt and provide cat, grep, wget
canaryImage: my-registry.example.com/alpine:3.21

Related: PR #116

---

Improvements

Default tunnel client image bumped to 0.6.0

The default tunnelClientDefaultImage has been updated from
ghcr.io/restatedev/restate-cloud-tunnel-client:0.5.0 to 0.6.0. This applies
to new RestateCloudEnvironment deployments that don't explicitly override the
tunnel client image.

Impact on Users:

• Existing deployments pinning their own tunnel client image: no impact.
• Deployments relying on the operator default: will pick up 0.6.0 on the next
  reconcile after upgrade.

Override via the --tunnel-client-default-image CLI flag or the
OPERATOR_TUNNEL_CLIENT_DEFAULT_IMAGE environment variable (settable through
the chart's generic env value) if you need to pin a specific version.

Related: PR #118

---

Upgrading

CRD Update Required: Helm does not automatically upgrade CRDs. After
upgrading the operator, you must manually apply the updated CRDs:

kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.5.0/restateclusters.yaml
kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.5.0/restatedeployments.yaml
kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.5.0/restatecloudenvironments.yaml

Then upgrade the operator via Helm:

helm upgrade restate-operator restatedev/restate-operator --version 2.5.0

v2.4.0

Restate Operator v2.4.0 Release Notes

Highlights

• Trusted CA certificates - RestateCluster now supports custom trusted CA certificates via spec.security.trustedCaCerts, removing the need for custom Restate images when using internal CAs.
• Configurable canary image - The canary job image is now configurable via Helm, supporting air-gapped and restricted registry environments.
• IPv6 support - The operator now binds to a dual-stack address, fixing readiness probe failures on IPv6-only clusters.
• Faster drain cleanup - Old deployment versions are now polled every 10 seconds during drain, instead of waiting up to 5 minutes.

New Features

Trusted CA certificates

You can now configure custom trusted CA certificates for RestateCluster via
spec.security.trustedCaCerts. This is useful when Restate needs to trust internal CAs, for example when
calling services behind an internal load balancer with a private certificate.

The operator adds an init container that concatenates the system CA bundle with
your custom certificates into a single PEM file, and sets SSL_CERT_FILE on
the Restate container to point to the combined bundle.

Changing the Secret references (name or key) triggers a pod rollout.

spec:
  security:
    trustedCaCerts:
      - secretName: internal-ca
        key: ca.pem

Related: PR #111

---

Configurable canary image

The container image used for PIA and Workload Identity canary jobs is now
configurable via the canaryImage Helm value, CANARY_IMAGE environment
variable, or --canary-image CLI flag. Previously busybox:uclibc was
hardcoded, which fails in environments that cannot pull from Docker Hub.

canaryImage: my-registry.example.com/busybox:uclibc

The simplest approach is to mirror the default image:

docker pull busybox:uclibc
docker tag busybox:uclibc my-registry.example.com/busybox:uclibc
docker push my-registry.example.com/busybox:uclibc

If using a different image, it must provide cat, grep, and wget.

Related: Issue #94, PR #106

---

Bug Fixes

IPv6 dual-stack support

The operator now binds its HTTP server to [::] instead of 0.0.0.0,
supporting both IPv4 and IPv6 clusters. Previously, the readiness probe
failed on IPv6-only clusters because the operator only listened on IPv4.

Related: Issue #93, PR #107

---

Faster drain cleanup polling

When old deployment versions still have active invocations (draining), the
operator now requeues every 10 seconds instead of waiting for the default
5-minute reconcile interval. This means old versions are cleaned up within
seconds of drain completion rather than up to 5 minutes.

Related: PR #112

---

Upgrading

CRD Update Required: Helm does not automatically upgrade CRDs. After
upgrading the operator, you must manually apply the updated CRDs:

kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.4.0/restateclusters.yaml
kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.4.0/restatedeployments.yaml
kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.4.0/restatecloudenvironments.yaml

Then upgrade the operator via Helm:

helm upgrade restate-operator restatedev/restate-operator --version 2.4.0

v2.3.1

Restate Operator v2.3.1 Release Notes

This contains an important fix for a bug introduced v2.3.0. If you're using v2.3.0 you will need to upgrade to this version.

Highlights

• Fix: GCP Workload Identity now requires explicit opt-in via gcpWorkloadIdentity: true Helm value, fixing a 403 error loop on non-GCP clusters introduced in v2.3.0.

Bug Fixes

IAMPolicyMember cleanup causes 403 on non-GCP clusters

In v2.3.0, the operator unconditionally attempted to delete IAMPolicyMember
resources during reconciliation, even on non-GCP clusters where the RBAC rules
were not granted. This caused a 403 Forbidden error loop on every reconcile.

The operator now requires the gcpWorkloadIdentity Helm value to be explicitly
set before it will create or delete IAMPolicyMember resources. The
iam.gke.io/gcp-service-account annotation is ignored with a warning unless
the flag is enabled.

Impact on Users:

• Non-GCP clusters: The 403 reconcile loop is fixed. No action needed.
• GCP clusters using Workload Identity: You must now set
  gcpWorkloadIdentity: true in your Helm values.

Migration Guidance:

If you are using GCP Workload Identity with Config Connector, add to your Helm
values:

gcpWorkloadIdentity: true

Related: Issue #103, PR #104

---

Upgrading

Upgrade the operator via Helm:

helm upgrade restate-operator restatedev/restate-operator --version 2.3.1

No CRD changes in this release.

v2.3.0

Restate Operator v2.3.0

✨ New Features

• GCP Workload Identity via Config Connector — The operator now automatically creates IAMPolicyMember resources to bind Kubernetes service accounts to GCP service accounts via Workload Identity. This is triggered when a RestateCluster has iam.gke.io/gcp-service-account in serviceAccountAnnotations. The GCP project ID is extracted from the service account email, so no additional configuration is needed beyond the annotation. A canary job validates that credentials are available before the StatefulSet proceeds. This mirrors the existing AWS Pod Identity Association pattern and requires Config Connector to be installed on the GKE cluster.

• Configurable cluster DNS suffix — The operator now supports configuring the Kubernetes cluster DNS suffix via the --cluster-dns CLI flag, CLUSTER_DNS environment variable, or Helm clusterDns value. Previously cluster.local was hardcoded in all internal service URLs. This is needed for multi-cluster setups, federated environments, and clusters with custom DNS naming.

• Configurable drain delay — Added drainDelaySeconds to the RestateDeployment CRD's spec.restate section. This controls how long the operator waits after a deployment is drained before removing the old version. Default remains 300 seconds (5 minutes). (#96)

🐛 Bug Fixes

• Improved admin API error messages — When a deployment registration is rejected by the admin API (e.g. breaking changes without --force), the error message now includes the response from Restate and is logged and emitted as a Kubernetes event, making failures much easier to diagnose. (#100)

• Fixed canary job completion detection — Fixed a bug where a completed canary job was treated as still pending, causing the operator to loop indefinitely with a NotReady status condition. (#102)

⚙️ Configuration Changes

• New Helm value clusterDns for configuring the cluster DNS suffix (default: cluster.local)
• Conditional RBAC for IAMPolicyMember CRDs when GCP Workload Identity is enabled

---

⚠️ Upgrading Notes

CRD Update Required: Helm does not automatically upgrade CRDs. After upgrading the operator, you must manually apply the updated CRDs:

kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.3.0/restateclusters.yaml
kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.3.0/restatedeployments.yaml
kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.3.0/restatecloudenvironments.yaml

Then upgrade the operator via Helm:

helm upgrade restate-operator restatedev/restate-operator --version 2.3.0

---

Full release notes: release-notes/v2.3.0.md

v2.2.0

Restate Operator v2.2.0

✨ New Features

• Knative Serving deployment mode — RestateDeployment now supports Knative Serving as an alternative to traditional ReplicaSets. This enables:

  • Scale-to-zero: Services automatically scale down when idle, saving resources
  • Automatic scaling: Replicas scale based on concurrent request load
  • In-place updates: Update service implementation without changing Restate deployment identity
  • Tag-based identity: Control versioning behavior with the tag field — same tag means in-place update, changed tag means versioned update, no tag means auto-versioning

  See the Knative Serving Mode documentation for details. (#64)

🐛 Bug Fixes

• Fix DNS network policy for NodeLocal DNSCache — The operator now creates DNS egress policies that work with both traditional kube-dns and NodeLocal DNSCache (169.254.20.10). This fixes DNS resolution issues on GKE Autopilot and other Kubernetes environments using node-local DNS caching. (#88)

⚙️ Configuration Changes

• Default partitions increased to 24 — The default number of partitions is now 24 (previously lower), providing better parallelism for most workloads. (#84)

📝 Documentation

• Added dedicated Knative Serving mode section to README with examples and tag-based versioning guide
• Added troubleshooting section for DNS resolution issues
• Updated RocksDB memory documentation (#82)

---

⚠️ Upgrading Notes

CRD Update Required: Helm does not automatically upgrade CRDs. After upgrading the operator, you must manually apply the updated CRDs:

kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.2.0/restateclusters.yaml
kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.2.0/restatedeployments.yaml
kubectl apply --server-side -f https://github.com/restatedev/restate-operator/releases/download/v2.2.0/restatecloudenvironments.yaml

Note: The restatedeployments CRD update is especially important for this release as it includes the new Knative Serving deployment mode fields.

Then upgrade the operator via Helm:

helm upgrade restate-operator restatedev/restate-operator --version 2.2.0

---

New Contributors

• @AhmedSoliman made their first contribution in #82

Full Changelog: v2.1.0...v2.2.0

v2.2.0-alpha1

What's Changed

• Add Knative Serving deployment mode with scale-to-zero and in-place updates by @EronWright in #64

Full Changelog: v2.1.0...v2.2.0-alpha1

v2.1.0

✨ New Features

• Operator-driven cluster provisioning - Added support for automatic cluster provisioning via the new spec.cluster.autoProvision field. When enabled, the operator will automatically provision the Restate cluster by calling the gRPC ProvisionCluster API after pods are running. This is particularly useful for multi-node clusters where manual provisioning was previously required. The provisioning status is tracked in status.provisioned to prevent repeated provisioning attempts. (#55)

  ⚠️ Important: When using cluster.autoProvision: true, you must set auto-provision = false in your Restate config to avoid split brain situations.

  🎯 cluster.autoProvision: true is the recommended approach for provisioning Restate clusters.

🔧 Improvements

• Simplified example configurations by removing default values that are no longer needed (replicated loglet and replicated metadata server are now defaults)

🏗️ CRD Changes

• Added spec.cluster.autoProvision field to enable operator-managed cluster provisioning
• Added status.provisioned field to track provisioning state

⬆️ Upgrading

CRD Update Required: Helm does not automatically upgrade CRDs. After upgrading the operator, you must manually apply the new CRDs:

kubectl apply -f https://github.com/restatedev/restate-operator/releases/download/v2.1.0/restateclusters.yaml
kubectl apply -f https://github.com/restatedev/restate-operator/releases/download/v2.1.0/restatedeployments.yaml
kubectl apply -f https://github.com/restatedev/restate-operator/releases/download/v2.1.0/restatecloudenvironments.yaml

Full Changelog: v2.0.0...v2.1.0

v2.0.0

What's Changed

• Update default tunnel client version by @jackkleeman in #81

Full Changelog: v1.9.2...v2.0.0

v1.9.2

What's Changed

• Avoid reconcile loop in netpol peer list by @jackkleeman in #73

Full Changelog: v1.9.1...v1.9.2