Skip to main content

Use Catalyst Quickstart with Azure

In this tutorial, you will select one of the API quickstart applications to try out the Catalyst APIs using Azure resources. The source code used for this tutorial can be found in the catalyst-quickstarts GitHub repository.

Select the API quickstart you would like to deploy to Azure:

pubsub call graph

Prerequisites​

RequirementInstructions
Diagrid AccountTo sign up for Catalyst, visit catalyst.diagrid.io
Diagrid CLIInstall the Diagrid CLI
GitHub AccountGet one for free
Azure AccountIf you don't have one, create an account for free
Azure CLIInstall the Azure CLI

Log in to Azure​

Sign in to Azure.

az login

Ensure you're running the latest version of the Azure CLI via the upgrade command.

az upgrade

Set environment variables​

Set environment variables which will be used in the deployment of Azure resources:

export RANDOM_VALUE="$(openssl rand -hex 3)"
export RESOURCE_GROUP="catalyst-rg"
export LOCATION="eastus"
export SERVICEBUS_NAMESPACE="catalyst-ns-$RANDOM_VALUE"
export STORAGEACCOUNT_NAME="orderstatestore$RANDOM_VALUE"
Naming resources in Azure

$RANDOM_VALUE ensures the Azure resource names are unique.

Deploy infrastructure services to Azure​

Select the API quickstart you plan to deploy to view the relevant instructions.

This tutorial will use Azure Service Bus for the Pub/Sub component target.

Deploy Resource Group​

First, create an Azure Resource group to host the resources created as part of the tutorial:

az group create --name $RESOURCE_GROUP --location $LOCATION

Deploy Azure Service Bus​

Create an Azure Service Bus Namespace.

az servicebus namespace create --resource-group $RESOURCE_GROUP --name $SERVICEBUS_NAMESPACE --location $LOCATION  --sku Standard

Create a topic in the Service Bus Namespace which will provide a one-to-many form of communication via the publish and subscribe pattern.

az servicebus topic create --name orders --namespace-name $SERVICEBUS_NAMESPACE --resource-group $RESOURCE_GROUP

Retrieve the Service Bus connection string and store in an environment variable. This credential will be used by the Diagrid Pub/Sub API to connect to the topic created above.

export SB_CONNECTION_STRING=`az servicebus namespace authorization-rule keys list --resource-group $RESOURCE_GROUP --namespace-name $SERVICEBUS_NAMESPACE --name RootManageSharedAccessKey --query primaryConnectionString -o tsv`
Confirm value set
echo $SB_CONNECTION_STRING

Prepare Diagrid Catalyst resources​

Log in​

Authenticate to your Diagrid Catalyst organization using the following command:

diagrid login

Confirm your login was successful:

diagrid whoami

Create project​

If you do not have an existing project available within your organization, create a new Catalyst project.

diagrid project create catalyst-project -w

To ensure this project is set as the default project in the Diagrid CLI, run:

diagrid project use catalyst-project

Retrieve the HTTP and gRPC endpoints for your Catalyst project. These endpoints will be used to make requests to Catalyst from the quickstart application.

export DAPR_HTTP_ENDPOINT=$(diagrid project get -o json | jq -r '.status.endpoints.http.url')
export DAPR_GRPC_ENDPOINT=$(diagrid project get -o json | jq -r '.status.endpoints.grpc.url')
Confirm value set
echo $DAPR_HTTP_ENDPOINT && echo $DAPR_GRPC_ENDPOINT

Create App IDs​

In Catalyst, each application is represented via a corresponding remote identity, known as an App ID. An App ID functions as the single point of contact for all interactions between a specific application and the Catalyst APIs.

Create two App IDs: one for the publishing app and one for the subscribing app.

diagrid appid create publisher && diagrid appid create subscriber

cli appid output

Retrieve the API token for the publisher App ID. App ID API tokens are used to authenticate API requests to Catalyst.

export PUBLISHER_API_TOKEN=$(diagrid appid get publisher -o json  | jq -r '.status.apiToken')
Confirm value set
echo $PUBLISHER_API_TOKEN

Onboard Azure infrastructure to Catalyst​

In order to use Azure Service Bus with the Pub/Sub API, you will to represent that resource in Catalyst via a Pub/Sub Component. The component contains the authentication information needed by Catalyst to securely access the Azure resource.

Create pub/sub component​

There are several ways to create components as described in Connect to external infrastructure. In this tutorial, we will use the non-prompt based CLI experience.

Create the Azure Service Bus Pub/Sub Component:

 diagrid component create az-pubsub --type pubsub.azure.servicebus.topics --metadata connectionString=$SB_CONNECTION_STRING --scopes publisher,subscriber
Confirm resource created
diagrid component get az-pubsub

azpubsub cli output

Create topic subscription​

To configure the subscriber app to receive messages published by the publisher app through the Pub/Sub API, create a topic subscription targeting the az-pubsub component with the following details:

  • Subscription name: az-subscription
  • Target Pub/Sub component: az-pubsub
  • Topic on which to listen for messages: orders
  • Default route on the subscriber app for message delivery: /neworder
  • Subscribing App IDs (scopes): subscriber
diagrid subscription create az-subscription --component az-pubsub --topic orders --route /neworder --scopes subscriber
Confirm resource created
diagrid subscription get az-subscription

azpubsub cli output

Deploy containerized quickstart applications to Azure​

This tutorial uses the quickstart apps available in the catalyst-quickstarts GitHub repository. These applications have been containerized and pushed to a public registry.

For the Pub/Sub quickstart, you will deploy two services:

  • publisher app which makes requests to the Catalyst Publish API
  • subscriber app which subscribes to and receives the messages published by the publisher app through Catalyst

To make API requests to Catalyst, the publisher application uses the OSS Dapr SDKs. Environment variables will be configured to enable the Dapr Client to connect to Catalyst instead of a locally-running Dapr sidecar.

Learn more about using the Dapr SDKs to access Catalyst APIs here.

Run the below command to specify a language for the quickstart:

export LANGUAGE=python

Deploy publisher application​

Select the hosting platform where you want the publisher application to run.

Ensure you have the necessary extensions installed and providers registered for working with Azure Container Apps (ACA).

az extension add --name containerapp --upgrade --allow-preview true
az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

Deploy the publisher application to ACA. This command will:

  • Deploy the sample application in the language of your choice to an ACA environment
  • Configure the environment variables required for the application to make Catalyst API calls
  • Expose the container app on a publically-accessible endpoint
az containerapp up \
--name publisher \
--resource-group $RESOURCE_GROUP \
--ingress external --target-port 5001 \
--image 'public.ecr.aws/diagrid/pubsub-'${LANGUAGE}'-publisher-qs:latest' \
--env-vars DAPR_HTTP_ENDPOINT="$DAPR_HTTP_ENDPOINT" DAPR_GRPC_ENDPOINT="$DAPR_GRPC_ENDPOINT" DAPR_API_TOKEN="$PUBLISHER_API_TOKEN" PUBSUB_NAME="az-pubsub"

Retrieve the application FQDN for the publisher application.

export PUBLISHER_APP_ENDPOINT=https://`az containerapp show --name publisher --resource-group $RESOURCE_GROUP | jq -r .properties.configuration.ingress.fqdn`
Confirm value set
echo $PUBLISHER_APP_ENDPOINT

Deploy subscriber application​

Select the hosting platform where you want the subscriber application to run.

Ensure you have the necessary extensions installed and providers registered for working with Azure Container Apps (ACA).

az extension add --name containerapp --upgrade --allow-preview true
az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

Deploy the subscriber application to ACA. This command will:

  • Deploy the sample application in the language of your choice to an ACA environment
  • Expose the container app on a publically-accessible endpoint
az containerapp up \
--name subscriber \
--resource-group $RESOURCE_GROUP \
--ingress external --target-port 5002 \
--image 'public.ecr.aws/diagrid/pubsub-'${LANGUAGE}'-subscriber-qs:latest' \
--env-vars PUBSUB_NAME="az-pubsub"

Retrieve the application FQDN for the subscriber application.

export SUBSCRIBER_APP_ENDPOINT=https://`az containerapp show --name subscriber --resource-group $RESOURCE_GROUP | jq -r .properties.configuration.ingress.fqdn`
Confirm value set
echo $SUBSCRIBER_APP_ENDPOINT

Update the subscriber App ID with an app endpoint​

To ensure incoming App ID requests and events can be forwarded to the subscriber application, update the subscriber App ID with the subscriber application endpoint and wait for the operation to complete.

diagrid appid update subscriber --app-endpoint $SUBSCRIBER_APP_ENDPOINT -w

Interact with the Catalyst APIs​

Use this command to kick off API calls from the publisher application which in turn uses the Catalyst Publish API.

curl -i -X POST $PUBLISHER_APP_ENDPOINT/order  -H "Content-Type: application/json" -d '{"orderId":1}'

Check API Logs​

Navigate to the Catalyst console to confirm the request was successful using the API Logs. You should see two requests:

  • An inbound request from the publisher app using the publisher App ID API token to publish the order message
  • An outbound request from the subscriber App ID to deliver the message to the configured Azure app endpoint

pubsub api logs subscriber api logs

Clean up resources​

You can use these commands to clean up the Azure and Catalyst resources you created once you are done using them.

Delete Azure Resources​

az group delete --name $RESOURCE_GROUP

Delete Catalyst resources​

diagrid appid delete publisher 
diagrid appid delete subscriber
diagrid component delete az-pubsub

If you want to delete the entire Catalyst project, including the managed infrastructure resources, run the diagrid project delete command.

diagrid project delete catalyst-project