Page Comparison

On this page, you will learn find a step-by-step guide on how to connect your AWS API Gateway to Obsidian step-by-step.

Overview of this Guide

Table of Contents

minLevel	1
maxLevel	7
outline	true
exclude	Overview of this Guide

Prerequisites

The following is required to proceedBoomi's API Control Plane.

Prerequisites

To proceed, you will need the following:

A running Obsidian instance {tenant-id}.frontend.obsidian.localinstance of Boomi´s API Control Plane
Access to the Amazon API Gateway Service with at least one API deployed in a stage
Docker to use utilize the image of our agent (that , which acts as an intermediary).
Any other container environment is also possible. Helm Charts are available here:
https://github.com/apiida/CPagent-Helm

...

Excerpt

name	Create a new Environment

Create a new Environment

...

To get started, simply open your

...

API Control Plane instance and follow the instructions below.

Add an Environment

...

Navigate to “Environments” in the menu on the left side
Click on the “Create New Environment” button in the top right corner
Choose your provider by clicking on it
Confirm by clicking on the "Next" button
Image Added

...

Fill in the form (as exemplarily shown below)

...

Add Environment Information

Complete the form below following the example below:
- In Environment Settings you will receive detailed information about the fields to be filled in.

Image Added

Confirm by clicking on the "

...

Register Environment" button

...

Image Added

Click

...

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

...

Next here to start the Connection Wizard.

You’ve completed the first step!

...

Provide the Gateway Information

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

Gateway Configuration

...

Create a new YAML file:

Code Block

language	yaml

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

...

You have two options to grant your agent access to your AWS API Gateway, depending on whether you plan to host the agent inside AWS itself or elsewhere.

Agents running outside AWS

This is the default, where you run the agent container outside of AWS, e.g. inside your local network or within another cloud provider. For the agent to be able to access the AWS API Gateway, you must provide credentials in form of Access Key and Secret Access Key.

...

Agents running inside AWS

For agents running within one of the AWS container services (e.g. ECS or EKS) and pointing to AWS API Gateway you can choose to 'Use AWS Internal Access' instead of providing explicit credentials. This eliminates the storing or transmission of gateway credentials by the agent - Hence tighter security.

In this case you must configure a Task IAM Role for your container in AWS which has the necessary permissions to access the API Gateway.
Here is the documentation from Amazon describing the process:
https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html

...

Use AWS Internal Access: Enable this if you intend to run your agent container inside AWS and want to use a Task IAM Role instead of providing accessKey and secretAccessKey.
accessKey/secretAccessKey: Id and secret access key of an AWS long-term access key for programmatic access.
region: The region in which your AWS API Gateway is hosted.
stage: The stage to which your APIs are deployed in AWS.

Info
See our Q&A below if you want to learn more about how to get these values.

Note
Currently, each AWS agent is specific to one region and one stage. If you want to manage multiple stages or regions, you will require an agent instance for each combination.

Example

Code Block

language	yaml

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

Q&A

Expand

title	How do I get my accessKey and secretAccessKey?

See this AWS link to learn how to get your access keys:
🌐 Understanding and getting your AWS credentials - AWS General Reference

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

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 Removed

Your configuration file will download automatically.
Confirm by clicking on the "Download and Next" button

You’ve completed the second step!

...

Excerpt

name	Create an Agent as Intermediary

Create an Agent as Intermediary

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:

Code Block

language	yaml

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

Code Block

language	yaml

version: '3.3' services: # AWS API Gateway Agent spring-aws-agent: image: ghcr.io/apiida/obsidian-agent:latest environment: - 'agentToken=1:751c5d80-ed45-4401-9594-8fe2f413b354' - 'backendUrl=wss://example.backend.obsidian.local/jsonRpc' - 'gateway-config=/workspace/awsConfig.yaml' volumes: - ./awsConfig.yaml:/workspace/awsConfig.yaml:rw

Image Added

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 and Next” to download your agent docker compose

Image Added

Put both files in the same folder. Then run the following commands.
- Code Block
  docker pull apiida/controlplane-agent
  - 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:

Code Block

language	powershell

docker-compose up -d

...

Excerpt

name	Check the Agent's Status

Check the Agent's Status

Head over to your

...

API Control Plane instance
Select “Environments” in the menu on the left side
- Your

...

- Agent should now be connected

...

- to API Control Plane

Image Added

Admin Portal

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

...

Gateways through Boomi´s API Control Plane.

Try it right now and discover your APIs!

💡 Tip: It is easy to add more agents!

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

...

Q&A

Expand

title	How do I get my accessKey and secretAccessKey?

See this AWS link to learn how to get your access keys:
🌐 Understanding and getting your AWS credentials - AWS General Reference

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

Version	Old Version 1	New Version Current
Changes made by	Markus Müller	Prativa Beura
Saved on	Sept 01, 2022	Jun 25, 2024

Page Comparison

Versions Compared

Key

Overview of this Guide

Prerequisites

Prerequisites

Create a new Environment

To get started, simply open your

Add an Environment

Navigate to “Environments” in the menu on the left sideClick on the “Create New Environment” button in the top right cornerChoose your provider by clicking on itConfirm by clicking on the "Next" buttonImage Added

Add Environment Information

Provide the Gateway Information

Gateway Configuration

You have two options to grant your agent access to your AWS API Gateway, depending on whether you plan to host the agent inside AWS itself or elsewhere.

Agents running outside AWS

Agents running inside AWS

Example

Q&A

Create an Agent as Intermediary

Agent Configuration

Example

Establish the connection

Start your Agent

Check the Agent's Status

Q&A

Navigate to “Environments” in the menu on the left side
Click on the “Create New Environment” button in the top right corner
Choose your provider by clicking on it
Confirm by clicking on the "Next" button
Image Added