Skip to content

Clarify that ip-mode can be NodePort or ClusterIp #2725

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 11, 2022
Merged

Clarify that ip-mode can be NodePort or ClusterIp #2725

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a266bf6
Clarify that ip-mode can be NodePort or ClusterIp
orsenthil Jul 11, 2022
c425a00
Update annotations.md
orsenthil Jul 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 32 additions & 31 deletions docs/guide/ingress/annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ By default, Ingresses don't belong to any IngressGroup, and we treat it as a "im

!!!warning "Security Risk"
IngressGroup feature should only be used when all Kubernetes users with RBAC permission to create/modify Ingress resources are within trust boundary.

If you turn your Ingress to belong a "explicit IngressGroup" by adding `group.name` annotation,
other Kubernetes users may create/modify their Ingresses to belong to the same IngressGroup, and can thus add more rules or overwrite existing rules with higher priority to the ALB for your Ingress.

Expand All @@ -86,7 +86,7 @@ By default, Ingresses don't belong to any IngressGroup, and we treat it as a "im
```

- <a name="group.order">`alb.ingress.kubernetes.io/group.order`</a> specifies the order across all Ingresses within IngressGroup.

!!!note ""
- You can explicitly denote the order using a number between -1000 and 1000
- The smaller the order, the rule will be evaluated first. All Ingresses without an explicit order setting get order value as 0
Expand All @@ -101,26 +101,26 @@ By default, Ingresses don't belong to any IngressGroup, and we treat it as a "im
Traffic Listening can be controlled with the following annotations:

- <a name="listen-ports">`alb.ingress.kubernetes.io/listen-ports`</a> specifies the ports that ALB listens on.

!!!note "Merge Behavior"
`listen-ports` is merged across all Ingresses in IngressGroup.

- You can define different listen-ports per Ingress, Ingress rules will only impact the ports defined for that Ingress.
- If same listen-port is defined by multiple Ingress within IngressGroup, Ingress rules will be merged with respect to their group order within IngressGroup.

!!!note "Default"
- defaults to `'[{"HTTP": 80}]'` or `'[{"HTTPS": 443}]'` depending on whether `certificate-arn` is specified.

!!!warning ""
!!!warning ""
You may not have duplicate load balancer ports defined.

!!!example
```
alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}, {"HTTP": 8080}, {"HTTPS": 8443}]'
```

- <a name="ssl-redirect">`alb.ingress.kubernetes.io/ssl-redirect`</a> enables SSLRedirect and specifies the SSL port that redirects to.

!!!note "Merge Behavior"
`ssl-redirect` is exclusive across all Ingresses in IngressGroup.

Expand All @@ -143,7 +143,7 @@ Traffic Listening can be controlled with the following annotations:
```

- <a name="customer-owned-ipv4-pool">`alb.ingress.kubernetes.io/customer-owned-ipv4-pool`</a> specifies the customer-owned IPv4 address pool for ALB on Outpost.

!!!warning ""
This annotation should be treated as immutable. To remove or change coIPv4Pool, you need to recreate Ingress.

Expand Down Expand Up @@ -182,7 +182,7 @@ Traffic Routing can be controlled with following annotations:
- [amazon-vpc-cni-k8s](https://github.com/aws/amazon-vpc-cni-k8s)

!!!note ""
`ip` mode is required for sticky sessions to work with Application Load Balancers.
`ip` mode is required for sticky sessions to work with Application Load Balancers. The Service type does not matter, when using `ip` mode.

!!!example
```
Expand All @@ -203,7 +203,7 @@ Traffic Routing can be controlled with following annotations:
alb.ingress.kubernetes.io/backend-protocol: HTTPS
```

- <a name="backend-protocol-version">`alb.ingress.kubernetes.io/backend-protocol-version`</a> specifies the application protocol used to route traffic to pods. Only valid when HTTP or HTTPS is used as the backend protocol.
- <a name="backend-protocol-version">`alb.ingress.kubernetes.io/backend-protocol-version`</a> specifies the application protocol used to route traffic to pods. Only valid when HTTP or HTTPS is used as the backend protocol.

!!!example
- HTTP2
Expand Down Expand Up @@ -236,7 +236,7 @@ Traffic Routing can be controlled with following annotations:
ARN can be used in forward action(both simplified schema and advanced schema), it must be an targetGroup created outside of k8s, typically an targetGroup for legacy application.
!!!note "use ServiceName/ServicePort in forward Action"
ServiceName/ServicePort can be used in forward action(advanced schema only).

!!!warning ""
[Auth related annotations](#authentication) on Service object will only be respected if a single TargetGroup in is used.

Expand Down Expand Up @@ -297,24 +297,24 @@ Traffic Routing can be controlled with following annotations:
name: use-annotation
```

- <a name="conditions">`alb.ingress.kubernetes.io/conditions.${conditions-name}`</a> Provides a method for specifying routing conditions **in addition to original host/path condition on Ingress spec**.
The `conditions-name` in the annotation must match the serviceName in the Ingress rules.
- <a name="conditions">`alb.ingress.kubernetes.io/conditions.${conditions-name}`</a> Provides a method for specifying routing conditions **in addition to original host/path condition on Ingress spec**.

The `conditions-name` in the annotation must match the serviceName in the Ingress rules.
It can be a either real serviceName or an annotation based action name when servicePort is `use-annotation`.

!!!warning "limitations"
General ALB limitations applies:

1. Each rule can optionally include up to one of each of the following conditions: host-header, http-request-method, path-pattern, and source-ip. Each rule can also optionally include one or more of each of the following conditions: http-header and query-string.

2. You can specify up to three match evaluations per condition.

3. You can specify up to five match evaluations per rule.

Refer [ALB documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html#rule-condition-types) for more details.

!!!example
- rule-path1:
- rule-path1:
- Host is www.example.com OR anno.example.com
- Path is /path1
- rule-path2:
Expand Down Expand Up @@ -455,7 +455,7 @@ Access control for LoadBalancer can be controlled with following annotations:
- if same listen-port is defined by multiple Ingress within IngressGroup, inbound-cidrs should only be defined on one of the Ingress.

!!!note "Default"

- `0.0.0.0/0` will be used if the IPAddressType is "ipv4"
- `0.0.0.0/0` and `::/0` will be used if the IPAddressType is "dualstack"

Expand Down Expand Up @@ -506,7 +506,7 @@ ALB supports authentication with Cognito or OIDC. See [Authenticate Users Using
```
alb.ingress.kubernetes.io/auth-type: cognito
```

- <a name="auth-idp-cognito">`alb.ingress.kubernetes.io/auth-idp-cognito`</a> specifies the cognito idp configuration.

!!!tip ""
Expand All @@ -518,7 +518,7 @@ ALB supports authentication with Cognito or OIDC. See [Authenticate Users Using
```

- <a name="auth-idp-oidc">`alb.ingress.kubernetes.io/auth-idp-oidc`</a> specifies the oidc idp configuration.

!!!tip ""
You need to create an [secret](https://kubernetes.io/docs/concepts/configuration/secret/) within the same namespace as Ingress to hold your OIDC clientID and clientSecret. The format of secret is as below:
```yaml
Expand All @@ -538,12 +538,12 @@ ALB supports authentication with Cognito or OIDC. See [Authenticate Users Using
```

- <a name="auth-on-unauthenticated-request">`alb.ingress.kubernetes.io/auth-on-unauthenticated-request`</a> specifies the behavior if the user is not authenticated.

!!!info "options:"
* **authenticate**: try authenticate with configured IDP.
* **deny**: return an HTTP 401 Unauthorized error.
* **allow**: allow the request to be forwarded to the target.

!!!example
```
alb.ingress.kubernetes.io/auth-on-unauthenticated-request: authenticate
Expand All @@ -557,7 +557,7 @@ ALB supports authentication with Cognito or OIDC. See [Authenticate Users Using
* **profile**
* **openid**
* **aws.cognito.signin.user.admin**

!!!example
```
alb.ingress.kubernetes.io/auth-scope: 'email openid'
Expand All @@ -569,7 +569,7 @@ ALB supports authentication with Cognito or OIDC. See [Authenticate Users Using
```
alb.ingress.kubernetes.io/auth-session-cookie: custom-cookie
```

- <a name="auth-session-timeout">`alb.ingress.kubernetes.io/auth-session-timeout`</a> specifies the maximum duration of the authentication session, in seconds

!!!example
Expand Down Expand Up @@ -680,7 +680,7 @@ SSL support can be controlled with following annotations:
!!!tip ""
The first certificate in the list will be added as default certificate. And remaining certificate will be added to the optional certificate list.
See [SSL Certificates](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html#https-listener-certificates) for more details.

!!!tip "Certificate Discovery"
TLS certificates for ALB Listeners can be automatically discovered with hostnames from Ingress resources. See [Certificate Discovery](cert_discovery.md) for instructions.

Expand All @@ -693,7 +693,7 @@ SSL support can be controlled with following annotations:
```
alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:us-west-2:xxxxx:certificate/cert1,arn:aws:acm:us-west-2:xxxxx:certificate/cert2,arn:aws:acm:us-west-2:xxxxx:certificate/cert3
```

- <a name="ssl-policy">`alb.ingress.kubernetes.io/ssl-policy`</a> specifies the [Security Policy](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html#describe-ssl-policies) that should be assigned to the ALB, allowing you to control the protocol and ciphers.

!!!example
Expand All @@ -712,7 +712,7 @@ Custom attributes to LoadBalancers and TargetGroups can be controlled with follo
!!!note ""
- If `deletion_protection.enabled=true` is in annotation, the controller will not be able to delete the ALB during reconciliation. Once the attribute gets edited to `deletion_protection.enabled=false` during reconciliation, the deployer will force delete the resource.
- Please note, if the deletion protection is not enabled via annotation (e.g. via AWS console), the controller still deletes the underlying resource.

!!!example
- enable access log to s3
```
Expand Down Expand Up @@ -766,7 +766,7 @@ The AWS Load Balancer Controller automatically applies following tags to the AWS
In addition, you can use annotations to specify additional tags

- <a name="tags">`alb.ingress.kubernetes.io/tags`</a> specifies additional tags that will be applied to AWS resources created.
In case of target group, the controller will merge the tags from the ingress and the backend service giving precedence
In case of target group, the controller will merge the tags from the ingress and the backend service giving precedence
to the values specified on the service when there is conflict.

!!!example
Expand Down Expand Up @@ -801,3 +801,4 @@ In addition, you can use annotations to specify additional tags
!!!example
```alb.ingress.kubernetes.io/shield-advanced-protection: 'true'
```