# Manage Catalyst Components

A **component** is how Catalyst plugs a Dapr API into real infrastructure. For example, a `state` component tells Catalyst which database backs the State API; a `pubsub` component tells it which broker powers Publish/Subscribe. You write a short YAML spec and Catalyst handles the wiring. Components are scoped to specific workload [IDs](https://docs.diagrid.io/operate/project-operations/ids), so you control which ones can use which infrastructure.

Catalyst supports the full set of Dapr components. The complete catalog, including the required metadata for each component type, is published in the [Components reference](https://docs.diagrid.io/references/catalyst/components-reference/intro).

:::tip Manage from the Catalyst console

Every operation on this page — creating, scoping, updating, and deleting components, subscriptions, HTTP endpoints, resiliency policies, and configurations — can also be done from the Catalyst Web UI at [catalyst.diagrid.io](https://catalyst.diagrid.io), which offers a guided experience equivalent to the `diagrid component create` interactive CLI wizard.

:::

## Component types

| Type | Purpose | Examples |
|------|---------|----------|
| **State** | Key-value storage for state, actor state, and workflow state. | Redis, PostgreSQL, Cassandra, AWS DynamoDB, Azure Cosmos DB, GCP Firestore |
| **Pub/Sub** | Message brokers for publish/subscribe messaging. | Kafka, RabbitMQ, Redis, AWS SNS/SQS, Azure Service Bus, GCP Pub/Sub |
| **Bindings** | Trigger apps from external events (input) or send data to external systems (output). | HTTP, S3, Azure Blob, Twilio, Kubernetes, Postmark |
| **Secret stores** | Back secret references in other components. | AWS Secrets Manager, Azure Key Vault, HashiCorp Vault |
| **Configuration stores** | Read application configuration values at runtime. | PostgreSQL, Redis, Azure App Configuration |
| **Conversation** | Route prompts to LLM providers via a unified component. | Anthropic, OpenAI, DeepSeek, HuggingFace |
| **Middleware** | HTTP middleware applied to app endpoints. | OAuth2, OPA, rate-limit, bearer-token, router-checker |

## Create a component

Components are created by applying a declarative spec. You can choose the flow that fits your workflow:

- **Interactive CLI wizard** — run `diagrid component create` with no arguments to launch a guided experience that walks you through picking a component type, entering metadata, and selecting scopes.
- **One-shot CLI** — pass flags for non-interactive scripting and CI pipelines.
- **Declarative YAML** — author a spec file and apply it with `diagrid apply`.
- **Catalyst Web UI** — the Catalyst console provides an equivalent guided experience in the browser.

```bash
# Interactive CLI wizard — prompts for type, metadata, and scopes
diagrid component create
```

```bash
# One-shot from flags
diagrid component create my-pubsub \
  --type pubsub.redis \
  --metadata redisHost=https://my-redis.example.com:6379 \
  --metadata redisPassword=my-password \
  --scopes my-app,other-app \
  --wait
```

See [`diagrid component create`](https://docs.diagrid.io/references/catalyst/cli-reference/component/create) for all flags.

```yaml
# state-store.yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: my-state
spec:
  type: state.postgresql
  version: v1
  metadata:
    - name: connectionString
      value: "postgres://user:password@host:5432/db"
    - name: tableName
      value: state
scopes:
  - my-app
```

```bash
diagrid apply -f state-store.yaml
```

See [Declarative management](https://docs.diagrid.io/operate/project-operations/declarative-management) for the full `diagrid apply` workflow, including dry-runs, directory apply, and CI/CD patterns.

:::tip Transparent secret management

Sensitive metadata fields — passwords, tokens, connection strings — are identified via the Dapr component metadata schema and transparently extracted into a Catalyst-managed secret store before the spec is persisted. Plaintext values never land in the control plane database.

See [Managing Secrets](https://docs.diagrid.io/operate/project-operations/secrets) for details and for bring-your-own secret store patterns.

:::

## Scope components to workloads

The `scopes` field on a component restricts which workloads can use it. Scoping serves three purposes:

- **Access control** — only listed workloads receive the component's binding.
- **Multi-tenancy** — different workloads can point at different infrastructure instances of the same component type.
- **Security** — isolate sensitive infrastructure (billing database, secret store) to specific workloads.

```bash
# Scope an existing component to an additional App ID
diagrid component update my-pubsub --scopes my-app,other-app,new-app --wait
```

See [`diagrid component update`](https://docs.diagrid.io/references/catalyst/cli-reference/component/update).

A component with no scope is not bound to any app and is unusable until a scope is added.

## List and inspect components

```bash
# List all components in the active project
diagrid component list

# Get details for a specific component
diagrid component get my-pubsub

# Edit a component interactively
diagrid component edit my-pubsub
```

See [`diagrid component list`](https://docs.diagrid.io/references/catalyst/cli-reference/component/list), [`diagrid component get`](https://docs.diagrid.io/references/catalyst/cli-reference/component/get), and [`diagrid component edit`](https://docs.diagrid.io/references/catalyst/cli-reference/component/edit).

## Resiliency policies

Resiliency policies apply timeout, retry, and circuit breaker behavior to operations between workloads and their bound components. Catalyst enforces these policies at the runtime level, so your app code doesn't need to implement them.

```yaml
apiVersion: dapr.io/v1alpha1
kind: Resiliency
metadata:
  name: default-resiliency
spec:
  policies:
    timeouts:
      general: 15s
    retries:
      retryForever:
        policy: exponential
        maxInterval: 15s
        maxRetries: -1
    circuitBreakers:
      simpleCB:
        maxRequests: 1
        timeout: 30s
        trip: consecutiveFailures >= 5
  targets:
    components:
      my-pubsub:
        outbound:
          retry: retryForever
          circuitBreaker: simpleCB
scopes:
  - my-app
```

Run `diagrid resiliency --help` for the full flag set.

## Subscriptions

Subscriptions are declarative pub/sub routes from a topic in a pub/sub component to an endpoint in an app. They are a separate resource type because a subscription binds three things: the pub/sub, the topic, and the target app route.

```yaml
apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: orders-subscription
spec:
  pubsubname: my-pubsub
  topic: orders
  routes:
    default: /orders
scopes:
  - my-app
```

```bash
diagrid apply -f orders-subscription.yaml
```

See [`diagrid subscription`](https://docs.diagrid.io/references/catalyst/cli-reference/subscription) for imperative management.

## HTTP endpoints

When your apps need to call an external HTTP service via Service Invocation, use an HTTPEndpoint resource to declare the URL, headers, and authentication as configuration rather than hard-coding them in your app.

```yaml
apiVersion: dapr.io/v1alpha1
kind: HTTPEndpoint
metadata:
  name: my-external-api
spec:
  baseUrl: https://api.example.com
  headers:
    - name: Authorization
      secretKeyRef:
        name: my-api-key
        key: token
scopes:
  - my-app
```

Run `diagrid httpendpoint --help` for the full flag set.

## Configuration

Dapr Configuration resources expose feature flags, tracing settings, and access-control policies to your apps. Create one and bind it to an app using the `--app-config` flag when creating or updating the app:

```bash
diagrid configuration create tracing-enabled \
  --tracing-sampling-rate 1 \
  --wait

diagrid app update my-app --app-config tracing-enabled --wait
```

See [`diagrid configuration`](https://docs.diagrid.io/references/catalyst/cli-reference/configuration) for all supported settings, including tracing, access control, and feature flags.

## Declarative management across the project

Manage the full component catalog of a project in Git with [`diagrid apply`](https://docs.diagrid.io/references/catalyst/cli-reference/apply) and `diagrid export`:

```bash
# Export all resources in the current project
diagrid export --project my-project --out-dir ./resources

# Apply a directory of resources
diagrid apply -f ./resources/ --project my-project
```

See [Declarative management](https://docs.diagrid.io/operate/project-operations/declarative-management) for the complete workflow — dry-runs, scoped API keys for CI, drift detection, and promoting resources between projects.

## What's next

- [Components reference](https://docs.diagrid.io/references/catalyst/components-reference/intro) — full catalog of component types and their metadata.
- [Managing secrets](https://docs.diagrid.io/operate/project-operations/secrets) — transparent and bring-your-own secret-store patterns.
- [Managed services](https://docs.diagrid.io/operate/project-operations/managed-services) — use Catalyst-hosted Pub/Sub, KV, and Workflow stores.
- [IDs](https://docs.diagrid.io/operate/project-operations/ids) — the workloads that components are scoped to.