Skip to main content

Migrate with the Catalyst Kubernetes operator

The Catalyst Kubernetes operator is a Kubernetes-native way to migrate your workloads from Dapr OSS. It can read your existing Dapr resources directly from Kubernetes and only requires you to migrate from the dapr.io annotations to the catalyst.diagrid.io annotations. It will manage configuring Catalyst for you and integrating your workloads without manual intervention.

1. Deploy the operator​

Install cert-manager first

The operator's mutating webhook needs a serving certificate, and by default the chart has cert-manager issue it. Install cert-manager before the operator:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
kubectl wait --for=condition=Available -n cert-manager deploy --all --timeout=120s

The CLI checks for cert-manager before it installs anything and stops with these commands if it is missing. Plain Helm does not check, so on the Helm tab below the install fails part-way with a resource mapping error for Certificate in cert-manager.io/v1 instead of telling you what to install.

Already managing the webhook certificate yourself? Pass --set webhook.certManager.enabled=false and the chart renders no cert-manager resources.

You can use the Diagrid CLI to install the Catalyst Kubernetes operator Helm chart into your cluster.

diagrid k8s-operator install

You can also override the Helm values using the --set flag:

diagrid k8s-operator install --set some.helm.value=foo

The chart also installs the Dapr CRDs, which on this migration path your Dapr open source installation already owns. The CLI checks the cluster before it installs and turns them off for you when it finds them, so diagrid k8s-operator install works whether or not Dapr is present. To decide yourself instead, set the value explicitly — --set dapr.installCRDs=false never installs them, --set dapr.installCRDs=true always does, and either choice is left untouched:

diagrid k8s-operator install --set dapr.installCRDs=false

To uninstall the Catalyst Kubernetes operator, run:

diagrid k8s-operator uninstall

See the Helm chart reference for the full list of values you can set on the chart.

2. Migrate resources​

You can use the Diagrid CLI to automatically migrate an existing namespace or you can manually annotation your workloads and Dapr resources within a namespace.

Add the annotations with the CLI​

You can migrate a namespace in-place, which will update the annotations and sidecar on your existing workloads and CRDs to use Catalyst instead of Dapr OSS.

diagrid k8s-operator migrate my-namespace --project my-project

Or you can copy your existing namespace to a new one and only update the copy, leaving the original namespace untouched.

diagrid k8s-operator migrate my-namespace --project my-project \
  --new-namespace my-namespace-copy

We recommend using --new-namespace on any real use cases to ensure you can validate the migrated workloads before removing the existing workloads.

Your workloads restart

migrate writes the annotations onto the pod template, which Kubernetes treats as a change to the Deployment. Your pods are replaced by a rolling update as soon as the command finishes — that is when the Dapr OSS sidecar goes and the Catalyst one arrives. You do not need to restart anything yourself.

Migrating in place therefore restarts the running workload. With --new-namespace the restart happens in the copy, and the original is left alone, which is the other reason to prefer it.

If you want to use local Dapr Servers, you must add the --host local flag to the migrate command:

diagrid k8s-operator migrate my-namespace --project my-project \
  --host local

In a public region, a local Dapr server cannot run workflows or use the managed KV store and pub/sub. See Dapr Server location before you choose it.

Add the annotations manually​

You can also manually apply the necessary catalyst.diagrid.io annotations to your workloads and Dapr resources.

Workloads​

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders
spec:
  template:
    metadata:
      annotations:
        catalyst.diagrid.io/enabled: "true"
        catalyst.diagrid.io/app-id: "orders"
        catalyst.diagrid.io/provider: "catalyst"          # tells the Catalyst operator to claim this pod
        catalyst.diagrid.io/project: "my-project"         # which Catalyst project to register against
        catalyst.diagrid.io/host: "remote"                # or "local" to inject the sidecar
        catalyst.diagrid.io/app-port: "8080"              # optional
        catalyst.diagrid.io/app-protocol: "grpc"          # optional

catalyst.diagrid.io/host is the switch between remote and local location. The operator reads only the annotations listed above — any dapr.io/* annotations on the pod are ignored. To prevent the Dapr OSS operator from also acting on the pod, the Catalyst operator disables the dapr.io/enabled annotation whenever catalyst.diagrid.io/enabled is present, so you don't get conflicting sidecars.

Dapr resources​

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: orderstate
  annotations:
    catalyst.diagrid.io/project: "my-project"
spec:
  type: state.redis
  version: v1
  metadata:
    - name: redisHost
      value: redis:6379

CRDs without catalyst.diagrid.io/project are left alone, which is useful for keeping in-cluster Dapr OSS resources side-by-side with Catalyst-managed ones during a phased migration.

Connecting Catalyst to your app endpoints​

Some Dapr APIs require the Dapr server to be able to call endpoints on your application, such as service invocation, input bindings or programmatic pub/sub subscriptions. When using the Catalyst Kubernetes Operator, all you need to do is ensure you have the following annotation:

catalyst.diagrid.io/app-port: "8080" # or whatever port your app listens on

For remote Dapr servers, the operator will establish a secure tunnel between Catalyst and your app so that traffic can flow without you having to expose the app directly to the Catalyst network.

For local Dapr servers (external apps), the operator will set the app's appEndpoint to https://localhost:<app-port> and the sidecar will route traffic from Catalyst to your app over localhost.

Next steps​

Once your workloads are running on Catalyst, cut over your traffic and decommission Dapr OSS.

Last updated on