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 and later.
  • 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_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.

    Use the Data metrics synchronization method when the number of datapoints exceeds 1440 to ensure successful metric recovery during runtime re-registration. When the Statistics method is used and the datapoint limit is exceeded, failures can occur during metrics recovery.

    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 management whenever 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 .
    • 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 . 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 . 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 . 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. If you provide a value for this property, make sure that all three segments Country, State, and City are specified 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 the individual fields (APICP_RUNTIME_COUNTRY, APICP_RUNTIME_STATE, and APICP_RUNTIME_CITY) takes precedence.
    • If you specify only a unique city name in APICP_RUNTIME_LOCATION field and have not specified the country or state, federated API management UI automatically populates the country and state.
    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.
    APICP_RUNTIME_TAGS Optional. The tag name of the runtime. If you do not specify a value for this property, the default value AWS is considered. Tags are used to organize and categorize the runtimes. Multiple tags can be specified by adding comma. Example: test, local, Dev. each tag must not exceed 50 characters. It must not contain white spaces. The total 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_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_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_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_HTTP_CONNECTION_TIMEOUT Optional. The duration in seconds in which the agent must establish a connection with federated API management. Specifies the maximum amount of time the agent will wait while attempting to establish a connection with federated API management. If the connection is not successfully established within this time frame, connection timeout error will occur. Default: 10 seconds.
    APICP_HTTP_READ_TIMEOUT Optional. Defines the maximum duration the agent will wait to receive data after a connection has already been established. If the agent does not receive any response within this time window, the request will fail with a read timeout error. Default: 10 seconds.
    APICP_HTTP_MAX_CONNECTION Optional. Specifies the maximum number of simultaneous HTTP connections that can be established with federated API management API management. Default: 5.
    APICP_HTTP_MAX_RETRIES_COUNT Optional. Defines how many times the system will retry when an HTTP request fails. Default: 0.
    APICP_HTTP_RETRY_INTERVAL Optional. Specifies the amount of time to wait between retry attempts when an HTTP request fails. Default: 5 seconds
    APICP_CLIENT_ID This field is mandatory. Client ID of the specific user. The Client ID is displayed when you generate the API key.
    APICP_API_KEY This field is mandatory. API key that is used to authenticate the tenant. For more details on how to generate API key, see Generating API Keys.
  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.