Deploying the AWS Agent in Docker

Deploy the AWS Agent as a stand alone application in Docker by downloading the AWS agent image.

Before you begin

Make sure that you have:
  • Started the Docker client.
  • Federated API management Version 11.1.7.
  • Verified if Amazon API Gateway and federated API management for which you want to establish connectivity using the Agent are up and running.
  • Created an IAM user in AWS with the following roles assigned:
    • AmazonAPIGatewayAdministrator
    • AWSCloudTrail_ReadOnlyAccess
    • CloudWatchReadOnlyAccess

Download and load the AWS agent Docker image

  1. Click Download resources.
  2. Download docker image corresponding to the AWS API Gateway standalone container agent (amd64) or AWS API Gateway standalone container agent (arm64) component based on your system architecture.
  3. Load the Docker image from a tar file using the following command:

    docker load -i <filename.tar>

Deploy the AWS agent Docker image

  1. Configure the below set of properties to establish connection between Amazon API Gateway and federated API management.

    Unzip the docker image and run the following commands:

    cd devops

    cd docker-compose

    .env and docker-compose.yml file contains properties related to Amazon API Gateway configurations, Agent configurations, Runtime configurations, and federated API management configurations.

    Note: To securely provide sensitive information like passwords in Docker or Kubernetes deployments, use Docker secrets or Kubernetes secrets. Deploy the Docker image accordingly to utilize these secrets for secure password management.
    Amazon API Gateway configurations let you specify Amazon API Gateway configurations required for AWS connectivity.
    Properties Description
    AWS_AGENT_IMAGE Mandatory. Docker Image name.

    This property is not applicable for AWS Lambda deployment
    AWS_REGION Mandatory. The region name in which the Amazon API Gateway service is hosted.

    This property is not applicable for AWS Lambda deployment. Ensure to create an AWS Lambda function in the same region where Amazon API Gateway is hosted.
    AWS_STAGE Mandatory. Stage (Runtime) name in Amazon API Gateway.
    AWS_ACCESS_KEY_ID Mandatory. Access key of the IAM user. Use the property only if you have specified the ENV_VARIABLE as AWS_CREDENTIALS_PROVIDER. For details about various credential providers supported by the Agent SDK, see Authentication.

    This property is not applicable for AWS Lambda deployment.
    AWS_SECRET_ACCESS_KEY Mandatory. Secret key of the IAM user. Use the property only if you have specified the ENV_VARIABLE as AWS_CREDENTIALS_PROVIDER. For details about various credential providers supported by the Agent SDK, see Authentication.

    This property is not applicable for AWS Lambda deployment.
    AWS_METRICS_BY_DATA_OR_STATISTICS Optional. Method in which the metrics are retrieved from CloudWatch. Values:
    • Data
    • Statistics
    The default value is Statistics. If you do not specify a value for this property, the default value is considered.
    AWS_METRICS_SYNC_BUFFER_INTERVAL_SECONDS Optional. By default, Amazon API Gateway metric data is automatically sent to Amazon CloudWatch in one-minute interval. That is, most Amazon API Gateway metrics will be available in Amazon CloudWatch within 1 minute of the original data point. But to ensure proper metrics sync, set CloudWatch buffer time interval as more than 600 seconds (10 minutes).The default value is 600 seconds. If you do not specify a value for this property, the default value is considered.
    AWS_ASSETS_SYNC_BUFFER_INTERVAL_SECONDS Mandatory. CloudTrail typically delivers Amazon API Gateway management events within about 5 minutes of the API call being made. This is the standard delivery time for CloudTrail events.Therefore, set CloudTrail event time interval as more than 300 seconds (5 minutes).The default value is 300 seconds. If you do not specify a value for this property, the default value is considered.

    Agent configurations let you specify the agent configurations such as heart beat interval, assets sync interval, metrics sync interval, and so on.

    Properties Description Possible Values
    APICP_PUBLISH_ASSETS Optional. Enable or disable the publishing of assets to federated API management.
    • true
    • false (Default value)
    Assets are published to federated API managementwhenever the Agent starts, provided that publishAssets is set to true. If you do not specify a value for this property, the default value, false is considered.
    APICP_SYNC_ASSETS Optional. Enable or disable syncing of assets to federated API management.
    • true
    • false (Default value)
    Assets are synchronized periodically according to the configured synchronization values. Within each synchronization interval, only the assets that are newly created, updated, or deleted are synchronized with federated API management. If you do not specify a value for this property, the default value, false is considered.
    APICP_SEND_METRICS Optional. Enable or disable sending API metrics to federated API management.
    • true
    • false (Default value)
    If you do not specify a value for this property, the default value, false is considered.
    APICP_HEARTBEAT_SEND_INTERVAL_SECONDS Optional. The duration in seconds in which the Agent must send the health check status to federated API management. Min: 15 seconds Max: 900 seconds (5 minutes).Default: 60 seconds. If you do not specify a value for this property, the default value is considered.
    APICP_ASSETS_SYNC_INTERVAL_SECONDS Optional. The duration in seconds in which the Agent must synchronize the changes made to the assets from the Amazon CloudTrail to federated API management. Min:* 60 seconds*Max: 21600 seconds (6 hours).Default: 300 seconds. If you do not specify a value for this property, the default value is considered.
    APICP_METRICS_SEND_INTERVAL_SECONDS Optional. The duration in seconds in which the Agent must retrieve the metrics from Amazon CloudWatch and send metrics to federated API management. Supported metric synchronization values:
    • 60 seconds (1 minute)(Default value)
    • 300 seconds (5 minutes)
    • 600 seconds (10 minutes)
    • 1800 seconds (30 minutes)
    • 3600 seconds (60 minutes)
    • 7200 seconds (120 minutes)
    If you do not specify a value for this property in Spring boot or AWS Functions, the default value, 900 seconds is considered. If you do not specify a value for this property, the default value is considered.

    Runtime configurations lets you specify the metadata of AWS Gateway that you want to administer from the federated API management such as runtime name, description, tags, and so on.

    Properties Description
    APICP_RUNTIME_NAME Mandatory. The runtime name. This property defines how you want to identify the runtime in federated API management. Name must not exceed 50 characters. When the runtime gets registered with federated API management for the first time, the current implementation generates the runtime ID in the format <AWS_account_ID><AWS_region><AWS_stage>. As a result, changing the runtime name does not alter the runtime ID. Even if the runtime name is changed between agent restarts, a new runtime does not get created in federated API management. Instead, the runtime name gets updated for the existing runtime.
    APICP_RUNTIME_DESCRIPTION Optional. The runtime description. Description must not exceed 300 characters. Default value: AWS Runtime. If you do not specify a value for this property, the default value is considered.
    APICP_RUNTIME_REGION Optional. The region name where the runtime is hosted. Example: EAST US Region name must not exceed 50 characters.
    APICP_RUNTIME_LOCATION Optional. Location where the runtime is deployed. Specify the location in the Country|State|City format.
    Note: If both APICP_RUNTIME_LOCATION and the individual fields (APICP_RUNTIME_COUNTRY, APICP_RUNTIME_STATE, and APICP_RUNTIME_CITY) are provided, the value in APICP_RUNTIME_LOCATION takes precedence.
    APICP_RUNTIME_COUNTRY Optional. Country where the runtime is deployed.
    APICP_RUNTIME_STATE Optional. State where the runtime is deployed.
    APICP_RUNTIME_CITY Optional. City where the runtime is deployed. If the city name is unique and the country and state fields are not specified, federated API management automatically populates the country and state values.
    APICP_RUNTIME_TAGS Optional. The tag name of the runtime. Default: AWS If you do not specify a value for this property, the default value is considered. Tags are used to organize and categorize the runtimes. Multiple tags can be specified by adding comma. Example: test, local, devTags must not exceed 50 characters. It must not contain whitespaces and the number of tags must not exceed 100.
    APICP_RUNTIME_CAPACITY_VALUE Optional. The number of transaction calls that a runtime can process for the specified duration. You can configure the capacity value with any non-negative integer. Default value: 500000
    APICP_RUNTIME_CAPACITY_UNIT Optional. You can configure the capacity value with any non-negative integer and for any duration which can be in the following units:
    • PER_SECOND
    • PER_MINUTE
    • PER_HOUR
    • PER_DAY
    • PER_WEEK
    • PER_MONTH
    • PER_YEAR (Default value)
    If you do not specify a value for this property, the default value is considered.

    Federated API management configurations let you specify federated API management details to which Amazon API Gateway must establish the connectivity.

    Properties Description
    APICP_URL Mandatory. The valid URL that is used to access federated API management.
    APICP_USERNAME Mandatory. User name that is used to log in to federated API management.
    APICP_PASSWORD Mandatory. Password of the corresponding user name, which is used for logging into the federated API management through basic authentication.
    APICP_SSL_ENABLED Optional. The SSL certification of federated API management. Possible values: true or false
    APICP_TRUSTSTORE_PATH Optional. Location of the truststore file. If APICP_SSL_ENABLED is set to true, you must specify a value for this property.
    APICP_TRUSTSTORE_PASSWORD Optional. Password to access the truststore file. If APICP_SSL_ENABLED is set to true, you must specify a value for this property.
    APICP_TRUSTSTORE_TYPE Optional. Type of the truststore. If APICP_SSL_ENABLED is set to true, you must specify a value for this property.
    APICP_KEYSTORE_PATH Optional. Location of the keystore file. If APICP_SSL_ENABLED is set to true, you must specify a value for this property.
    APICP_KEYSTORE_PASSWORD Optional. Password to access the keystore file. If APICP_SSL_ENABLED is set to true, you must specify a value for this property.
    APICP_KEYSTORE_TYPE Optional. Type of the keystore. If APICP_SSL_ENABLED is set to true, you must specify a value for this property.
    APICP_KEY_ALIAS Optional. Alias of key in the keystore. If APICP_SSL_ENABLED is set to true, you must specify a value for this property.
    APICP_KEY_PASSWORD Optional. Password of key in the keystore. If APICP_SSL_ENABLED is set to true, you must specify a value for this property.
    APICP_HTTP_CONNECTION_TIMEOUT Optional. The duration in seconds in which the agent must establish the initial connection with federated API management. Default: 10 seconds.
    APICP_HTTP_READ_TIMEOUT Optional. The duration in seconds in which the agent fails to receive data over an established HTTP connection. Default: 10 seconds.
    APICP_HTTP_MAX_CONNECTION Optional. Defines the maximum number of simultaneous connections the agent can establish with federated API management. Default: 5.
    APICP_HTTP_MAX_RETRIES_COUNT Optional. Defines the maximum number of times an operation will be automatically retried after an initial connection failure. Default: 0.
    APICP_HTTP_RETRY_INTERVAL Optional. Specifies the number of seconds the agent waits before attempting to reconnect to the federated API management after a failed connection. Default: 5 seconds
  2. Run the following command:
    docker-compose up -d

    AWS agent application starts.

  3. Verify if Amazon API Gateway(runtime) is registered with the federated API management and if the APIs and metrics are published and synchronized with federated API management respectively.
    1. Open the federated API management application.
    2. On the Catalog page, click the Runtimes.
    3. Check if the runtime is registered with federated API management by verifying if the AZURE_API_MANAGEMENT_SERVICE_NAME (specified in the .env file) is listed. If the runtime is listed, it indicates that the runtime is successfully registered with the federated API management.

    4. Check if the runtime's health status is sent to federated API management by verifying the status of that corresponding runtime in the Status column. The status appears green only if the runtime is up and the heartbeats (status) are received successfully by federated API management.

    5. Check if the APIs are published from the runtime to federated API management by selecting Details from Action menu of the corresponding runtime for which, you want to verify if its APIs are published to federated API management.

    6. Click Relations tab.

      A list of all the APIs associated with the runtime appears. You can also view the runtimes and its associated APIs in the APIs tab of the Catalog page.

    7. Check if the API metrics are synchronized from the runtime to federated API management by clicking the monitor icon under the Action column corresponding to the runtime for which, you want to verify if the metrics are published to federated API management.
    8. Click Insights tab.

      The Runtime-specific monitor page renders the metrics of that runtime pertaining to a specified time interval. It lists the metrics such as Transactions, Error rate, Availability, Response time, and so on. For details, see Monitoring performance of runtimes in federated API management.