docs: multiple ports docs for manifest (#4684)

This PR adds multiple ports content for LBWS and BS By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the Apache 2.0 License.
aws · Mar 27, 2023 · e1f8f53 · e1f8f53
1 parent 0727059
commit e1f8f53
Show file tree

Hide file tree

Showing 6 changed files with 235 additions and 1 deletion.
diff --git a/site/content/docs/include/http-additionalrules-healthcheck.en.md b/site/content/docs/include/http-additionalrules-healthcheck.en.md
@@ -0,0 +1,47 @@
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-healthcheck" href="#http-additional-rules-healthcheck" class="field">`healthcheck`</a> <span class="type">String or Map</span>  
+    If you specify a string, Copilot interprets it as the path exposed in your container to handle target group health check requests. The default is "/".
+    ```yaml
+    http:
+      additional_rules:
+        - healthcheck: '/'
+    ```
+    You can also specify healthcheck as a map:
+    ```yaml
+    http:
+      additional_rules:
+        - healthcheck:
+            path: '/'
+            port: 8080
+            success_codes: '200'
+            healthy_threshold: 3
+            unhealthy_threshold: 2
+            interval: 15s
+            timeout: 10s
+            grace_period: 60s
+    ```
+
+    <span class="parent-field">http.additional_rules.healthcheck.</span><a id="http-additional-rules-healthcheck-path" href="#http-additional-rules-healthcheck-path" class="field">`path`</a> <span class="type">String</span>  
+    The destination that the health check requests are sent to.
+
+    <span class="parent-field">http.additional_rules.healthcheck.</span><a id="http-additional-rules-healthcheck-port" href="#http-additional-rules-healthcheck-port" class="field">`port`</a> <span class="type">Integer</span>  
+    The port that the health check requests are sent to. The default is [`image.port`](./#image-port), or the port exposed by [`http.target_container`](./#http-target-container), if set.  
+    If the port exposed is `443`, then the health check protocol is automatically set to HTTPS.
+
+    <span class="parent-field">http.additional_rules.healthcheck.</span><a id="http-additional-rules-healthcheck-success-codes" href="#http-additional-rules-healthcheck-success-codes" class="field">`success_codes`</a> <span class="type">String</span>  
+    The HTTP status codes that healthy targets must use when responding to an HTTP health check. You can specify values between 200 and 499. You can specify multiple values (for example, "200,202") or a range of values (for example, "200-299"). The default is 200.
+
+    <span class="parent-field">http.additional_rules.healthcheck.</span><a id="http-additional-rules-healthcheck-healthy-threshold" href="#http-additional-rules-healthcheck-healthy-threshold" class="field">`healthy_threshold`</a> <span class="type">Integer</span>  
+    The number of consecutive health check successes required before considering an unhealthy target healthy. The default is 5. Range: 2-10.
+
+    <span class="parent-field">http.additional_rules.healthcheck.</span><a id="http-additional-rules-healthcheck-unhealthy-threshold" href="#http-additional-rules-healthcheck-unhealthy-threshold" class="field">`unhealthy_threshold`</a> <span class="type">Integer</span>  
+    The number of consecutive health check failures required before considering a target unhealthy. The default is 2. Range: 2-10.
+
+    <span class="parent-field">http.additional_rules.healthcheck.</span><a id="http-additional-rules-healthcheck-interval" href="#http-additional-rules-healthcheck-interval" class="field">`interval`</a> <span class="type">Duration</span>  
+    The approximate amount of time, in seconds, between health checks of an individual target. The default is 30s. Range: 5s–300s.
+
+    <span class="parent-field">http.additional_rules.healthcheck.</span><a id="http-additional-rules-healthcheck-timeout" href="#http-additional-rules-healthcheck-timeout" class="field">`timeout`</a> <span class="type">Duration</span>  
+    The amount of time, in seconds, during which no response from a target means a failed health check. The default is 5s. Range 5s-300s.
+
+    <span class="parent-field">http.additional_rules.healthcheck.</span><a id="http-additional-rules-healthcheck-grace-period" href="#http-additional-rules-healthcheck-grace-period" class="field">`grace_period`</a> <span class="type">Duration</span>  
+    The amount of time to ignore failing target group healthchecks on container start. The default is 60s. This can be useful to fix deployment issues for containers which take a while to become healthy and begin listening for incoming connections, or to speed up deployment of containers guaranteed to start quickly.
diff --git a/site/content/docs/include/http-additionalrules.en.md b/site/content/docs/include/http-additionalrules.en.md
@@ -0,0 +1,64 @@
+??? note "http.additional_rules Map"
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-path" href="#http-additional-rules-path" class="field">`path`</a> <span class="type">String</span>  
+    Requests to this path will be forwarded to your service. Each listener rule should listen on a unique path.
+
+    {% include 'http-additionalrules-healthcheck.en.md' %}
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-deregistration-delay" href="#http-additional-rules-deregistration-delay" class="field">`deregistration_delay`</a> <span class="type">Duration</span>  
+    The amount of time to wait for targets to drain connections during deregistration. The default is 60s. Setting this to a larger value gives targets more time to gracefully drain connections, but increases the time required for new deployments. Range 0s-3600s.
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-target-container" href="#http-additional-rules-target-container" class="field">`target_container`</a> <span class="type">String</span>  
+    A sidecar container that requests are routed to instead of the main service container.  
+    If the target container's port is set to `443`, then the protocol is set to `HTTPS` so that the load balancer establishes
+    TLS connections with the Fargate tasks using certificates that you install on the target container.
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-target-port" href="#http-additional-rules-target-port" class="field">`target_port`</a> <span class="type">String</span>  
+    The container port that receives traffic. Specify this field if the container port is different from `image.port` for the main container or `sidecar.port` for the sidecar containers.
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-stickiness" href="#http-additional-rules-stickiness" class="field">`stickiness`</a> <span class="type">Boolean</span>  
+    Indicates whether sticky sessions are enabled.
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-allowed-source-ips" href="#http-additional-rules-allowed-source-ips" class="field">`allowed_source_ips`</a> <span class="type">Array of Strings</span>  
+    CIDR IP addresses permitted to access your service.
+    ```yaml
+    http:
+      additional_rules:
+        - allowed_source_ips: ["192.0.2.0/24", "198.51.100.10/32"]
+    ```
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-alias" href="#http-additional-rules-alias" class="field">`alias`</a> <span class="type">String or Array of Strings or Array of Maps</span>  
+    HTTPS domain alias of your service.
+    ```yaml
+    # String version.
+    http:
+      additional_rules:
+        - alias: example.com
+    # Alternatively, as an array of strings.
+    http:
+      additional_rules:
+        - alias: ["example.com", "v1.example.com"]
+    # Alternatively, as an array of maps.
+    http:
+      additional_rules:
+        - alias:
+            - name: example.com
+              hosted_zone: Z0873220N255IR3MTNR4
+            - name: v1.example.com
+              hosted_zone: AN0THE9H05TED20NEID
+    ```
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-hosted-zone" href="#http-additional-rules-hosted-zone" class="field">`hosted_zone`</a> <span class="type">String</span>  
+    ID of your existing hosted zone; can only be used with `http.alias` and `http.additional_rules.alias`. If you have an environment with imported certificates, you can specify the hosted zone into which Copilot should insert the A record once the load balancer is created.
+    ```yaml
+    http:
+      additional_rules:
+        - alias: example.com
+          hosted_zone: Z0873220N255IR3MTNR4
+    # Also see http.alias array of maps example, above.
+    ```
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-redirect-to-https" href="#http-additional-rules-redirect-to-https" class="field">`redirect_to_https`</a> <span class="type">Boolean</span>  
+    Automatically redirect the Application Load Balancer from HTTP to HTTPS. By default it is `true`.
+
+    <span class="parent-field">http.additional_rules.</span><a id="http-additional-rules-version" href="#http-additional-rules-version" class="field">`version`</a> <span class="type">String</span>  
+    The HTTP(S) protocol version. Must be one of `'grpc'`, `'http1'`, or `'http2'`. If omitted, then `'http1'` is assumed.
+    If using gRPC, please note that a domain must be associated with your application.
diff --git a/site/content/docs/include/nlb-additionallisteners.en.md b/site/content/docs/include/nlb-additionallisteners.en.md
@@ -0,0 +1,45 @@
+??? note "nlb.additional_listeners Map"
+    <span class="parent-field">nlb.additional_listeners.</span><a id="nlb-additional-listeners-port" href="#nlb-additional-listeners-port" class="field">`port`</a> <span class="type">String</span>  
+    Required. The additional port and protocol for the Network Load Balancer to listen on.
+
+    Accepted protocols include `tcp` and `tls`. If the protocol is not specified, `tcp` is used by default.
+
+    <span class="parent-field">nlb.additional_listeners.</span><a id="nlb-additional-listeners-healthcheck" href="#nlb-additional-listeners-healthcheck" class="field">`healthcheck`</a> <span class="type">Map</span>  
+    Specify the health check configuration for your additional listener on the Network Load Balancer.
+    ```yaml
+    nlb:
+      additional_listeners:
+        - healthcheck:
+            port: 80
+            healthy_threshold: 3
+            unhealthy_threshold: 2
+            interval: 15s
+            timeout: 10s
+    ```
+
+    <span class="parent-field">nlb.additional_listeners.healthcheck.</span><a id="nlb-additional-listeners-healthcheck-port" href="#nlb-additional-listeners-healthcheck-port" class="field">`port`</a> <span class="type">String</span>  
+    The port that the health check requests are sent to. Specify this if your health check should be performed on a different port than the container target port.
+
+    <span class="parent-field">nlb.additional_listeners.healthcheck.</span><a id="nlb-additional-listeners-healthcheck-healthy-threshold" href="#nlb-additional-listeners-healthcheck-healthy-threshold" class="field">`healthy_threshold`</a> <span class="type">Integer</span>  
+    The number of consecutive health check successes required before considering an unhealthy target healthy. The default is 3. Range: 2-10.
+
+    <span class="parent-field">nlb.additional_listeners.healthcheck.</span><a id="nlb-additional-listeners-healthcheck-unhealthy-threshold" href="#nlb-additional-listeners-healthcheck-unhealthy-threshold" class="field">`unhealthy_threshold`</a> <span class="type">Integer</span>  
+    The number of consecutive health check failures required before considering a target unhealthy. The default is 3. Range: 2-10.
+
+    <span class="parent-field">nlb.additional_listeners.healthcheck.</span><a id="nlb-additional-listeners-healthcheck-interval" href="#nlb-additional-listeners-healthcheck-interval" class="field">`interval`</a> <span class="type">Duration</span>  
+    The approximate amount of time, in seconds, between health checks of an individual target. The value can be 10s or 30s. The default is 30s.
+
+    <span class="parent-field">nlb.additional_listeners.healthcheck.</span><a id="nlb-additional-listeners-healthcheck-timeout" href="#nlb-additional-listeners-healthcheck-timeout" class="field">`timeout`</a> <span class="type">Duration</span>  
+    The amount of time, in seconds, during which no response from a target means a failed health check. The default is 10s.
+
+    <span class="parent-field">nlb.additional_listeners.</span><a id="nlb-additional-listeners-target-container" href="#nlb-additional-listeners-target-container" class="field">`target_container`</a> <span class="type">String</span>  
+    A sidecar container that takes the place of a service container.
+
+    <span class="parent-field">nlb.additional_listeners.</span><a id="nlb-additional-listeners-target-port" href="#nlb-additional-listeners-target-port" class="field">`target_port`</a> <span class="type">Integer</span>  
+    The container port that receives traffic. Specify this field if the container port is different from `nlb.port`, the listener port.
+
+    <span class="parent-field">nlb.additional_listeners.</span><a id="nlb-additional-listeners-ssl-policy" href="#nlb-additional-listeners-ssl-policy" class="field">`ssl_policy`</a> <span class="type">String</span>  
+    The security policy that defines which protocols and ciphers are supported. To learn more, see [this doc](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-tls-listener.html#describe-ssl-policies).
+
+    <span class="parent-field">nlb.additional_listeners.</span><a id="nlb-additional-listeners-stickiness" href="#nlb-additional-listeners-stickiness" class="field">`stickiness`</a> <span class="type">Boolean</span>  
+    Indicates whether sticky sessions are enabled.
diff --git a/site/content/docs/include/nlb.en.md b/site/content/docs/include/nlb.en.md
@@ -78,3 +78,7 @@ nlb:
 nlb:
   alias: ["example.com", "v1.example.com"]
 ```
+<span class="parent-field">nlb.</span><a id="nlb-additional-listeners" href="#nlb-additional-listeners" class="field">`additional_listeners`</a> <span class="type">Array of Maps</span>  
+Configure multiple NLB listeners.
+
+{% include 'nlb-additionallisteners.en.md' %}
diff --git a/site/content/docs/manifest/backend-service.en.md b/site/content/docs/manifest/backend-service.en.md
@@ -142,6 +142,32 @@ List of all available properties for a `'Backend Service'` manifest. To learn ab
                 id: fs-1234567
         ```
 
+    === "Expose Multiple Ports"
+
+        ```yaml
+        name: 'backend'
+        type: 'Backend Service'
+
+        image:
+          build: './backend/Dockerfile'
+          port: 8080
+
+        http:
+          path: '/'
+          target_port: 8083           # Traffic on "/" is forwarded to the main container, on port 8083. 
+          additional_rules:
+            - path: 'customerdb'
+              target_port: 8081       # Traffic on "/customerdb" is forwarded to the main container, on port 8081.
+            - path: 'admin' 
+              target_port: 8082       # Traffic on "/admin" is forwarded to the sidecar "envoy", on port 8082.
+              target_container: envoy
+
+        sidecars:
+          envoy:
+            port: 80
+            image: aws_account_id.dkr.ecr.us-west-2.amazonaws.com/envoy-proxy-with-selfsigned-certs:v1
+        ```    
+
 <a id="name" href="#name" class="field">`name`</a> <span class="type">String</span>
 The name of your service.
 
@@ -207,6 +233,11 @@ http:
 The HTTP(S) protocol version. Must be one of `'grpc'`, `'http1'`, or `'http2'`. If omitted, then `'http1'` is assumed.
 If using gRPC, please note that a domain must be associated with your application.
 
+<span class="parent-field">http.</span><a id="http-additional-rules" href="#http-additional-rules" class="field">`additional_rules`</a> <span class="type">Array of Maps</span>  
+Configure multiple ALB listener rules.
+
+{% include 'http-additionalrules.en.md' %}
+
 {% include 'image-config-with-port.en.md' %}  
 If the port is set to `443` and an internal load balancer is enabled with `http`, then the protocol is set to `HTTPS` so that the load balancer establishes
 TLS connections with the Fargate tasks using certificates that you install on the container.

diff --git a/site/content/docs/manifest/lb-web-service.en.md b/site/content/docs/manifest/lb-web-service.en.md
@@ -229,6 +229,40 @@ List of all available properties for a `'Load Balanced Web Service'` manifest. T
             placement: 'private'
         ```
 
+    === "Expose Multiple Ports"
+
+        ```yaml
+        name: 'frontend'
+        type: 'Load Balanced Web Service'
+
+        image:
+          build: './frontend/Dockerfile'
+          port: 8080
+
+        nlb:
+          port: 8080/tcp              # Traffic on port 8080/tcp is forwarded to the main container, on port 8080.
+          additional_rules:  
+            - port: 8084/tcp          # Traffic on port 8084/tcp is forwarded to the main container, on port 8084.
+            - port: 8085/tcp          # Traffic on port 8085/tcp is forwarded to the sidecar "envoy", on port 3000.
+              target_port: 3000         
+              target_container: envoy   
+
+        http:
+          path: '/'
+          target_port: 8083           # Traffic on "/" is forwarded to the main container, on port 8083. 
+          additional_rules: 
+            - path: 'customerdb'
+              target_port: 8081       # Traffic on "/customerdb" is forwarded to the main container, on port 8083.  
+            - path: 'admin'
+              target_port: 8082       # Traffic on "/admin" is forwarded to the sidecar "envoy", on port 8082.
+              target_container: envoy    
+
+        sidecars:
+          envoy:
+            port: 80
+            image: aws_account_id.dkr.ecr.us-west-2.amazonaws.com/envoy-proxy-with-selfsigned-certs:v1
+        ```
+
 
 <a id="name" href="#name" class="field">`name`</a> <span class="type">String</span>  
 The name of your service.
@@ -247,7 +281,7 @@ To disable the Application Load Balancer, specify `http: false`. Note that for a
 at least one of Application Load Balancer or Network Load Balancer must be enabled.
 
 <span class="parent-field">http.</span><a id="http-path" href="#http-path" class="field">`path`</a> <span class="type">String</span>  
-Requests to this path will be forwarded to your service. Each Load Balanced Web Service should listen on a unique path.
+Requests to this path will be forwarded to your service. Each listener rule should listen on a unique path.
 
 {% include 'http-healthcheck.en.md' %}
 
@@ -259,6 +293,10 @@ A sidecar container that requests are routed to instead of the main service cont
 If the target container's port is set to `443`, then the protocol is set to `HTTPS` so that the load balancer establishes 
 TLS connections with the Fargate tasks using certificates that you install on the target container.
 
+<span class="parent-field">http.</span><a id="http-target-port" href="#http-target-port" class="field">`target_port`</a> <span class="type">String</span>  
+Optional. The container port that receives traffic. By default, this will be `image.port` if the target container is the main container, 
+or `sidecars.<name>.port` if the target container is a sidecar.
+
 <span class="parent-field">http.</span><a id="http-stickiness" href="#http-stickiness" class="field">`stickiness`</a> <span class="type">Boolean</span>  
 Indicates whether sticky sessions are enabled.
 
@@ -301,6 +339,11 @@ Automatically redirect the Application Load Balancer from HTTP to HTTPS. By defa
 The HTTP(S) protocol version. Must be one of `'grpc'`, `'http1'`, or `'http2'`. If omitted, then `'http1'` is assumed.
 If using gRPC, please note that a domain must be associated with your application.
 
+<span class="parent-field">http.</span><a id="http-additional-rules" href="#http-additional-rules" class="field">`additional_rules`</a> <span class="type">Array of Maps</span>  
+Configure multiple ALB listener rules.
+
+{% include 'http-additionalrules.en.md' %}
+
 {% include 'nlb.en.md' %}
 
 {% include 'image-config-with-port.en.md' %}