On this page you will learn how to connect your AWS API Gateway to Obsidian step-by-step.
Overview of this Guide
Prerequisites
The following is required to proceed:
A running Obsidian instance
{tenant-id}.frontend.obsidian.local
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 in Obsidian
To get started, simply open your Obsidian instance and follow the instructions below.
Add an Environment for AWS
Navigate to “Environments” in the menu on the left side
Click on the “Create New Environment” button
Fill in the form (as exemplarily shown below)
Confirm by clicking on the "Create New Environment" button
Request an Environment Token
Click on the “Request Token” button
Copy & save the token that appears above (it will be needed later)
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:
type: AWS accessKey: {aws-access-key} secretAccessKey: {aws-secret-access-key} region: {aws-region} stage: {aws-stage}
accessKey
/secretAccessKey
: Insert your AWS access keysregion
: Insert the region that is assigned to your APIs in AWSstage
: Insert the stage where you deployed the APIs in AWS
See our Q&A below if you want to learn more about how to get these values.
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
type: AWS accessKey: ABC123ABC123ABC123AB secretAccessKey: ABC123ABC123ABC123ABC123ABC123ABC123ABC1 region: eu-central-1 stage: test
Q&A
You’ve completed the second step!
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:
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 stepbackendUrl
: Insert your tenant id into the backend URLvolume
: Add the path to your gateway configuration (the file you’ve created in the second step)
Example
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
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 instance
Select “Environments” in the menu on the left side
Your AWS API Gateway should now be connected to Obsidian
You’ve completed the last step!
You can now interact with your AWS Gateway through Obsidian. 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.