Skip to main content

Operator quickstart

After installing Diagrid, create a governed project that a team can safely build in. This guide covers the common operations you perform as a platform operator, walking that journey end to end with the diagrid CLI: create a project, create the team's workload identities, wire up infrastructure, lock it down with zero-trust controls, and hand it over.

Each step is a command you can run. Every step also has an equivalent in the Diagrid Web Console and a declarative form you can keep in Git.

What you'll build​

By the end of this guide you'll have a project with apps, scoped infrastructure, access controls, trace export, and project-scoped team access.

A governed projectProjectYour workloadsAppComponentPoliciesYour infrastructure
A governed projectYour workloads connect to an app in the project, and its components connect to your infrastructure. The project also holds the policies.

Before you begin​

# Authenticate the CLI to your Diagrid organization
diagrid login

1. Create a project for a team​

A project is the isolation boundary you hand to a team or environment. Create a project, then enable only the managed infrastructure required by the workloads that will run in it, and set it as your default so every project-scoped command that follows runs within it:

# Create a project and set it as the default for later commands
diagrid project create payments --use

Provision the managed infrastructure that matches what the team runs:

  • Applications — add --deploy-managed-pubsub and --deploy-managed-kv for Catalyst-hosted Pub/Sub and key-value stores.
  • Workflow applications — nothing to add. Every new project gets the managed workflow store by default.
  • Agents — nothing to add for the workflow store, which every agent needs because it runs as a durable workflow. When you create the project's first agent, Diagrid creates the components agents need. The project's region must support the managed key-value store. See Framework requirements.
  • MCP servers — no managed infrastructure needed. The project simply routes MCP and service-invocation calls between workloads, acting as a secure gateway.

See Projects for the full set of project options.

2. Create workload identities​

Every workload — an application, an agent, or an MCP server — needs an ID, its identity inside the project. The ID does two jobs: it lets the workload connect to Diagrid, authenticating every API call it makes, and it is the handle you scope security to — components, access policies, and resiliency all bind to it. Create workloads first, so you can scope infrastructure and policies to them in the next steps:

# An application
diagrid app create orders-api

# An agent
diagrid agent create billing-agent

# An MCP server
diagrid mcpserver create github-mcp --url https://mcp.example.com/mcp

Each kind has its own command because each is a different resource: an MCP server needs the URL of the server it fronts, and only an agent or an app can be given an endpoint Diagrid calls back into.

To connect code to the project, the team needs two things: the project's endpoints (shared by every workload) and each workload's API token. Retrieve them and share them securely:

# Project HTTP and gRPC endpoints
diagrid project get payments

# An App ID's API token
diagrid app get orders-api

The team sets these as the DAPR_HTTP_ENDPOINT, DAPR_GRPC_ENDPOINT, and DAPR_API_TOKEN environment variables. — see Connect to Diagrid. For dev/test, diagrid dev run injects them automatically. For day-2 operations on apps, see IDs.

3. Connect backing infrastructure​

Managed services cover Pub/Sub, key-value, and workflow. To wire in infrastructure you operate — your Redis, Postgres, or Kafka, whether it runs on-premises or in a cloud — create a component. The component abstracts that infrastructure and decouples it from your application: the workload calls a standard Dapr API while Diagrid routes the call to whatever the component points at, so you can swap the backing store without changing application code. Scope it to the workloads that may use it:

# Register your Redis as a state store, usable only by the orders-api workload
diagrid component create orders-state \
  --type state.redis \
  --metadata redisHost=my-redis.internal:6379 \
  --metadata redisPassword=<password> \
  --scopes orders-api

See Components for the full catalog of supported component types.

4. Bring your own secret store​

By default, Diagrid manages secrets for you: when you create a component, endpoint, or configuration, it extracts the sensitive fields — passwords, tokens, keys — into a built-in managed secret store and replaces them with references, so plaintext is never stored in the control plane. No setup required.

If your organization already keeps credentials in AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault, bring it instead. Register it as a secretstores component, and Diagrid resolves secret references through it at runtime:

# Register your own HashiCorp Vault as a secret store
diagrid component create team-vault \
  --type secretstores.hashicorp.vault \
  --metadata vaultAddr=https://vault.internal:8200 \
  --metadata vaultToken=<token> \
  --scopes orders-api

The managed store and your own can coexist. See Manage secrets.

5. Lock it down with zero trust​

Diagrid gives you project-level isolation by default — the workloads and resources inside a project can reach one another, while everything outside it is denied. From there you tighten access at the workload, component, topic, and workflow levels with these controls:

  • Scope every component to a single workload. List one workload in the component's scopes and only that workload can use it — every other workload in the project is denied the infrastructure behind it:

    diagrid component create orders-state --type state.redis --scopes orders-api

  • Lock down access between workloads. Attach a deny-by-default access policy to a target workload and allow-list only its expected callers; any other workload that tries to invoke it is rejected before the call reaches it (see service invocation). MCP servers are deny-by-default too — grant a caller access to specific tools:

    diagrid mcpserver access grant github-mcp --caller billing-agent --allow-tools create_issue,list_issues --wait

  • Scope pub/sub topics. On the pub/sub component, publishingScopes limits which topics each workload may publish to and subscriptionScopes limits which it may subscribe from; anything outside those lists is blocked. Here orders-api may only publish to orders, and billing-agent may only subscribe to it:

    # orders-pubsub.yaml
    apiVersion: cra.diagrid.io/v1beta1
    kind: Component
    metadata:
      name: orders-pubsub
    spec:
      type: pubsub.redis
      version: v1
      metadata:
        - name: redisHost
          value: "my-redis.internal:6379"
        - name: publishingScopes
          value: "orders-api=orders"
        - name: subscriptionScopes
          value: "billing-agent=orders"
    scopes:
      - orders-api
      - billing-agent

  • Lock down cross-application workflows. Allow-list which apps may schedule workflows and activities on a workflow application; a caller that isn't listed is rejected with a PermissionDenied error (see workflow access policies):

    diagrid workflow access-policy create orders-workflow-policy --scopes orders-api --callers billing-agent

  • Verify workflow history. Diagrid cryptographically signs each step it records, so a workflow's history cannot be altered after the fact without detection — giving you a verifiable, provable record of exactly what ran. It can only be enabled at project creation:

    diagrid project create payments --deploy-managed-kv --deploy-managed-pubsub --enable-workflow-history-signing --use

    Signed histories persist in the project's workflow state store — the managed one, or a state store you bring yourself. See Configure the workflow state store.

Together these give you defense in depth across identity, access, messaging, and execution. For the bigger picture, read Zero-trust security for distributed applications with Dapr.

6. Export traces to your observability backend​

Out of the box, Diagrid gives you metrics, API logs, and the topology for every workload — no setup required. If you also run a centralized tracing backend, you can export distributed traces to any OpenTelemetry (OTLP) collector — Grafana Tempo, Jaeger, Datadog, or your own — so Diagrid traffic shows up alongside the rest of your telemetry. Create a Configuration for trace export and attach it to the apps whose traces you want to export:

# Create a configuration that exports traces to your OpenTelemetry collector
diagrid configuration create otel-export \
  --tracing-sampling-rate 1 \
  --tracing-otel-endpoint otel-collector.observability:4317 \
  --tracing-otel-protocol grpc

Attaching the configuration is an App ID setting rather than an app one, so set appConfig on the app's backing App ID and apply it:

# orders-api-appid.yaml
apiVersion: cra.diagrid.io/v1beta1
kind: AppIdentity
metadata:
  name: orders-api
spec:
  appConfig: otel-export
diagrid apply -f orders-api-appid.yaml

For a secured collector, add --tracing-otel-secure and --tracing-otel-header 'Authorization:Bearer <token>'. A single Configuration can combine tracing with access control, so attach one per app.

7. Hand the project off​

The project is now a secure, ready-to-use space. Give the team access by adding users with a role scoped to this project. The role decides what each person can do:

  • Admin — full control of the project: create and change apps, components, and policies. Give this to the team that owns the project.

    diagrid user create --email lead@example.com --name "Team lead" --role cra.diagrid:admin:projects:payments

  • Viewer — read-only access to every resource, with no ability to change anything. Good for support staff or auditors.

    diagrid user create --email support@example.com --name "Support" --role cra.diagrid:viewer:projects:payments

Roles in between — such as cra.diagrid:editor — grant create and update access without full admin rights. See Manage access for the full role matrix, organization-wide roles, SSO, and API keys for automation.

The team then connects applications and agents (see Connect to Diagrid) and creates any additional apps and workloads. From there you operate and observe everything in one place: workflows, agents, and metrics, API logs, and the topology.

Manage Diagrid as code​

Every command above has a declarative equivalent. Keep your projects, components, apps, and policies as YAML in Git and apply them with a single upsert command that works for any resource kind:

# Create or update any resource (project, component, App ID, policy) from YAML
diagrid apply -f payments-project.yaml

Use diagrid export to capture existing resources as YAML, and wire diagrid apply into CI/CD for GitOps. See Declarative management.

Next steps​

Last updated on