Connect to External Infrastructure

To utilize an existing cloud infrastructure resource with the Catalyst APIs, you are required to create an external Connection. This allows you to take advantage of your existing databases, message brokers and 3rd party services while gaining the advantages of a common API surface. For more details on Infrastructure Connections and for a list of what services are supported in Catalyst, read Connections.

There are a number of ways to create external Connections.

Create a Connection using the Catalyst Console

The Catalyst console supports creating a connection using a step-by-step user flow.

1. Open the console and navigate to the Connections page in the left-hand menu.

2. Choose Create Connection in the top right-hand corner.

   

3. Select the Connection Type: PubSub, State or Binding.

4. Select the Connection target from the list of supported resources.

5. Assign access to desired App IDs. By default all App IDs will be able to access the Connection via supported APIs.

6. Select the Authentication Profile for connecting to the resource. Authentication Profiles will vary per Connection target.

7. Configure the Connection by providing all the required metadata fields and any optional metadata fields that you desire.

   • Use the Catalyst Connection specs for additional documentation on the supported Connection metadata and the Dapr open source Reference docs linked in the upper-left corner.
   • Optional metadata can be added into the Connection by using the + icon.

   

8. Optionally enable default resiliency policies for retries, timeouts and circuit breakers on inbound/outbound requests to/from the resource. These resiliency policies act on top of any built-in resiliency and might only make sense in one direction for some Connections types.

9. Choose Continue to review your the configuration details and then Save to create the Connection in Catalyst.

   At this point you will be redirected to the Connections list page, where you can monitor the Status of your newly created Connection. Initially your Connection will be in Processing as the infrastructure details are loaded but should change to Provisioning and Ready shortly after.

Create a Connection using the Diagrid CLI

There are multiple ways to create external infrastructure Connections in the Diagrid CLI. To install the CLI, follow the instructions here.

Use the prompt-based CLI

The Diagrid CLI supports creating external infrastructure Connections using an interactive, prompt-based experience.

1. Login to the CLI and verify your identity.

   diagrid login
   diagrid whoami

2. Open the prompt-based wizard for Connection creation. Navigate using the return, up/down arrow and escape keys.

   diagrid connection create --prompt

   

3. Select the Connection Type: PubSub, State or Binding.

4. Select the Connection target from the list of supported resources.

5. Select the Authentication Profile for connecting to the resource. Authentication Profiles will vary per Connection target.

6. Assign access to desired App IDs. By default all App IDs will be able to access the Connection via supported APIs.

7. Configure the authentication details for the Connection by providing all required metadata fields.

   • For additional documentation on the supported Connection metadata, refer to the Catalyst Connection specs.

8. Finish configuring the Connection by providing all remaining required metadata fields and any optional metadata fields that you desire.

   At this point you have created your Connection. Monitor the status by running the following command.

   diagrid connection get <connection-name>

   Initially your Connection will be in Processing as the infrastructure details are loaded but should change to Provisioning and Ready shortly after.

Use declarative Connections

Catalyst supports creating and modifying external resource Connections using a declarative YAML format. This allows you to save Connections as part of your source control system and utilize them in development toolchains.

1. Login to the CLI and verify your identity.

   diagrid login
   diagrid whoami

2. Create a declarative YAML Connection file for the external infrastructure resource that you wish to connect to. The Connection format conforms to the open-source Dapr Component specification for the respective resource with the following exceptions:

   • apiVersion:cra.diagrid.io/v1beta1
   • kind: Connection
   • The value for metadata.namespace becomes your Catalyst project name
   • App ID scoping is nested as spec.scopes

   For a complete reference of supported Catalyst Connections and associated metadata descriptions refer to Catalyst Connection specs. For example, a Connection for a Redis state store might be as follows, with additional metadata available in the Redis Connection spec.

   apiVersion: cra.diagrid.io/v1beta1
   kind: Connection
   metadata:
     name: redis-state
     namespace: <catalyst-project>
   spec:
     type: state.redis
     version: v1
     metadata:
       - name: redisHost
         value: catalyst.redis.io:6379
       - name: redisPassword
         value: <REDACTED>
       - name: enableTLS
         value: false
     scopes:
       - appid-1
       - appid-2

3. Save the YAML file and create the Connection resource in Catalyst by running the following.

   diagrid connection apply -f <connection.yaml>

4. At this point you have created your Connection. Monitor the status by running the following.

   diagrid connection get <connection-name>

   Initially your Connection will be in Processing as the infrastructure details are loaded but should change to Provisioning and Ready shortly after.

Open Source Dapr Components

Catalyst has support for importing and exporting open source Dapr components as Connection resources. Please read the Dapr Compatibility guide for additional details.