From e1f8f53a444e4e1bf74f16805ea844afd00ae54b Mon Sep 17 00:00:00 2001 From: Parag Sanjay Bhingre Date: Mon, 27 Mar 2023 15:18:36 -0700 Subject: [PATCH] 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. --- .../http-additionalrules-healthcheck.en.md | 47 ++++++++++++++ .../docs/include/http-additionalrules.en.md | 64 +++++++++++++++++++ .../include/nlb-additionallisteners.en.md | 45 +++++++++++++ site/content/docs/include/nlb.en.md | 4 ++ .../docs/manifest/backend-service.en.md | 31 +++++++++ .../docs/manifest/lb-web-service.en.md | 45 ++++++++++++- 6 files changed, 235 insertions(+), 1 deletion(-) create mode 100644 site/content/docs/include/http-additionalrules-healthcheck.en.md create mode 100644 site/content/docs/include/http-additionalrules.en.md create mode 100644 site/content/docs/include/nlb-additionallisteners.en.md diff --git a/site/content/docs/include/http-additionalrules-healthcheck.en.md b/site/content/docs/include/http-additionalrules-healthcheck.en.md new file mode 100644 index 00000000000..a2d9199417d --- /dev/null +++ b/site/content/docs/include/http-additionalrules-healthcheck.en.md @@ -0,0 +1,47 @@ + + http.additional_rules.`healthcheck` String or Map + 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 + ``` + + http.additional_rules.healthcheck.`path` String + The destination that the health check requests are sent to. + + http.additional_rules.healthcheck.`port` Integer + 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. + + http.additional_rules.healthcheck.`success_codes` String + 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. + + http.additional_rules.healthcheck.`healthy_threshold` Integer + The number of consecutive health check successes required before considering an unhealthy target healthy. The default is 5. Range: 2-10. + + http.additional_rules.healthcheck.`unhealthy_threshold` Integer + The number of consecutive health check failures required before considering a target unhealthy. The default is 2. Range: 2-10. + + http.additional_rules.healthcheck.`interval` Duration + The approximate amount of time, in seconds, between health checks of an individual target. The default is 30s. Range: 5s–300s. + + http.additional_rules.healthcheck.`timeout` Duration + 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. + + http.additional_rules.healthcheck.`grace_period` Duration + 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 new file mode 100644 index 00000000000..0a6e4975902 --- /dev/null +++ b/site/content/docs/include/http-additionalrules.en.md @@ -0,0 +1,64 @@ +??? note "http.additional_rules Map" + + http.additional_rules.`path` String + 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' %} + + http.additional_rules.`deregistration_delay` Duration + 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. + + http.additional_rules.`target_container` String + 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. + + http.additional_rules.`target_port` String + 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. + + http.additional_rules.`stickiness` Boolean + Indicates whether sticky sessions are enabled. + + http.additional_rules.`allowed_source_ips` Array of Strings + 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"] + ``` + + http.additional_rules.`alias` String or Array of Strings or Array of Maps + 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 + ``` + http.additional_rules.`hosted_zone` String + 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. + ``` + http.additional_rules.`redirect_to_https` Boolean + Automatically redirect the Application Load Balancer from HTTP to HTTPS. By default it is `true`. + + http.additional_rules.`version` String + 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. \ No newline at end of file diff --git a/site/content/docs/include/nlb-additionallisteners.en.md b/site/content/docs/include/nlb-additionallisteners.en.md new file mode 100644 index 00000000000..a09ef06dee1 --- /dev/null +++ b/site/content/docs/include/nlb-additionallisteners.en.md @@ -0,0 +1,45 @@ +??? note "nlb.additional_listeners Map" + nlb.additional_listeners.`port` String + 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. + + nlb.additional_listeners.`healthcheck` Map + 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 + ``` + + nlb.additional_listeners.healthcheck.`port` String + 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. + + nlb.additional_listeners.healthcheck.`healthy_threshold` Integer + The number of consecutive health check successes required before considering an unhealthy target healthy. The default is 3. Range: 2-10. + + nlb.additional_listeners.healthcheck.`unhealthy_threshold` Integer + The number of consecutive health check failures required before considering a target unhealthy. The default is 3. Range: 2-10. + + nlb.additional_listeners.healthcheck.`interval` Duration + 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. + + nlb.additional_listeners.healthcheck.`timeout` Duration + The amount of time, in seconds, during which no response from a target means a failed health check. The default is 10s. + + nlb.additional_listeners.`target_container` String + A sidecar container that takes the place of a service container. + + nlb.additional_listeners.`target_port` Integer + The container port that receives traffic. Specify this field if the container port is different from `nlb.port`, the listener port. + + nlb.additional_listeners.`ssl_policy` String + 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). + + nlb.additional_listeners.`stickiness` Boolean + Indicates whether sticky sessions are enabled. \ No newline at end of file diff --git a/site/content/docs/include/nlb.en.md b/site/content/docs/include/nlb.en.md index 425fea5e4f3..24b60c8b9d0 100644 --- 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"] ``` +nlb.`additional_listeners` Array of Maps +Configure multiple NLB listeners. + +{% include 'nlb-additionallisteners.en.md' %} \ No newline at end of file diff --git a/site/content/docs/manifest/backend-service.en.md b/site/content/docs/manifest/backend-service.en.md index 10bc4b3b2c4..a3b24cdd31c 100644 --- 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 + ``` + `name` String 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. +http.`additional_rules` Array of Maps +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 index 9bd96070526..ac290b0ff96 100644 --- 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 + ``` + `name` String 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. http.`path` String -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. +http.`target_port` String +Optional. The container port that receives traffic. By default, this will be `image.port` if the target container is the main container, +or `sidecars..port` if the target container is a sidecar. + http.`stickiness` Boolean 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. +http.`additional_rules` Array of Maps +Configure multiple ALB listener rules. + +{% include 'http-additionalrules.en.md' %} + {% include 'nlb.en.md' %} {% include 'image-config-with-port.en.md' %}