Migrate with Catalyst-native tooling

With Catalyst-native tooling you create your Catalyst resources yourself — using the UI, CLI, or Terraform — then wire each workload to Catalyst. This requires a little more work than the Catalyst Kubernetes Operator but gives you more control over how you interact with and automate your project setup.

1. Create your Catalyst resources

Catalyst resources can be created imperatively using the CLI or web console, or declaratively using Terraform or YAML manifests. Pick the tooling that best fits how you manage infrastructure today.

UI

1. Visit the Catalyst web console at catalyst.diagrid.io and create a new project.
2. Create an App ID for each Dapr-enabled application. If you want to use local location, you must enable the external flag on the App ID.
3. Recreate each Dapr component using the components catalog and scope it to the relevant App IDs.
4. Recreate any other pub/sub subscriptions, configurations, and resiliency policies in the console as well.
5. If your app receives pub/sub messages or bindings, configure the App Connection for each App ID so Catalyst can deliver them.

CLI

The fastest path is diagrid apply, which mirrors kubectl apply and accepts a directory of YAML resources. Authenticate and create the target project once:

diagrid login
diagrid project create my-project --wait --use

Apply your existing Dapr OSS Component, Subscription, Configuration, and Resiliency manifests:

diagrid apply --project my-project -f ./dapr-resources/

You still need an AppID per workload, since Dapr OSS identifies apps via the dapr.io/app-id annotation rather than a CRD. Add them declaratively alongside your Dapr CRDs:

# ./dapr-resources/appids/orders.yaml
apiVersion: cra.diagrid.io/v1beta1
kind: AppID
metadata:
  name: orders
spec:
  appEndpoint: https://orders.example.com # endpoint app is listening on (optional)
  appProtocol: http
  external: true # only if using local location

Or create them imperatively:

diagrid appid create orders --project my-project \
  --app-endpoint https://orders.example.com \
  --app-token $APP_TOKEN \
  --app-protocol http \
  --external # only if using local location

Plaintext secrets in component metadata are automatically extracted into a managed secret store on apply — see Managing secrets.

See the full CLI reference for every command and flag.

Terraform

Use the Diagrid Catalyst Terraform provider to model Catalyst resources alongside the rest of your infrastructure. Authenticate by setting CATALYST_API_KEY (or passing api_key to the provider block).

terraform {
  required_providers {
    catalyst = {
      source = "diagridio/catalyst"
    }
  }
}

provider "catalyst" {
  api_key = var.catalyst_api_key
}

resource "catalyst_project" "my_project" {
  name   = "my-project"
  region = "region1"
}

resource "catalyst_appid" "orders" {
  project_id = catalyst_project.my_project.name
  name       = "orders"
  protocol   = "http"

  app_endpoint = {
    url = "https://orders.example.com"
  }

  external = true # only if using local location
}

resource "catalyst_component" "orderstate" {
  project_name = catalyst_project.my_project.name
  name         = "orderstate"
  spec = {
    type    = "state.redis"
    version = "v1"
    metadata = [
      { name = "redisHost", value = "redis:6379" },
      {
        name = "redisPassword"
        secret_key_ref = {
          name = "redis-secret"
          key  = "password"
        }
      },
    ]
  }
  scopes = [catalyst_appid.orders.name]
}

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-native tooling, you will need to manually connect Catalyst to your workload's app endpoints.

For local location (external App IDs), you will be able to set the appEndpoint field on the App ID to point to the local address you app listens on e.g. http://localhost:8080.

For remote location, you need to expose your app to the Catalyst network and set the appEndpoint to that address.

If it is not possible to establish a direct connection, you may want to consider using the Catalyst Kubernetes operator which automates establishing a secure tunnel between Catalyst and your app without requiring you to expose the app directly to the Catalyst network. A similiar technique can be achieved manually by installing the Diagrid CLI in your app container and setting the entry point command to:

diagrid dev run \
  --project ${PROJECT_NAME} \
  --appid ${APP_ID} \
  --app-port ${APP_PORT} \
  --skip-managed-kv \ # omit if you want to use Catalyst managed kvstore
  --skip-managed-pubsub \ # omit if you want to use Catalyst managed pubsub
  --approve -- <your app command>

Ensuring that you set the env vars DIAGRID_API_KEY, DAPR_API_TOKEN, PROJECT_NAME, APP_ID, and APP_PORT appropriately.

2. Connect your workloads

Remote: Catalyst manages the Dapr server

Update each Deployment:

1. Remove the dapr.io/* annotations and the Dapr OSS sidecar from the workload spec (deployment, statefulset, etc.).
2. Fetch the Catalyst Dapr HTTP/gRPC endpoints and API token for the corresponding App ID.

# Get the project endpoints
diagrid project get my-project -a

# Get the appid token
diagrid appid get my-app --project my-project

Alternatively, you can find these in the web console, or output them from your Terraform resources.

3. Inject the Catalyst endpoints and token as environment variables into your workload spec, typically via a Kubernetes Secret:

   Env var	Value
   DAPR_HTTP_ENDPOINT	Project HTTP endpoint
   DAPR_GRPC_ENDPOINT	Project gRPC endpoint
   DAPR_API_TOKEN	App ID API token

4. Roll the workload out. The app now calls Catalyst over HTTP/gRPC; no sidecar runs in the pod.

Local: the Catalyst Dapr server runs as a app sidecar in your cluster

If you need to run Dapr in the app pod but don't want to use the Catalyst Kubernetes operator, you can set it up manually:

1. Create an App ID with the external flag enabled and wait for it to become ready.
2. Grab the bootstrap config from the App ID status and store it somewhere your pod can mount it (a ConfigMap or Secret).
3. Create or reuse an existing certificate issuer CA (issuer.pem, issuer.key and ca.pem) that can be used to establish trust for your app workload identities.
4. Mount three things into the app sidecar container: the bootstrap config, the issuer cert and key, and the trust anchor bundle.
5. Set these environment variables on the sidecar container:
   • BOOTSTRAP_CONFIG_PATH — path to the bootstrap config inside the container.
   • WORKLOAD_IDENTITY_ISSUER_CERT — path to the issuer certificate.
   • WORKLOAD_IDENTITY_ISSUER_KEY — path to the issuer private key.
   • WORKLOAD_IDENTITY_TRUST_ANCHORS — path to the trust anchor bundle.

The sidecar uses these to establish workload identity with Catalyst and pull down its configuration. Your app keeps talking to localhost on the standard Dapr ports.

Next steps

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