Let’s look at a sample scenario through which you can deploy the AWS Agent as a spring boot application in Docker using Visual Studio Code editor. To deploy the AWS Agent in AWS Lambda, see How to deploy the AWS Agent in AWS Lambda?
Note: This procedure explains how to deploy the AWS agent as a stand-alone application, unless specified otherwise.
Ensure that you have:
- Built the Gradle project and the application-version-SNAPSHOT Jar is created at application / build / libs
For details about how to build the Jars, see How to build? - Started the Docker client.
- API Control Plane, version 11.0.3
- Verified if Amazon API Gateway and API Control Plane for which you want to establish connectivity using the Agent are up and running.
- Created the Runtime Type in API Control Plane to represent Amazon API Gateway. For details, see How to create the runtime type?
- Created an IAM user in AWS with the following roles assigned:
- AmazonAPIGatewayAdministrator
- AWSCloudTrail_ReadOnlyAccess
- CloudWatchReadOnlyAccess
To build a Docker image
-
Go to webmethods-api-control-plane-agent-aws\application using the following command in the Visual Studio Terminal:
cd application -
Run the following command to build the Docker image:
docker build . --tag=<image-name>For example: docker build . --tag=aws-agent-appln
Verify if aws-agent-appln image is listed in the docker client or run the following command to verify if the image is listed in the docker images:
docker images
Let’s look at a sample scenario through which you can run the AWS agent as a spring boot application in Docker using Visual Studio Code editor.
To run the Spring boot application in Docker
-
Configure the below set of properties to establish connection between AWS API Gateway and API Control Plane.
Go to webmethods-api-control-plane-agent-aws\devops\docker-compose using the following commands in the Visual Studio Terminal:
cd devopscd docker-compose
.env and docker-compose.yml file contains properties related to Amazon API Gateway configurations, Agent configurations, Runtime configurations, and API Control Plane 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:
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 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 API Control Plane. |
Assets are published to API Control Plane 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 API Control Plane. |
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 API Control Plane. 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 API Control Plane. |
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 API Control Plane. | 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 API Control Plane. | 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 API Control Plane. | Supported metric synchronization values:
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 Amazon Gateway that you want to administer from the API Control Plane 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 API Control Plane. Name must not exceed 50 characters. When the runtime gets registered with API Control Plane 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 API Control Plane. 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 | Mandatory. The region name where the runtime is hosted. Example: EAST US Region name must not exceed 50 characters. |
| APICP_RUNTIME_LOCATION | Optional. The location where the runtime is deployed. Example: DENVER Location name can not be empty and must not exceed 50 characters. |
| 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, dev Tags 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:
If you do not specify a value for this property, the default value is considered. |
| APICP_RUNTIME_TYPE_ID | Mandatory. The Id of the runtime type. Pre-defined types: WEBMETHODS_DEVELOPER_PORTAL, WEBMETHODS_API_GATEWAY Ensure to verify if the runtime type exists in API Control Plane. If it does not exist, use the Runtime Type Management Service REST API to add the runtime type. For details, see How to create the runtime type? |
API Control Plane configurations let you specify API Control Plane details to which Amazon API Gateway must establish the connectivity.
| Properties | Description |
|---|---|
| APICP_URL | Mandatory. The valid URL that is used to access API Control Plane. |
| APICP_USERNAME | Mandatory. User name that is used to log in to API Control Plane. |
| APICP_PASSWORD | Mandatory. Password of the corresponding user name, which is used for logging into the API Control Plane through basic authentication. |
| APICP_SSL_ENABLED | Optional. The SSL certification of API Control Plane. 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. |
-
Run the following command:
docker-compose up -dThe output must be as follows:
The AWS agent application starts.
-
Verify if AWS API Gateway(runtime) is registered with the API Control Plane and if the APIs and metrics are published and synchronized with API Control Plane respectively.
- Open the API Control Plane application.
- Click Catalog > Runtimes tab.
- Check if the runtime is registered with API Control Plane by verifying if the APICP_RUNTIME_NAME (specified in the .env file) is listed.
If the runtime is listed, it indicates that the runtime is successfully registered with the API Control Plane. - Check if the runtime's health status is sent to API Control Plane 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 API Control Plane. - Check if the APIs are published from the runtime to API Control Plane by clicking Action menu > Details of the corresponding runtime for which, you want to verify if its APIs are published to API Control Plane.
- 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 Catalog > APIs tab. - Check if the API metrics are synchronized from the runtime to API Control Plane by clicking the icon under the Action column corresponding to the runtime for which, you want to verify if the metrics are published to API Control Plane.
- 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 Runtime section under Catalog in API Control Plane documentation, https://docs.webmethods.io/#api-management-saas