Environment variables applicable for Azure API Management Service

Understand the environment variables that are applicable for Azure API Management Service.

Azure API Management Service configurations let you specify Azure API Management Service configurations that are required for Azure connectivity.
Note: The following properties apply to both sprint boot and Azure Functions deployment modes, unless specified otherwise.
Properties Description
AZURE_RESOURCE_GROUP Mandatory. The container into which Azure API Management resources are deployed and managed.For details about how to find the resource group in which your Azure API Management resources are deployed, see Azure documentation.
AZURE_API_MANAGEMENT_SERVICE_NAME Mandatory. A unique name that identifies your Azure API Management instance. The resource name that you specify while creating an Azure API Management Service instance is the AZURE_API_MANAGEMENT_SERVICE_NAME. For details, see Azure documentation.
Note: AZURE_API_MANAGEMENT_SERVICE_NAME is considered as a runtime name in federated API management.
AZURE_MERTICS_SYNC_BUFFER_INTERVAL_MINUTES Optional. While retrieving the metrics using the Azure SDK, the real-time analytical (metrics) data from the Azure API Management Service may be delayed by 15 minutes or longer, depending on the current service load. For details, see Azure documentation. Therefore, set AZURE_MERTICS_SYNC_BUFFER_INTERVAL_MINUTES to more than 15 minutes. The default value is 15 minutes.If you do not specify a value for this property, the default value is considered. Specifying a value less than 15-minutes results in unnecessary calls, as the analytics data might not be available.
AZURE_METRICS_BY_REQUESTS_OR_INSIGHTS Optional. Method in which the metrics are retrieved from Azure SDK.
  • Requests
  • Insights

Requests: The agent uses the reports().listByRequest method to retrieve all requests in the specified time interval. The agent builds federated API management compatible metrics such as transactionsCount, averageLatency, and averageResponseTime, categorizing them according to the status code 2xx, 3xx, 4xx, and 5xx before sending them to federated API management.

Insights: The agent uses reports().listByTime or reports().listByApi method to retrieve the aggregated metrics data report in 15-minute intervals (15, 30, 45). However, this method does not categorize the data according to the status codes. The default value is Requests. 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 Azure API Management Service must establish the connectivity.
Note: The following properties apply to both Sprint boot and Azure Functions deployment modes, unless specified otherwise.
Properties Description
APICP_URL Mandatory. The valid URL that is used to access federated API management.

Example: https://localhost:8080
   
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 property is set to true, you must specify a value for this property.
APICP_TRUSTSTORE_TYPE Optional. Type of the truststore. If APICP_SSL_ENABLED property 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 property is set to true, you must specify a value for this property.
APICP_KEYSTORE_TYPE Optional. Type of the keystore. If APICP_SSL_ENABLED property is set to true, you must specify a value for this property.
APICP_KEY_ALIAS Optional. Alias of the key in the keystore. If APICP_SSL_ENABLED property is set to true, you must specify a value for this property.
APICP_RUNTIME_NAME Mandatory. Name of the runtime. The property defines how you want to identify the runtime in federated API management. Name must not exceed 50 characters. By default, AZURE_API_MANAGEMENT_SERVICE_NAME is considered as a runtime name.
APICP_RUNTIME_DESCRIPTION Optional. The runtime description. Description must not exceed 300 characters. Default value: Azure Runtime. If you do not specify a value for this property, the default value is considered.
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 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 automatically populates the country, state, and city values in APICP_RUNTIME_LOCATION field.
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_REGION Optional. The region name where the runtime is hosted. Example: EAST US. Region name must not exceed 50 characters. If not provided, the Azure subscription’s default region is used.
APICP_RUNTIME_TAGS Optional. The tag name of the runtime. If you do not specify a value for this property, the default value Azure 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_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

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

The Agent configurations differ between Sprint boot and Azure Functions deployment modes.

Agent configurations for Sprint boot deployment mode:

Properties Description Possible Values
APICP_HEARTBEAT_SEND_INTERVAL_SECONDS Optional. The duration in seconds in which the agent must send the health check status (heartbeats) of the Azure API Management Service 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_PUBLISH_ASSETS Optional. Enable or disable the publishing of assets (APIs) to federated API management.
  • True
  • False (Default value)
Assets are published to federated API management whenever the Agent starts, if APICP_PUBLISH_ASSETS is set to true. If you do not specify a value for this property, the default value is considered.
APICP_SEND_METRICS Optional. Enable or disable syncing of Azure analytical data (metrics) to federated API management.
  • True
  • False (Default value)
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 Azure API Management Service using Azure SDK and send metrics to federated API management. Min: 60 seconds

Max: 7200 seconds

Default: 300 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 that are made to the assets from the Azure API Management Service to federated API management by using the Azure SDK. Min: 60 seconds (Default value)

Max: 21600 seconds (6 hours).

If you do not specify a value for this property, the default value is considered.
APICP_SYNC_ASSETS Optional. Enable or disable syncing of assets (APIs) 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 . If you do not specify a value for this property, the default value is considered.
APICP_RUNTIME_CAPACITY_VALUE Optional. The approximate estimate of the throughput that a runtime can handle for the specified duration. Default value: 500000.If you do not specify a value for this property, the default value is considered.
APICP_RUNTIME_CAPACITY_UNIT Optional. Choose the unit of duration in which the capacity must be defined. Possible values are as follows:
  • 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.
APICP_LOG_LEVEL Optional. The level of logs to be captured.
  • ALL
  • ERROR
  • INFO (Default value)
  • TRACE
If you do not specify a value for this property, the default value is considered.

Agent configurations for Functions deployment mode:

Properties Description Possible Values
APICP_SYNC_HEARTBEAT_INTERVAL_CRON Mandatory. The duration in seconds in which the agent must send the health check status (heartbeats) of the Azure API Management Service to federated API management. Specify the value as a cron expression.

Min: 0 */1 * * * * (Equivalent to 60 seconds)

Max: 0 */5 * * * *(Equivalent to 900 seconds)
APICP_HEARTBEAT_SEND_INTERVAL_SECONDS Mandatory. The duration in seconds in which the agent must send the health check status (heartbeats) of the Azure API Management Service to . This value is used to display information in the federated API management UI.

Min: 15 seconds

Max: 900 seconds (15 minutes).

Default: 60 seconds

If you do not specify a value for this property, the default value is considered.

Make sure to specify a value in seconds matching the cron expression specified in APICP_SYNC_HEARTBEAT_INTERVAL_CRON

For example: If APICP_SYNC_HEARTBEAT_INTERVAL_CRON is set to 0 */1 * * * * then set APICP_HEARTBEAT_SEND_INTERVAL_SECONDS to 60 seconds
APICP_SYNC_METRICS_INTERVAL_CRON Mandatory. The duration in seconds in which the agent must retrieve the metrics from Azure API Management Service using Azure SDK and send metrics to federated API management.

Specify the value as a cron expression.

Min: 0 */5 * * * * (Equivalent to 300 seconds)

Max: 0 0 */2 * * *(Equivalent to 7200 seconds)

Note: For Microsoft Azure Functions, the recommended interval for metrics collection is 5 minutes or longer. The metrics API provided by Microsoft aggregates data in 5-minute windows and returns only the accumulated values. Therefore, even if the sync frequency is set to less than 5 minutes, the data received will still represent a 5-minute aggregation.
APICP_METRICS_SEND_INTERVAL_SECONDS Mandatory. The duration in seconds in which the agent must retrieve the metrics from Azure API Management Service using Azure SDK and send metrics to federated API management. This value is used to display information in the federated API management UI.

Min: 60 seconds

Max: 7200 seconds

Default: 300 seconds.

If you do not specify a value for this property, the default value is considered. Ensure to specify a value in seconds matching the cron expression specified in APICP_SYNC_METRICS_INTERVAL_CRON

For example: If APICP_SYNC_METRICS_INTERVAL_CRON is set to 0 */2 * * * * then set APICP_METRICS_SEND_INTERVAL_SECONDS to 120 seconds.
APICP_ASSETS_SYNC_INTERVAL_SECONDS Optional. The duration in seconds in which the Agent must synchronize the changes made to the assets from the Azure API Management Service to federated API management using the Azure SDK.

Min: 60 seconds (Default value)

Max: 21600 seconds (6 hours).

If you do not specify a value for this property, the default value is considered.
APICP_SYNC_ASSETS Optional. Enable or disable syncing of assets (APIs) 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 is considered.
APICP_RUNTIME_CAPACITY_VALUE Optional. The approximate estimate of the throughput that a runtime can handle for the specified duration. Default value: 500000

If you do not specify a value for this property, the default value is considered.
APICP_RUNTIME_CAPACITY_UNIT Optional. Choose the unit of duration in which the capacity must be defined. Possible values are as follows:
  • 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.
APICP_LOG_LEVEL Optional. The level of logs to be captured.
  • ALL
  • ERROR
  • INFO (Default value)
  • TRACE
If you do not specify a value for this property, the default value is considered.
APICP_CLIENT_ID This field is mandatory for V12.1 SaaS deployment. Client ID of the specific user.  
APICP_API_KEY This field is mandatory for V12.1 SaaS deployment. API key that is used to authenticate the tenant. For more details on how to generate API key, see Generating API Keys.  
Note: Each secret configuration property must be stored in a separate plain text file and mounted as a Docker secret. Make sure you create the following secret files in api-controlplane-agent-azure/devops/docker-compose/secrets directory with your actual credentials before you run the Azure agent. The file name must match the exact secret property name (for example, azure_subscription_id) and must not include a file extension (.txt). Ensure that the file contains only the secret value - no labels, quotes, or extra whitespace. For example, echo your-actual-azure-subscription-id > azure_subscription_id. Ensure the secret files have restricted permissions using the following command: chmod 600 *.txt.
The following are the security best practices for managing secrets:
  • Avoid committing secret files to version control.
  • Use strong, unique passwords and tokens for each environment.
  • Rotate (update) secret files regularly and restart the application afterward.
  • Restrict access — secret files should be readable only by the file owner.
  • Do not reuse production secrets in development or testing. Ensure each environment has its own set of secrets.