DocumentationAEMAEM TutorialsAEM as a Cloud Service Tutorials

Flexible port egress

Last update: Mon Nov 18 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Intermediate
  • Developer

Learn how to set up and use flexible port egress to support external connections from AEM as a Cloud Service to external services.

What is Flexible port egress?

Flexible port egress allows for custom, specific port forwarding rules to be attached to AEM as a Cloud Service, allowing connections from AEM to external services to be made.

A Cloud Manager Program can only have a single network infrastructure type. Ensure that flexible port egress is the most appropriate type of network infrastructure for your AEM as a Cloud Service before executing the following commands.

Related Articles
Read the AEM as a Cloud Service advanced network configuration documentation for more details on flexible port egress.

Prerequisites

The following are required when setting or configuring flexible port egress using Cloud Manager APIs:

For more details review how to setup, configure, and obtain Cloud Manger API credentials,to use them to make a Cloud Manager API call.

This tutorial uses curl to make the Cloud Manager API configurations. The provided curl commands assume a Linux/macOS syntax. If using the Windows command prompt, replace the \ line-break character with ^.

Enable flexible port egress per program

Start by enabling the flexible port egress on AEM as a Cloud Service.

Cloud Manager

Flexible port egress can be enabled using Cloud Manager. The following steps outline how to enable flexible port egress on AEM as a Cloud Service using the Cloud Manager.

  1. Log in to the Adobe Experience Manager Cloud Manager as a Cloud Manager Business Owner.

  2. Navigate to the desired Program.

  3. In the left menu, navigate to Services > Network Infrastructures.

  4. Select the Add network infrastructure button.

    Add network infrastructure

  5. In the Add network infrastructure dialog, select the Flexible port egress option, and select the Region to create the dedicated egress IP address.

    Add flexible port egress

  6. Select Save to confirm the addition of the flexible port egress.

    Confirm flexible port egress creation

  7. Wait for the network infrastructure to be created and marked as Ready. This process can take up to 1 hour.

    Flexible port egress creation status

With the flexible port egress created, you can now configure the port forwarding rules using the Cloud Manager APIs as described below.

Cloud Manager APIs

Flexible port egress can be enabled using Cloud Manager APIs. The following steps outline how to enable flexible port egress on AEM as a Cloud Service using the Cloud Manager API.

  1. First, determine the region Advanced Networking is set up in by using the Cloud Manager API listRegions operation. The region name is required to make subsequent Cloud Manager API calls. Typically, the region the Production environment resides in is used.

    Find your AEM as a Cloud Service environment’s region in Cloud Manager under the environment’s details. The region name displayed in Cloud Manager can be mapped to the region code used in the Cloud Manager API.

    listRegions HTTP request

    code language-shell 
    $ curl -X GET https://cloudmanager.adobe.io/api/program/{programId}/regions \
    -H 'x-gw-ims-org-id: <ORGANIZATION_ID>' \
    -H 'x-api-key: <CLIENT_ID>' \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json'

  2. Enable flexible port egress for a Cloud Manager Program using the Cloud Manager API createNetworkInfrastructure operation. Use the appropriate region code obtained from the Cloud Manager API listRegions operation.

    createNetworkInfrastructure HTTP request

    code language-shell 
    $ curl -X POST https://cloudmanager.adobe.io/api/program/{programId}/networkInfrastructures \
    -H 'x-gw-ims-org-id: <ORGANIZATION_ID>' \
    -H 'x-api-key: <CLIENT_ID>' \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{ "kind": "flexiblePortEgress", "region": "va7" }'

    Wait 15 minutes for the Cloud Manager Program to provision the network infrastructure.

  3. Check that the environment has finished flexible port egress configuration using the Cloud Manager API getNetworkInfrastructure operation, using the id returned from the createNetworkInfrastructure HTTP request in the previous step.

    getNetworkInfrastructure HTTP request

    code language-shell 
    $ curl -X GET https://cloudmanager.adobe.io/api/program/{programId}/networkInfrastructure/{networkInfrastructureId} \
    -H 'x-gw-ims-org-id: <ORGANIZATION_ID>' \
    -H 'x-api-key: <CLIENT_ID>' \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json'

    Verify that the HTTP response contains a status of ready. If not yet ready, recheck the status every few minutes.

With the flexible port egress created, you can now configure the port forwarding rules using the Cloud Manager APIs as described below.

Configure flexible port egress proxies per environment

  1. Enable and configure the flexible port egress configuration on each AEM as a Cloud Service environment using the Cloud Manager API enableEnvironmentAdvancedNetworkingConfiguration operation.

    enableEnvironmentAdvancedNetworkingConfiguration HTTP request

    code language-shell 
    $ curl -X PUT https://cloudmanager.adobe.io/api/program/{programId}/environment/{environmentId}/advancedNetworking \
    -H 'x-gw-ims-org-id: <ORGANIZATION_ID>' \
    -H 'x-api-key: <CLIENT_ID>' \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d @./flexible-port-egress.json

    Define the JSON parameters in a flexible-port-egress.json and provided to curl via ... -d @./flexible-port-egress.json.

    Download the example flexible-port-egress.json. This file only an example. Configure your file as required based on the optional/required fields documented at enableEnvironmentAdvancedNetworkingConfiguration.

    code language-json 
    {
    "portForwards": [
        {
            "name": "mysql.example.com",
            "portDest": 3306,
            "portOrig": 30001
        },
        {
            "name": "smtp.sendgrid.com",
            "portDest": 465,
            "portOrig": 30002
        }
    ]
}

    For each portForwards mapping, the advanced networking defines the following forwarding rule:

    table 0-row-5 1-row-5
    Proxy host Proxy port External host External port
    AEM_PROXY_HOST portForwards.portOrig → portForwards.name portForwards.portDest

    If your AEM deployment only requires HTTP/HTTPS connections (port 80/443) to external service, leave the portForwards array empty, as these rules are only required for non-HTTP/HTTPS requests.

  2. For each environment, validate the egress rules are in effect using the Cloud Manager API getEnvironmentAdvancedNetworkingConfiguration operation.

    getEnvironmentAdvancedNetworkingConfiguration HTTP request

    code language-shell 
    $ curl -X GET https://cloudmanager.adobe.io/api/program/{programId}/environment/{environmentId}/advancedNetworking \
    -H 'x-gw-ims-org-id: <ORGANIZATION_ID>' \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'x-api-key: <CLIENT_ID>' \
    -H 'Content-Type: application/json'

  3. Flexible port egress configurations can be updated using the Cloud Manager API enableEnvironmentAdvancedNetworkingConfiguration operation. Remember enableEnvironmentAdvancedNetworkingConfiguration is a PUT operation, so all rules must be provided with every invocation of this operation.

  4. Now, you can use the flexible port egress configuration in your custom AEM code and configuration.

Connecting to external services over flexible port egress

With the flexible port egress proxy enabled, AEM code and configuration can use them to make calls to external services. There are two flavors of external calls that AEM treats differently:

  1. HTTP/HTTPS calls to external services on non-standard ports
    • Includes HTTP/HTTPS calls made to services running on ports other than the standard 80 or 443 ports.
  2. non-HTTP/HTTPS calls to external services
    • Includes any non-HTTP calls, such as connections with Mail servers, SQL databases, or services that run on other non-HTTP/HTTPS protocols.

HTTP/HTTPS requests from AEM on standard ports (80/443) are allowed by default and need no extra configuration or considerations.

HTTP/HTTPS on non-standard ports

When creating HTTP/HTTPS connections to non-standard ports (not-80/443) from AEM, the connections must be made through special host and ports, provided via placeholders.

AEM provides two sets of special Java™ system variables that map to AEM’s HTTP/HTTPS proxies.

Variable name
Use
Java™ code
OSGi configuration
AEM_PROXY_HOST
Proxy host for both HTTP/HTTPS connections
System.getenv().getOrDefault("AEM_PROXY_HOST", "proxy.tunnel")
$[env:AEM_PROXY_HOST;default=proxy.tunnel]
AEM_HTTP_PROXY_PORT
Proxy port for HTTPS connections (set fallback to 3128)
System.getenv().getOrDefault("AEM_HTTP_PROXY_PORT", 3128)
$[env:AEM_HTTP_PROXY_PORT;default=3128]
AEM_HTTPS_PROXY_PORT
Proxy port for HTTPS connections (set fallback to 3128)
System.getenv().getOrDefault("AEM_HTTPS_PROXY_PORT", 3128)
$[env:AEM_HTTPS_PROXY_PORT;default=3128]

When making HTTP/HTTPS calls to external services on non-standard ports, no corresponding portForwards must be defined using the Cloud Manager API enableEnvironmentAdvancedNetworkingConfiguration operation, as the port forwarding “rules” are defined “in code”.

TIP
See AEM as a Cloud Service’s flexible port egress documentation for the full set of routing rules.

Code examples

HTTP/HTTPS on non-standard ports

HTTP/HTTPS on non-standard ports

Java™ code example making HTTP/HTTPS connection from AEM as a Cloud Service to an external service on non-standard HTTP/HTTPS ports.

Non-HTTP/HTTPS connections to external services

When creating non-HTTP/HTTPS connections (ex. SQL, SMTP, and so on) from AEM, the connection must be made through a special host name provided by AEM.

Variable name
Use
Java™ code
OSGi configuration
AEM_PROXY_HOST
Proxy host for non-HTTP/HTTPS connections
System.getenv().getOrDefault("AEM_PROXY_HOST", "proxy.tunnel")
$[env:AEM_PROXY_HOST;default=proxy.tunnel]

Connections to external services are then called through the AEM_PROXY_HOST and the mapped port (portForwards.portOrig), which AEM then routes to the mapped external hostname (portForwards.name) and port (portForwards.portDest).

Proxy host
Proxy port
External host
External port
AEM_PROXY_HOST
portForwards.portOrig
→
portForwards.name
portForwards.portDest

Code examples

SQL connection using JDBC DataSourcePool

SQL connection using JDBC DataSourcePool

Java™ code example connecting to external SQL databases by configuring AEM's JDBC datasource pool.

SQL connection using Java APIs

SQL connection using Java™ APIs

Java™ code example connecting to external SQL databases using Java™'s SQL APIs.

Virtual Private Network (VPN)

E-mail service

OSGi configuration example using AEM to connect to external e-mail services.

recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69