Deploy a custom API and connector

After you build a custom connector, and optionally a custom API, you deploy the connector and any custom API through pull requests to your DevHub applications-live repository. ArgoCD applies the changes. There’s no manual publishing: every API, unified or custom, is published through applications-live. The following diagram shows how a release becomes a running connector and a published API:

Prerequisites

Before you begin, make sure you have:

A released connector repository. For more information, see Overview.
A released API repository, if you use a custom API. For more information, see Create a custom API.
Write access to gc-devhub-{installation}-applications-live through the applications-live GitHub team.
The {env}-apim-rw and {env}-apim-subs-ro roles for your runtime in self-service.tfvars.

Plan your resource names

All workloads, both Backbase-managed and yours, share the same cluster and Azure installation. Prefix the name of everything you create so that each name is unique and identifiable. Release names must be unique for each deployed version and follow the pattern {name}-v{major}. Avoid tokens such as temp, poc, or environment names in release names.

A name that isn’t unique can collide with resources from other workloads in the same installation. Choose and apply your prefix before you create the first resource.

The following table lists the resources you create and an example name:

Resource	Example name	Defined in
Connector release	`yourprefix-onboarding-v1`	`runtimes/{runtime}/apps/`
API	`yourprefix-onboarding-api`	`runtimes/{runtime}/apim/apis/`
Version set	`yourprefix-onboarding-api`	`apiversionsets.values.yaml`
Backend	`yourprefix-onboarding-backend`	`backends.values.yaml`
Product	`yourprefix-onboarding-product`	`products.values.yaml`
Subscription	`yourprefix-onboarding-subscription`	`subscriptions.values.yaml`

Deploy the connector

When you release a connector repository, the build creates a container image and a Helm chart, and pushes both to your installation’s container registry. Snapshot charts use the version {version}-{sha8}. applications-live references the chart version. To deploy the connector, open a pull request that:

Adds your connector release to runtimes/{runtime}/apps/ as an ArgoCD Application, with one source for each release and the chart taken from your registry.
Adds your values under runtimes/{runtime}/values/.

After you merge the pull request, ArgoCD syncs automatically. For more information, see Configure connectors and Run. DevHub workloads run in a DevHub namespace. The default namespace is devhub-grandcentral. For a dedicated namespace, use devh-gc-<domain>. You use this namespace in the connector URL. For more information, see Deployment namespace. The URL of the deployed connector follows this pattern, and you use it as the backend URL in the next section: https://{releaseName}-{namespace}.{runtime}.{installation}.gcservices.io.

Publish the API

You configure the API in runtimes/{runtime}/apim/ of your applications-live repository. Replace YOUR_API with the artifact ID of your API repository. For a description of each field, see Azure API Management configuration. To publish the API, follow these steps:

Register the API. Create the file runtimes/{runtime}/apim/apis/YOUR_API.yaml. It’s an ArgoCD Application with two sources: your applications-live repository, and the API Helm chart from your container registry.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: YOUR_API
  namespace: argocd
spec:
  project: YOUR_ARGOCD_PROJECT
  destination:
    server: https://kubernetes.default.svc
    namespace: YOUR_NAMESPACE
  sources:
    - repoURL: git@github.com:bb-ecos-INSTALLATION/gc-devhub-INSTALLATION-applications-live.git
      targetRevision: main
      ref: apps-live
    - repoURL: YOUR_ACR/charts
      chart: YOUR_API
      targetRevision: CHART_VERSION
      helm:
        releaseName: YOUR_API-v1
        valueFiles:
          - $apps-live/runtimes/RUNTIME/apim/apis/common.apim.values.yaml
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Set CHART_VERSION to the chart version from the build of your API repository. The apimArmId value comes from common.apim.values.yaml, so you don’t set it for each API. Copy YOUR_ARGOCD_PROJECT from an existing API application in your installation. YOUR_NAMESPACE is commonly devhub-grandcentral, or devh-gc-<domain> for a dedicated namespace. For more information, see Deployment namespace.

Add the version set. Add your API to apiversionsets.values.yaml. Use the same name as metadata.name in your API application.
apiVersionSets: - name: YOUR_API

Add the backend. Add the connector backend to backends.values.yaml. The URL is the connector URL from the previous section.

backends:
  - name: YOUR_CONNECTOR_BACKEND
    url: 'https://YOUR_RELEASE-YOUR_NAMESPACE.RUNTIME.INSTALLATION.gcservices.io'
    title: "Your connector v1"

Create the product. Add the product to products.values.yaml. The API name is YOUR_API-1, which is {artifactId}-{major}. The policy routes calls for that API to your backend.

products:
  - name: YOUR_PRODUCT
    displayName: "Your product"
    approvalRequired: "false"
    policy:
      apiBackend:
        - api: YOUR_API-1
          backend: YOUR_CONNECTOR_BACKEND
      value: |
        <policies>
          <inbound>
            <base />
            <set-backend-service backend-id="YOUR_CONNECTOR_BACKEND" />
          </inbound>
          <backend><base /></backend>
          <outbound><base /></outbound>
          <on-error><base /></on-error>
        </policies>
    productApis:
      - apiName: YOUR_API-1

Create the subscription. Add the subscription to subscriptions.values.yaml. Azure API Management (APIM) generates the subscription key from it.
subscriptions: - name: YOUR_SUBSCRIPTION productScope: YOUR_PRODUCT
Open the pull request. Commit the changes and open a pull request. By default, all members of the applications-live team are reviewers. After review, merge the pull request. ArgoCD applies the changes.

Some resources depend on others. Backends and named values must exist before the policy fragments that reference them. Secrets must exist before the resources that use them. To reuse policy logic, define policy fragments in policyfragments.values.yaml under policyFragments, with a name and a policyValue. Reference a fragment from a product policy with <include-fragment fragment-id="YOUR_FRAGMENT"/>.

Choose how callers authenticate

Each subscription is scoped to one product and gives callers one key. Choose the setup that fits your callers:

Separate key for your custom connector: Create your own product and subscription, as in the preceding steps.
One key for Backbase-managed and custom connectors: Ask the Backbase implementation team. Managed products live in the Backbase-managed repository, which you can’t change.

To read subscription keys in the Azure portal, you need the {env}-apim-subs-ro role.

Understand what you can change

You control everything you create in DevHub:

Custom APIs and custom connectors.
Products and subscriptions.
Policies and policy fragments. Your policies can include fragments that are already defined.

You can’t change unified APIs or Backbase-managed connectors, and they don’t appear in your DevHub repositories. Standard customers can’t change the repoURL of an API application. Only premium customers can use custom registries to publish and deploy their own integrations. For more information, see GitHub organization and repository structure.

Verify the deployment

After ArgoCD syncs, call your API through the gateway with your subscription key in the api-key header:

curl --location 'https://api.RUNTIME.INSTALLATION.gcservices.io/YOUR_DOMAIN/YOUR_SERVICE/v1/YOUR_PATH' \
  --header 'api-key: YOUR_SUBSCRIPTION_KEY'

For more information about calling an API with a subscription key, see Request Template Connector API.

Promote to other runtimes

To promote your connector and API, repeat the same changes with the same chart versions in the next runtime folder, including the APIM entries. After review and merge, ArgoCD syncs. Don’t let a higher runtime run a later chart version than the lower runtimes. For more information, see Promote to a higher runtime.

Pro-code connectors

Connector Studio

Sync Hub

Prerequisites

Plan your resource names

Deploy the connector

Publish the API

Choose how callers authenticate

Understand what you can change

Verify the deployment

Promote to other runtimes

​Prerequisites

​Plan your resource names

​Deploy the connector

​Publish the API

​Choose how callers authenticate

​Understand what you can change

​Verify the deployment

​Promote to other runtimes

​Related topics

Prerequisites

Plan your resource names

Deploy the connector

Publish the API

Choose how callers authenticate

Understand what you can change

Verify the deployment

Promote to other runtimes

Related topics