Reference - Agent configuration

15 minute read

Before you start

• Read Amplify Central AWS API Gateway connected overview
• Prepare Amplify Central
• Prepare AWS API Gateway
• Docker must be installed and you will need a basic understanding of Docker commands

Objectives

Learn how to create your Discovery Agent and Traceability Agent configuration files, then install and run your agents.

Discovery Agent

The Discovery Agent is used to discover new deployments and stage updates to existing deployments. Once they are discovered, the related APIs are published to Amplify Central so that they become available for any consumer.

The Discovery Agent only discovers published APIs where the stage has a tag(s) defined in the agent configuration file. See AWS_DISCOVERYTAGS.

There are two operating modes of the Discovery Agent, one is receiving continuous changes from AWS API Gateway and pushing to Amplify Central. The other synchronizing all APIs and then exits.

Continuous Discovery Overview

In this mode the agent will receive change events for configuration changes to AWS API Gateway resources. These events will be processed and sent to Amplify Central. This mode is also required to manage subscriptions and subscription notifications.

Synchronous Discovery Overview

In this mode the agent will read the configuration on AWS API Gateway and send all REST APIs to Amplify Central. Once it has completed this task it will exit and no additional changes will be sent to Amplify Central until the agent is executed again. This mode does not handle any subscription events.

The configuration of the AWS_QUEUENAME is not used in this mode.

Create your Discovery Agent configuration

Customizing email servers

The host, which represents the email server, can be configured with minimal setup. This section represents the email servers that have been currently tested. Please note, that all testing has been set up on port 587 signifying TLS support.

# Google/Gmail server
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST=smtp.gmail.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT=587
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_USERNAME=your GMAIL account
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PASSWORD=your GMAIL password (see note below)
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_AUTHTYPE=PLAIN

# Microsoft  Office 365 server
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST=smtp.office365.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT=587
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_USERNAME=your Office Mail account
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PASSWORD=your Office Mail password
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_AUTHTYPE=LOGIN

# Microsoft Outlook server
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST=smtp-mail.outlook.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT=587
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_USERNAME=your Outlook Mail account
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PASSWORD=your Office Mail password
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_AUTHTYPE=PLAIN

# Yahoo email server
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST=smtp.mail.yahoo.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT=587
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_USERNAME=your Yahoo Mail account
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PASSWORD=your Yahoo Mail password (see note below)
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_AUTHTYPE=PLAIN

# Amazon Simple Email Service
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST=email-smtp.<region>.amazonaws.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT=587
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_USERNAME=user access key (see note below)
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PASSWORD=user secret key (see note below)
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_AUTHTYPE=PLAIN

Note: You will be required to use an application generated password instead of the actual user email password for the following email servers. Follow the links for application generated passwords.

• Gmail - Application generated gmail password. Use this password in place of your actual password in the agent configuration password: field.
• Yahoo - Application generated yahoo password. Use this password in place of your actual password in the agent configuration password: field.
• AWS Simple email service. Create your SMTP credentials and use them in the username (ACCESS KEY) and password (SECRET KEY) of the agent configuration. You might also have to verify the email address you will use (at least the sender email address).

Subscription webhook notifications

When configured, a webhook notification will create an HTTP Post request to the URL specified.

The post request can include optional headers specified in the CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_WEBHOOK_HEADERS environment variables. Here is an example of specifying multiple headers in the environment file:

CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_WEBHOOK_HEADERS=Header=contentType,Value=application/json, Header=Elements-Formala-Instance-Id,Value=5551212, Header=Authorization,Value=authvalue

The data posted will be a JSON object with the following structure:

{
  "catalogItemId":"value",
  "catalogItemUrl":"value",
  "catalogItemName":"value",
  "action":"value",           # see below
  "email":"value",            # if applicable
  "message":"value",          # if applicable, any errors that occurred will be here
  "key":"value",              # if applicable
  "keyHeaderName":"value",    # if applicable
  "clientID":"value",         # if applicable
  "clientSecret":"value"      # if applicable
}

The action above will be one of the following:

• ACTIVE - Subscription was approved and processed properly by the agent
• FAILED_TO_SUBSCRIBE - Subscription was approved but failed processing in the agent
• UNSUBSCRIBED - Unsubscribe was processed properly by the agent
• FAILED_TO_UNSUBSCRIBE - Unsubscribe process failed in the agent

SMTP notifications

Subscription notifications with email notifications can set both the subject and the body. The body, which may be HTML, is able to substitute data from the subscription event into the email that is sent to the event initiator. Here is a sample of the template used for subscribe events:

CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_SUBJECT=Subscription Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_BODY=Subscription created for Catalog Item:  <a href= ${catalogItemUrl}> ${catalogItemName} </a> <br/>
Your API is secured using an APIKey credential:header:<b>${keyHeaderName}</b>/value:<b>${key}</b>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_OAUTH=Your API is secured using OAuth token. You can obtain your token using grant_type=client_credentials with the following client_id=<b>${clientID}</b> and client_secret=<b>${clientSecret}</b>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_APIKEYS=Your API is secured using an APIKey credential:header:<b>${keyHeaderName}</b>/value:<b>${key}</b>

The agent will fill in the appropriate data for the variables specified, ie ${catalogItemUrl}, ${keyHeaderName} and ${authtemplate} before sending the SMTP message. The variables that may be used are the keys for the JSON data sent to the webhook endpoint, see Subscription webhook notifications.

Create your Discovery Agent environment file

Create a configuration file using the above variables. See the variable descriptions for their values. Below is a sample of what the configuration file will look like.

For example:

# AWS connectivity
AWS_REGION=us-east-2
AWS_QUEUENAME=aws-apigw-discovery-us-east-2
AWS_AUTH_ACCESSKEY=<YOUR AWS ACCESS KEY HERE>
AWS_AUTH_SECRETKEY=<YOUR AWS SECRET KEY HERE>
AWS_LOGGROUP=<YOUR LOG GROUP NAME>
AWS_FILTER=tag.PushToAmplify == true
AWS_PUSHTAGS=true

#Amplify Central connectivity
# organisation config:
CENTRAL_ORGANIZATIONID=<YOUR ORGANIZATION ID>
CENTRAL_TEAM=<THE TEAM NAME>
CENTRAL_ENVIRONMENT=<NAME OF THE CENTRAL TOPOLOGY ENVIRONMENT>
CENTRAL_AUTH_CLIENTID=<SERVICE ACCOUNT NAME: DOSA_xxxxxxxxx>

CENTRAL_MODE=<publishToEnvironment | publishToEnvironmentAndCatalog>

#CENTRAL_SSL_MINVERSION=
#CENTRAL_SSL_MAXVERSION=
#CENTRAL_SSL_CIPHERSUITES=
#CENTRAL_SSL_NEXTPROTOS=
#CENTRAL_SSL_INSECURESKIPVERIFY=

LOG_LEVEL=info
LOG_OUTPUT=stdout
LOG_PATH=logs

Install and run Discovery Agent

1. Copy the private_key.pem and public_key.pem files that were originally created when you set up your Service Account to a keys directory. Make sure the directory is located on the machine being used for deployment. Note that the public_key.pem comes from Steps 3 and 4 of Prepare AWS Gateway to deploy the Discovery Agent AWS config setup.

2. Pull the latest image of the Discovery Agent:

   docker pull axway.jfrog.io/ampc-public-docker-release/agent/aws-apigw-discovery-agent:latest
   

3. Start the Discovery Agent pointing to the env_vars file and the keys directory

   • Continuous Discovery mode

     docker run --env-file ./env_vars -v <pwd>/keys:/keys  axway.jfrog.io/ampc-public-docker-release/agent/aws-apigw-discovery-agent:latest
     

     pwd relates to the local directory where the docker command is run. For Windows, the absolute path is preferred.

   • Synchronous Discovery mode

     docker run --env-file ./env_vars -v <pwd>/keys:/keys  axway.jfrog.io/ampc-public-docker-release/agent/aws-apigw-discovery-agent:latest --synchronize
     

     pwd relates to the local directory where the docker command is run. For Windows, the absolute path is preferred.

4. Run the following health check command to ensure the agent is up and running (continuous mode):

   docker inspect --format='{{json .State.Health}}' <container>
   

Traceability Agent

The Traceability Agent is used to filter the AWS CloudWatch logs that are related to discovered APIs and prepare the transaction events that are sent to Amplify platform. Each time an API is called by a consumer, an event (summary + detail) is sent to Amplify Central and is visible in API Observer.

Create your Traceability Agent configuration

Create your Traceability Agent environment file

Create a configuration file using the above variables. See the variable descriptions for their values. Below is a sample of what the configuration file will look like.

For example:

# AWS connectivity
AWS_REGION=us-east-2
AWS_QUEUENAME=aws-apigw-traceability-us-east-2
AWS_AUTH_ACCESSKEY=<YOUR AWS ACCESS KEY HERE>
AWS_AUTH_SECRETKEY=<YOUR AWS SECRET KEY HERE>

#Amplify Central connectivity
# organisation config:
CENTRAL_ORGANIZATIONID=<YOUR ORGANIZATION ID>
CENTRAL_TEAM=<THE TEAM NAME>
CENTRAL_ENVIRONMENT=<NAME OF THE CENTRAL TOPOLOGY ENVIRONMENT>
CENTRAL_AUTH_CLIENTID=<SERVICE ACCOUNT NAME: DOSA_xxxxxxxxx>

#CENTRAL_SSL_MINVERSION=
#CENTRAL_SSL_MAXVERSION=
#CENTRAL_SSL_CIPHERSUITES=
#CENTRAL_SSL_NEXTPROTOS=
#CENTRAL_SSL_INSECURESKIPVERIFY=

LOG_LEVEL=debug
LOG_OUTPUT=stdout
LOG_PATH=logs

Install and run Traceability Agent

1. Copy the private_key.pem and public_key.pem files that were originally created when you set up your Service Account to a keys directory. Make sure the directory is located on the machine being used for deployment.

2. Pull the latest image of the Traceability Agent:

   docker pull docker pull axway.jfrog.io/ampc-public-docker-release/agent/aws-apigw-discovery-agent:latest/aws-apigw-traceability-agent:latest
   

3. Start the Traceability Agent pointing to the env_vars file and the keys directory. Note that pwd relates to the local directory where the docker command is run. For Windows, the absolute path is preferred.

   docker run --env-file ./env_vars -v <pwd>/keys:/keys  axway.jfrog.io/ampc-public-docker-release/agent/aws-apigw-traceability-agent:latest
   

4. Run the following health check command to ensure the agent is up and running:

   docker inspect --format='{{json .State.Health}}' <container>
   

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.