Page Comparison

On this page you will learn how to connect your AWS API Gateway to Obsidian APIIDA´s API Control Plane step-by-step.

Overview of this Guide

...

The following is required to proceed:

• A running Obsidian instance {tenant-id}.frontend.obsidian.localinstance of APIIDA´s API Control Plane

• Access to the Amazon API Gateway Service with at least one API deployed in a stage

• Docker to use the image of our agent (that acts as an intermediary)

...

Create a new Environment

...

To get started, simply open your Obsidian API Control Plane instance and follow the instructions below.

...

• Navigate to “Environments” in the menu on the left side

• Click on the “Create New Environment” button in the top right corner

...

• Fill in the form (as exemplarily shown below)

...

• Confirm by clicking on the "Create New Register Environment" button

Request an Environment Token

• Click on the “Request Token” button

• Copy & save the token that appears above (it will be needed later)

...

Select your Provider

• Choose your provider by clicking on it

• Confirm by clicking on the "Next" button

...

You’ve completed the first step!

...

The following describes how to create the gateway configuration for an AWS API Gateway Agent.

Gateway Configuration

Create a new YAML file:

type: AWS
accessKey: {aws-access-key}
secretAccessKey: {aws-secret-access-key}
region: {aws-region}
stage: {aws-stage}

...

• accessKey/secretAccessKey: Insert your AWS access keys

• region: Insert the region that is assigned to your APIs in AWS

• stage: Insert the stage where you deployed the APIs in AWS

Example

type: AWS
accessKey: ABC123ABC123ABC123AB
secretAccessKey: ABC123ABC123ABC123ABC123ABC123ABC123ABC1
region: eu-central-1
stage: test

Q&A

Expand
title Where can I find the region assigned to my API in AWS?
Go to the API Overview in the AWS API Gateway Service The region identifier of your API can be found in the region tab (see screenshot) The region identifier is also part of your overview URL https://{region-identifier}.console.aws... Image Removed

...

• Go to the API Overview and choose Stages (from the left menu page)

  • The stages in which your API is deployed will be displayed in the second column

...

• Click on “Download” to download your configuration file

• Confirm by clicking on the "Next" button

You’ve completed the second step!

...

The following describes how to create a Docker container for the agent. It is described using a Docker compose file so that additional agents can be easily added to your docker stack later.

Agent Configuration

Create a docker-compose.yml:

version: '3.3'
services:

# AWS API Gateway Agent

  spring-aws-agent:
    image: ghcr.io/apiida/obsidian-agent:latest
    environment:
      - 'agentToken={the-token-requested-in-step-1}'
      - 'backendUrl=wss://{your-tenant-id}.backend.obsidian.local/jsonRpc'
      - 'gateway-config=/workspace/awsConfig.yaml'
    volumes:
      - {path-to-the-agent-config-created-in-step-2}:/workspace/awsConfig.yaml:rw

• agentToken: Insert the token that you’ve received in the first step

• backendUrl: Insert your tenant id into the backend URL

• volume: Add the path to your gateway configuration (the file you’ve created in the second step)

Example

...

...

• image: The docker image of the API Control Plane Agent

• container_name: You can freely choose the name of your Agent here as well as in line 3.

• environment

  • backendUrl: The agent will establish a web-socket to this URL and thereby connect to your API Control Plane.

  • gateway-config: The path inside the container to the configuration you downloaded in step 2.

• volumes

  • The outer path of the configuration file : The inner path of the configuration file

• Click on “Download” to download your agent docker compose

• Put both files in the same folder. Then run the following commands.

  • Code Block
    docker pull ghcr.io/apiida/obsidian-agent:latest

...

• • • Download the latest image of the agent.

  • Code Block
    docker compose up

    • Starts the agent. It will connect automatically.

You’ve completed the third step!

You're ready to establish the connection between Obsidian and your AWS API Gateway.

Establish the connection

Establish the connection between Obsidian and your AWS API Gateway by starting the Agent (respectively the docker container that contains the agent).

Start your Agent

For example, execute the following command in the directory where the docker compose file is located to start the docker container that contains the agent you have just configured:

docker-compose up -d

...

Check the Agent's Status

• Head over to your Obsidian API Control Plane instance

• Select “Environments” in the menu on the left side

  • Your AWS API Gateway Agent should now be connected to Obsidian

...

• • API Control Plane

...

• Click on the tile or the entry in the table to get more detailed information about the status of the connection. This can be very useful in case of an error.

You’ve completed the last step!

You can now interact with your AWS Gateway through ObsidianAPIIDA´s API Control Plane.

Try it right now and discover your APIs!

...

Repeat this guide or that of another gateway and simply add the agents to the existing Docker compose file.

...

Q&A

Expand
title Where can I find the region assigned to my API in AWS?
Go to the API Overview in the AWS API Gateway Service The region identifier of your API can be found in the region tab (see screenshot) The region identifier is also part of your overview URL https://{region-identifier}.console.aws... Image Added

Expand
title Where can I find the stage(s) in which my API is deployed?
Go to the API Overview and choose Stages (from the left menu page) The stages in which your API is deployed will be displayed in the second column Image Added