Deploy connectors and supergraph independently

Introduction

By default, the CLI command to build the supergraph, i.e. ddn supergraph build create, also builds the connectors required by the supergraph for convenience. Though in certain cases, you might want to do these steps independently, e.g. when the connectors are self-hosted and not deployed on Hasura DDN.

In this recipe, you'll learn how to manage independent deployments for your connectors and the supergraph.

Prerequisites

Before continuing, ensure you have:

• A local Hasura DDN project.

Recipe

Basics

The supergraph interacts with a connector via the DataConnectorLink metadata object which contains the NDC schema of the connector along with the URLs where the connector is running.

Hence, to independently manage the connector and supergraph deployments, we need to ensure that the corresponding DataConnectorLink object is kept in sync with the connector.

Step 1. Build the connector

Build and deploy your connector and note the:

• Read url, say <deployed-connector-read-url>
• Write url, say <deployed-connector-write-url>
• Authorization header, say Bearer <deployed-connector-token>

For example, to build the connector on DDN:

Build connector on DDN using config at <subgraph-name>/connector/<connector-name>/connector.yaml

ddn connector build create --connector <subgraph-name>/connector/<connector-name>/connector.yaml \
  --env-file .env.cloud \
  --project <project-name>

info

The --project and --env-file flags can be skipped if the keys project and cloudEnvFile are set in the context.

Step 2. Update connector URLs and Auth header in the data connector link

Update the environment variables that correspond to the connector read, write URLs and the Authorization header in the data connector link:

For example: <subgraph-name>/metadata/<connector-link-name>.hml

kind: DataConnectorLink
version: v1
definition:
  name: <connector-link-name>
  url:
    readWriteUrls:
      read:
        valueFromEnv: <CONNECTOR>_READ_URL
      write:
        valueFromEnv: <CONNECTOR>_WRITE_URL
  headers:
    Authorization:
      valueFromEnv: <CONNECTOR>_AUTHORIZATION_HEADER
  schema:
    ...

Update the environment variables in the corresponding env file:

For example: .env.cloud

...
<CONNECTOR>_READ_URL="<deployed-connector-read-url>"
<CONNECTOR>_WRITE_URL="<deployed-connector-write-url>"
<CONNECTOR>_AUTHORIZATION_HEADER="Bearer <deployed-connector-token>"
...

Step 3. Build the supergraph without connectors

Build the supergraph to get a supergraph build using the connector deployed above:

Create supergraph build on DDN without building the related connectors:

ddn supergraph build create --no-build-connectors \
  --supergraph supergraph.yaml \
  --env-file .env.cloud \
  --project <project-name>

info

The --project, --supergraph and --env-file flags can be skipped if the keys project, supergraph and cloudEnvFile are set in the context.

Step 4. (Optional) Add a custom script to build the supergraph

You can add the above command as a custom script to avoid having to pass the --no-build-connectors flag each time.

For example, you can update your context config to the following:

<project-root>/.hasura/context.yaml:

kind: Context
version: v3
definition:
  current: default
  contexts:
    default: ...
  scripts:
    docker-start:
      bash: HASURA_DDN_PAT=$(ddn auth print-pat) docker compose --env-file .env up --build --pull always -d
      powershell: $Env:HASURA_DDN_PAT = (ddn auth print-pat); docker compose --env-file .env up --build --pull always -d
    build-supergraph:
      bash: ddn supergraph build create --no-build-connectors --supergraph supergraph.yaml --env-file .env.cloud --project <project-name>
      powershell: ddn supergraph build create --no-build-connectors --supergraph supergraph.yaml --env-file .env.cloud --project <project-name>

Now you can run the following command to build the supergraph:

ddn run build-supergraph

info

The --project, --supergraph and --env-file flags can be skipped if the keys project, supergraph and cloudEnvFile are set in the context.

Learn more

• Project configuration