Virtual gateways

To create a virtual gateway using the Amazon Web Services Management Console

1. Open the App Mesh console at https://console.amazonaws.cn/appmesh/.

2. Choose the mesh in which you want to create the virtual gateway. All of the meshes that you own and that have been shared with you are listed.

3. Choose Virtual gateways in the left navigation.

4. Choose Create virtual gateway.

5. For Virtual gateway name, enter a name for your virtual gateway.

6. (Optional, but recommended) Configure Client policy defaults.

   1. (Optional) Select Enforce TLS if you want the gateway to only communicate with virtual services using Transport Layer Security (TLS).

   2. (Optional) For Ports, specify one or more ports on which you want to enforce TLS communication with virtual services.

   3. For Validation method, select one of the following options. The certificate that you specify must already exist and meet specific requirements. For more information, see Certificate requirements.

      • Amazon Private Certificate Authority hosting – Select one or more existing Certificates.

      • Envoy Secret Discovery Service (SDS) hosting – Enter the name of the secret that Envoy fetches using the Secret Discovery Service.

      • Local file hosting – Specify the path to the Certificate chain file on the file system where Envoy is deployed.

   4. (Optional) Enter a Subject Alternative Name. To add additional SANs, select Add SAN. SANs must be FQDN or URI formatted.

   5. (Optional) Select Provide client certificate and one of the options below to provide a client certificate when a server requests it and enable mutual TLS authentication. To learn more about mutual TLS, see the App Mesh Mutual TLS Authentication docs.

      • Envoy Secret Discovery Service (SDS) hosting – Enter the name of the secret that Envoy fetches using the Secret Discovery Service.

      • Local file hosting – Specify the path to the Certificate chain file, as well as the Private key, on the file system where Envoy is deployed. For a complete, end-to-end walk through of deploying a mesh with a sample application using encryption with local files, see Configuring TLS with File Provided TLS Certificates on GitHub.

7. (Optional) To configure logging, selected Logging. Enter the HTTP access logs path that you want Envoy to use. We recommend the /dev/stdout path so that you can use Docker log drivers to export your Envoy logs to a service such as Amazon CloudWatch Logs.

   Note

   Logs must still be ingested by an agent in your application and sent to a destination. This file path only instructs Envoy where to send the logs.

   Show moreShow less

8. Configure the Listener.

   1. Select a Protocol and specify the Port on which Envoy listens for traffic. The http listener permits connection transition to websockets. You can click Add Listener to add multiple listeners. The Remove button will remove that listener.

   2. (Optional) Enable connection pool

      Connection pooling limits the number of connections that the Virtual Gateway Envoy can concurrently establish. It is intended to protect your Envoy instance from being overwhelmed with connections and lets you adjust traffic shaping for the needs of your applications.

      You can configure destination-side connection pool settings for a virtual gateway listener. App Mesh sets the client-side connection pool settings to infinite by default, simplifying mesh configuration.

      Note

      The connectionPool and connectionPoolportMapping protocols must be the same. If your listener protocol is grpc or http2, specify maxRequests only. If your listener protocol is http, you can specify both maxConnections and maxPendingRequests.

      • For Maximum connections, specify the maximum number of outbound connections.

      • For Maximum requests, specify maximum number of parallel requests that can be established with the Virtual Gateway Envoy.

      • (Optional) For Maximum pending requests, specify the number of overflowing requests after Maximum connections that an Envoy queues. The default value is 2147483647.

      Show moreShow less

   3. (Optional) If you want to configure a health check for your listener, then select Enable health check.

      A health check policy is optional, but if you specify any values for a health policy, then you must specify values for Healthy threshold, Health check interval, Health check protocol, Timeout period, and Unhealthy threshold.

      • For Health check protocol, choose a protocol. If you select grpc, then your service must conform to the GRPC Health Checking Protocol.

      • For Health check port, specify the port that the health check should run on.

      • For Healthy threshold, specify the number of consecutive successful health checks that must occur before declaring the listener healthy.

      • For Health check interval, specify the time period in milliseconds between each health check execution.

      • For Path, specify the destination path for the health check request. This value is only used if the Health check protocol is http or http2. The value is ignored for other protocols.

      • For Timeout period, specify the amount of time to wait when receiving a response from the health check in milliseconds.

      • For Unhealthy threshold, specify the number of consecutive failed health checks that must occur before declaring the listener unhealthy.

      Show moreShow less

   4. (Optional) If you want to specify whether clients communicate with this virtual gateway using TLS, then select Enable TLS termination.

      • For Mode, select the mode that you want TLS to be configured for on the listener.

      • For Certificate method, select one of the following options. The certificate must meet specific requirements. For more information, see Certificate requirements.

        • Amazon Certificate Manager hosting – Select an existing Certificate.

        • Envoy Secret Discovery Service (SDS) hosting – Enter the name of the secret that Envoy fetches using the Secret Discovery Service.

        • Local file hosting – Specify the path to the Certificate chain and Private key files on the file system where Envoy is deployed.

      • (Optional) Select Require client certificate and one of the options below to enable mutual TLS authentication if the client provides a certificate. To learn more about mutual TLS, see the App Mesh Mutual TLS Authentication docs.

        • Envoy Secret Discovery Service (SDS) hosting – Enter the name of the secret that Envoy fetches using the Secret Discovery Service.

        • Local file hosting – Specify the path to the Certificate chain file on the file system where Envoy is deployed.

      • (Optional) Enter a Subject Alternative Name. To add additional SANs, select Add SAN. SANs must be FQDN or URI formatted.

      Show moreShow less

9. Choose Create virtual gateway to finish.

1. aws appmesh create-virtual-gateway \ 
   --mesh-name meshName \ 
   --virtual-gateway-name virtualGatewayName \ 
   --cli-input-json file://create-virtual-gateway.json

2. Contents of example create-virtual-gateway.json:

   {
       "spec": {
         "listeners": [
           {
             "portMapping": {
               "port": 9080,
               "protocol": "http"
             }
           }
         ]
       }
   }

3. Example output:

   {
       "virtualGateway": {
           "meshName": "meshName",
           "metadata": {
               "arn": "arn:aws:appmesh:us-west-2:123456789012:mesh/meshName/virtualGateway/virtualGatewayName",
               "createdAt": "2022-04-06T10:42:42.015000-05:00",
               "lastUpdatedAt": "2022-04-06T10:42:42.015000-05:00",
               "meshOwner": "123456789012",
               "resourceOwner": "123456789012",
               "uid": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
               "version": 1
           },
           "spec": {
               "listeners": [
                   {
                       "portMapping": {
                           "port": 9080,
                           "protocol": "http"
                       }
                   }
               ]
           },
           "status": {
               "status": "ACTIVE"
           },
           "virtualGatewayName": "virtualGatewayName"
       }
   }
   

To delete a virtual gateway using the Amazon Web Services Management Console

1. Open the App Mesh console at https://console.amazonaws.cn/appmesh/.

2. Choose the mesh from which you want to delete a virtual gateway. All of the meshes that you own and that have been shared with you are listed.

3. Choose Virtual gateways in the left navigation.

4. Choose the virtual gateway that you want to delete and select Delete. You cannot delete a virtual gateway if it has any associated gateway routes. You must delete any associated gateway routes first. You can only delete a virtual gateway where your account is listed as Resource owner.

5. In the confirmation box, type delete and then select Delete.

To delete a virtual gateway using the Amazon CLI

1. Use the following command to delete your virtual gateway (replace the red values with your own):

   aws appmesh delete-virtual-gateway \
        --mesh-name meshName \
        --virtual-gateway-name virtualGatewayName

2. Example output:

   {
       "virtualGateway": {
           "meshName": "meshName",
           "metadata": {
               "arn": "arn:aws:appmesh:us-west-2:123456789012:mesh/meshName/virtualGateway/virtualGatewayName",
               "createdAt": "2022-04-06T10:42:42.015000-05:00",
               "lastUpdatedAt": "2022-04-07T10:57:22.638000-05:00",
               "meshOwner": "123456789012",
               "resourceOwner": "123456789012",
               "uid": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
               "version": 2
           },
           "spec": {
               "listeners": [
                   {
                       "portMapping": {
                           "port": 9080,
                           "protocol": "http"
                       }
                   }
               ]
           },
           "status": {
               "status": "DELETED"
           },
           "virtualGatewayName": "virtualGatewayName"
       }
   }