Skip to content

Commit e1f8f53

Browse files
paragbhingreparagbhingre
authored
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.
1 parent 0727059 commit e1f8f53

6 files changed

Lines changed: 235 additions & 1 deletion

File tree

‎site/content/docs/include/http-additionalrules-healthcheck.en.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
2+
<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>
3+
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 "/".
4+
```yaml
5+
http:
6+
additional_rules:
7+
- healthcheck: '/'
8+
```
9+
You can also specify healthcheck as a map:
10+
```yaml
11+
http:
12+
additional_rules:
13+
- healthcheck:
14+
path: '/'
15+
port: 8080
16+
success_codes: '200'
17+
healthy_threshold: 3
18+
unhealthy_threshold: 2
19+
interval: 15s
20+
timeout: 10s
21+
grace_period: 60s
22+
```
23+
24+
<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>
25+
The destination that the health check requests are sent to.
26+
27+
<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>
28+
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.
29+
If the port exposed is `443`, then the health check protocol is automatically set to HTTPS.
30+
31+
<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>
32+
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.
33+
34+
<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>
35+
The number of consecutive health check successes required before considering an unhealthy target healthy. The default is 5. Range: 2-10.
36+
37+
<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>
38+
The number of consecutive health check failures required before considering a target unhealthy. The default is 2. Range: 2-10.
39+
40+
<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>
41+
The approximate amount of time, in seconds, between health checks of an individual target. The default is 30s. Range: 5s–300s.
42+
43+
<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>
44+
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.
45+
46+
<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>
47+
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.

‎site/content/docs/include/http-additionalrules.en.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
??? note "http.additional_rules Map"
2+
3+
<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>
4+
Requests to this path will be forwarded to your service. Each listener rule should listen on a unique path.
5+
6+
{% include 'http-additionalrules-healthcheck.en.md' %}
7+
8+
<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>
9+
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.
10+
11+
<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>
12+
A sidecar container that requests are routed to instead of the main service container.
13+
If the target container's port is set to `443`, then the protocol is set to `HTTPS` so that the load balancer establishes
14+
TLS connections with the Fargate tasks using certificates that you install on the target container.
15+
16+
<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>
17+
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.
18+
19+
<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>
20+
Indicates whether sticky sessions are enabled.
21+
22+
<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>
23+
CIDR IP addresses permitted to access your service.
24+
```yaml
25+
http:
26+
additional_rules:
27+
- allowed_source_ips: ["192.0.2.0/24", "198.51.100.10/32"]
28+
```
29+
30+
<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>
31+
HTTPS domain alias of your service.
32+
```yaml
33+
# String version.
34+
http:
35+
additional_rules:
36+
- alias: example.com
37+
# Alternatively, as an array of strings.
38+
http:
39+
additional_rules:
40+
- alias: ["example.com", "v1.example.com"]
41+
# Alternatively, as an array of maps.
42+
http:
43+
additional_rules:
44+
- alias:
45+
- name: example.com
46+
hosted_zone: Z0873220N255IR3MTNR4
47+
- name: v1.example.com
48+
hosted_zone: AN0THE9H05TED20NEID
49+
```
50+
<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>
51+
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.
52+
```yaml
53+
http:
54+
additional_rules:
55+
- alias: example.com
56+
hosted_zone: Z0873220N255IR3MTNR4
57+
# Also see http.alias array of maps example, above.
58+
```
59+
<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>
60+
Automatically redirect the Application Load Balancer from HTTP to HTTPS. By default it is `true`.
61+
62+
<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>
63+
The HTTP(S) protocol version. Must be one of `'grpc'`, `'http1'`, or `'http2'`. If omitted, then `'http1'` is assumed.
64+
If using gRPC, please note that a domain must be associated with your application.

‎site/content/docs/include/nlb-additionallisteners.en.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
??? note "nlb.additional_listeners Map"
2+
<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>
3+
Required. The additional port and protocol for the Network Load Balancer to listen on.
4+
5+
Accepted protocols include `tcp` and `tls`. If the protocol is not specified, `tcp` is used by default.
6+
7+
<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>
8+
Specify the health check configuration for your additional listener on the Network Load Balancer.
9+
```yaml
10+
nlb:
11+
additional_listeners:
12+
- healthcheck:
13+
port: 80
14+
healthy_threshold: 3
15+
unhealthy_threshold: 2
16+
interval: 15s
17+
timeout: 10s
18+
```
19+
20+
<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>
21+
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.
22+
23+
<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>
24+
The number of consecutive health check successes required before considering an unhealthy target healthy. The default is 3. Range: 2-10.
25+
26+
<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>
27+
The number of consecutive health check failures required before considering a target unhealthy. The default is 3. Range: 2-10.
28+
29+
<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>
30+
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.
31+
32+
<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>
33+
The amount of time, in seconds, during which no response from a target means a failed health check. The default is 10s.
34+
35+
<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>
36+
A sidecar container that takes the place of a service container.
37+
38+
<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>
39+
The container port that receives traffic. Specify this field if the container port is different from `nlb.port`, the listener port.
40+
41+
<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>
42+
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).
43+
44+
<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>
45+
Indicates whether sticky sessions are enabled.

‎site/content/docs/include/nlb.en.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,3 +78,7 @@ nlb:
7878
nlb:
7979
alias: ["example.com", "v1.example.com"]
8080
```
81+
<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>
82+
Configure multiple NLB listeners.
83+
84+
{% include 'nlb-additionallisteners.en.md' %}

‎site/content/docs/manifest/backend-service.en.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,32 @@ List of all available properties for a `'Backend Service'` manifest. To learn ab
142142
id: fs-1234567
143143
```
144144

145+
=== "Expose Multiple Ports"
146+
147+
```yaml
148+
name: 'backend'
149+
type: 'Backend Service'
150+
151+
image:
152+
build: './backend/Dockerfile'
153+
port: 8080
154+
155+
http:
156+
path: '/'
157+
target_port: 8083 # Traffic on "/" is forwarded to the main container, on port 8083.
158+
additional_rules:
159+
- path: 'customerdb'
160+
target_port: 8081 # Traffic on "/customerdb" is forwarded to the main container, on port 8081.
161+
- path: 'admin'
162+
target_port: 8082 # Traffic on "/admin" is forwarded to the sidecar "envoy", on port 8082.
163+
target_container: envoy
164+
165+
sidecars:
166+
envoy:
167+
port: 80
168+
image: aws_account_id.dkr.ecr.us-west-2.amazonaws.com/envoy-proxy-with-selfsigned-certs:v1
169+
```
170+
145171
<a id="name" href="#name" class="field">`name`</a> <span class="type">String</span>
146172
The name of your service.
147173

@@ -207,6 +233,11 @@ http:
207233
The HTTP(S) protocol version. Must be one of `'grpc'`, `'http1'`, or `'http2'`. If omitted, then `'http1'` is assumed.
208234
If using gRPC, please note that a domain must be associated with your application.
209235

236+
<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>
237+
Configure multiple ALB listener rules.
238+
239+
{% include 'http-additionalrules.en.md' %}
240+
210241
{% include 'image-config-with-port.en.md' %}
211242
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
212243
TLS connections with the Fargate tasks using certificates that you install on the container.

‎site/content/docs/manifest/lb-web-service.en.md‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,40 @@ List of all available properties for a `'Load Balanced Web Service'` manifest. T
229229
placement: 'private'
230230
```
231231

232+
=== "Expose Multiple Ports"
233+
234+
```yaml
235+
name: 'frontend'
236+
type: 'Load Balanced Web Service'
237+
238+
image:
239+
build: './frontend/Dockerfile'
240+
port: 8080
241+
242+
nlb:
243+
port: 8080/tcp # Traffic on port 8080/tcp is forwarded to the main container, on port 8080.
244+
additional_rules:
245+
- port: 8084/tcp # Traffic on port 8084/tcp is forwarded to the main container, on port 8084.
246+
- port: 8085/tcp # Traffic on port 8085/tcp is forwarded to the sidecar "envoy", on port 3000.
247+
target_port: 3000
248+
target_container: envoy
249+
250+
http:
251+
path: '/'
252+
target_port: 8083 # Traffic on "/" is forwarded to the main container, on port 8083.
253+
additional_rules:
254+
- path: 'customerdb'
255+
target_port: 8081 # Traffic on "/customerdb" is forwarded to the main container, on port 8083.
256+
- path: 'admin'
257+
target_port: 8082 # Traffic on "/admin" is forwarded to the sidecar "envoy", on port 8082.
258+
target_container: envoy
259+
260+
sidecars:
261+
envoy:
262+
port: 80
263+
image: aws_account_id.dkr.ecr.us-west-2.amazonaws.com/envoy-proxy-with-selfsigned-certs:v1
264+
```
265+
232266

233267
<a id="name" href="#name" class="field">`name`</a> <span class="type">String</span>
234268
The name of your service.
@@ -247,7 +281,7 @@ To disable the Application Load Balancer, specify `http: false`. Note that for a
247281
at least one of Application Load Balancer or Network Load Balancer must be enabled.
248282

249283
<span class="parent-field">http.</span><a id="http-path" href="#http-path" class="field">`path`</a> <span class="type">String</span>
250-
Requests to this path will be forwarded to your service. Each Load Balanced Web Service should listen on a unique path.
284+
Requests to this path will be forwarded to your service. Each listener rule should listen on a unique path.
251285

252286
{% include 'http-healthcheck.en.md' %}
253287

@@ -259,6 +293,10 @@ A sidecar container that requests are routed to instead of the main service cont
259293
If the target container's port is set to `443`, then the protocol is set to `HTTPS` so that the load balancer establishes
260294
TLS connections with the Fargate tasks using certificates that you install on the target container.
261295

296+
<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>
297+
Optional. The container port that receives traffic. By default, this will be `image.port` if the target container is the main container,
298+
or `sidecars.<name>.port` if the target container is a sidecar.
299+
262300
<span class="parent-field">http.</span><a id="http-stickiness" href="#http-stickiness" class="field">`stickiness`</a> <span class="type">Boolean</span>
263301
Indicates whether sticky sessions are enabled.
264302

@@ -301,6 +339,11 @@ Automatically redirect the Application Load Balancer from HTTP to HTTPS. By defa
301339
The HTTP(S) protocol version. Must be one of `'grpc'`, `'http1'`, or `'http2'`. If omitted, then `'http1'` is assumed.
302340
If using gRPC, please note that a domain must be associated with your application.
303341

342+
<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>
343+
Configure multiple ALB listener rules.
344+
345+
{% include 'http-additionalrules.en.md' %}
346+
304347
{% include 'nlb.en.md' %}
305348

306349
{% include 'image-config-with-port.en.md' %}

0 commit comments

Comments
 (0)