Configure platform gateway route timeouts

In Ansible Automation Platform 2.7, all API access to platform components goes through platform gateway. Gateway-level timeout settings control how long platform gateway waits for backend services to respond before closing a connection.

Important

If you experience timeout errors when uploading container images or collections to automation hub, increase gateway route timeouts to allow more time for the upload to complete.

As all traffic now routes through platform gateway, gateway-level settings for request body size limits and connection timeouts apply to uploads that previously went directly to automation hub.

Collection uploads and container image uploads have different size characteristics and are affected by different gateway settings.

Collection upload limits
Copy link

Collections uploaded to automation hub are typically under 20 MB for public content and under 200 MB for private automation hub. These uploads are affected by the gateway request body size limit.

Platform gateway controls request body size through the GRPC_SERVER_MAX_RECEIVE_MESSAGE_LENGTH setting (default: 20 MiB, minimum: 4 MiB), which is enforced by the Envoy proxy. This default matches automation hub's 20 MB limit, so collection uploads work without additional configuration.

For collections larger than 20 MB, such as large private content, increase GRPC_SERVER_MAX_RECEIVE_MESSAGE_LENGTH by setting the environment variable to match your largest expected collection size. When increasing this value, also increase ENVOY_PER_CONNECTION_BUFFER_LIMIT_BYTES (default: 25 MiB) to remain at least 5 MiB above the request body size limit.

Note

For containerized deployments, the installer variable gateway_nginx_client_max_body_size (default: 5m) controls nginx body size limits. Since nginx sits in front of Envoy in containerized topologies, this limit is applied first. If collection uploads fail with HTTP 413 errors on containerized deployments, increase this value to at least 20m to match automation hub's default.

Container image uploads
Copy link

Container images for execution environments can exceed 4 GB. These uploads use chunked transfer encoding, so they are primarily affected by gateway route timeout settings rather than body size limits.

When to configure gateway settings
Copy link

Adjust platform gateway settings when you experience upload errors or timeouts after routing traffic through platform gateway in Ansible Automation Platform 2.7.

Symptoms requiring configuration changes
Copy link

Adjust platform gateway settings if you experience:

  • HTTP 413 Request Entity Too Large errors when uploading collections: increase GRPC_SERVER_MAX_RECEIVE_MESSAGE_LENGTH and ENVOY_PER_CONNECTION_BUFFER_LIMIT_BYTES (and gateway_nginx_client_max_body_size for containerized deployments).
  • Timeout errors during container image pushes: increase route timeout values.
  • Incomplete transfers or interrupted uploads: increase route timeout values.

Affected operations
Copy link

Expand
Operation Primary setting Size range
Collection uploads to automation hub GRPC_SERVER_MAX_RECEIVE_MESSAGE_LENGTH Up to 200 MB
Container image push (podman push, docker push) Route timeout 1-10+ GB
Execution environment uploads Route timeout 1-10+ GB
Bulk content synchronization Route timeout Varies

Configure gateway routes using the ansible.platform collection
Copy link

You can configure platform gateway route timeouts during installation or redeployment to support large file uploads to automation hub.

Before you begin
Copy link

  • The ansible.platform collection is installed.
  • You have administrator access to the deployment environment.
  • For Red Hat OpenShift Container Platform deployments, you have cluster administrator privileges.

Procedure
Copy link

  1. Create or edit your platform gateway deployment playbook.
  2. Add the route timeout configuration for your deployment type.

    For OpenShift Container Platform deployments:

    ---
- name: Set hub container registry route timeout
  ansible.platform.route:
    name: "hub container registry"
    request_timeout_seconds: 600
    idle_timeout_seconds: 600

    For containerized deployments:

    ---
- name: Set hub container registry route timeout
  ansible.platform.route:
    name: "hub container registry"
    request_timeout_seconds: 600
    idle_timeout_seconds: 600
  3. Run the playbook to apply the configuration: 
    $ ansible-playbook -i inventory gateway-deploy.yml

Results
Copy link

Upload a large container image to automation hub:

$ podman push <large-image> <gateway-host>/automation-hub/<repository>/<image>:<tag>

Confirm that the upload completes without timeout errors.

Configure gateway routes using the API
Copy link

You can adjust route timeouts on existing deployments to support large file uploads to automation hub.

Before you begin
Copy link

  • You have platform gateway administrator access.
  • You have an OAuth2 token with administrative privileges.
  • Platform gateway is deployed and operational.

Procedure
Copy link

  1. Obtain an administrative OAuth2 token: 
    $ curl -k -X POST \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"<admin-password>"}' \
  https://<gateway-host>/api/gateway/v1/tokens/
  2. Update the route timeout settings.

    For OpenShift Container Platform deployments:

    $ curl -k -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "request_timeout_seconds": 3600,
    "idle_timeout_seconds": 3600,
    "route_annotations": {
      "haproxy.router.openshift.io/timeout": "3600s"
    }
  }' \
  https://<gateway_host>/api/gateway/v1/routes/$ROUTE_ID/

    For containerized deployments:

    $ curl -k -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "request_timeout_seconds": 3600,
    "idle_timeout_seconds": 3600
  }' \
  https://<gateway_host>/api/gateway/v1/routes/$ROUTE_ID/

Results
Copy link

Verify the new timeout settings are active:

$ curl -k -X GET \
  -H "Authorization: Bearer <token>" \
  https://<gateway_host>/api/gateway/v1/routes/

Upload a large container image to automation hub and verify completion without errors.

Configure Ansible Lightspeed route timeouts
Copy link

If you use Red Hat Ansible Lightspeed and need to adjust streaming timeouts, configure the request_timeout_seconds and idle_timeout_seconds fields on the Lightspeed route.

Before you begin
Copy link

  • You have platform gateway administrator access.
  • The ansible.platform collection is installed.

About this task
Copy link

These fields replace the max_stream_duration and stream_idle_timeout global proxy settings that were available in Ansible Automation Platform 2.6.

Expand
Removed setting (2.6) Replacement field (2.7) Default
max_stream_duration request_timeout_seconds 3600
stream_idle_timeout idle_timeout_seconds 60

Procedure
Copy link

  1. Create or edit a playbook to configure the Ansible Lightspeed route timeouts: 
    ---
- name: Configure Ansible Lightspeed route timeouts
  hosts: localhost
  tasks:
    - name: Set Ansible Lightspeed streaming timeouts
      ansible.platform.route:
        name: 'lightspeed api'
        request_timeout_seconds: 3600
        idle_timeout_seconds: 60
    • request_timeout_seconds - Maximum total duration in seconds for streaming requests. Replaces the former max_stream_duration setting.
    • idle_timeout_seconds - Idle timeout in seconds. The connection closes if no data is transmitted within this period. Replaces the former stream_idle_timeout setting.
  2. Run the playbook: 
    $ ansible-playbook configure-lightspeed-timeouts.yml

Results
Copy link

Verify the updated timeout settings by querying the route through the API:

$ curl -s -k \
  -H "Authorization: Bearer <token>" \
  https://<gateway-host>/api/gateway/v1/routes/ \
  | python3 -m json.tool

Locate the Lightspeed route and confirm that effective_timeout_seconds and effective_idle_timeout_seconds reflect the expected values.

Gateway timeout recommendations
Copy link

Platform gateway route timeout values determine how long the gateway waits for requests to complete before terminating the connection.

Calculating timeout values
Copy link

If your environment requires specific settings, use the following formula to calculate a timeout value:

  1. Measure your upload bandwidth by timing a test file upload.
  2. Calculate the base timeout: timeout_seconds = (file_size_in_GB x 1024) / (bandwidth_in_MB_per_second)
  3. Add a 25% buffer to the result: recommended_timeout = timeout_seconds x 1.25
  4. Round the result up to the nearest multiple of 300 seconds (5 minutes).

Performance considerations
Copy link

Increasing timeout values might lead to the following issues:

  • Increased memory usage: The gateway maintains connection state for all active uploads.
  • Connection pool exhaustion: Many concurrent long-running uploads can consume all available connections.
  • Delayed error detection: Network issues might take longer to surface.

Best practices
Copy link

  • Set timeouts based on the largest file size you expect to upload.
  • Monitor gateway resource usage during large uploads to automation hub.
  • Schedule large uploads during off-peak hours.
  • Use multiple smaller images instead of a single large image when possible.