Skip to content

Commit 6bf1aa9

Browse files
M00nF1shTim Bannister
M00nF1sh
and
Tim Bannister
authored
Docs update about IngressClass & new controller-level flags (#2002)
* add docs for new flags * add documentation for IngressClass & new controller-flags * Update docs/deploy/configurations.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/deploy/configurations.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/deploy/configurations.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/deploy/configurations.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/deploy/configurations.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/deploy/configurations.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/deploy/configurations.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/deploy/configurations.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> * Update docs/guide/ingress/ingress_class.md Co-authored-by: Tim Bannister <[email protected]> Co-authored-by: Tim Bannister <[email protected]>
1 parent f3e6276 commit 6bf1aa9

File tree

3 files changed

+174
-6
lines changed

3 files changed

+174
-6
lines changed

‎docs/deploy/configurations.md

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -66,13 +66,16 @@ Currently, you can set only 1 namespace to watch in this flag. See [this Kuberne
6666
|aws-region | string | [instance metadata](#instance-metadata) | AWS Region for the kubernetes cluster |
6767
|aws-vpc-id | string | [instance metadata](#instance-metadata) | AWS VPC ID for the Kubernetes cluster |
6868
|cluster-name | string | | Kubernetes cluster name|
69-
|default-tags | stringMap | | Default AWS Tags that will be applied to all AWS resources managed by this controller |
70-
|default-ssl-policy | string | ELBSecurityPolicy-2016-08 | Default SSL Policy that will be applied to all ingresses or services that do not have the SSL Policy annotation. |
71-
|enable-leader-election | boolean | true | Enable leader election for controller manager. Enabling this will ensure there is only one active controller manager. |
72-
|enable-pod-readiness-gate-inject | boolean | true | If enabled, targetHealth readiness gate will get injected to the pod spec for the matching endpoint pods. |
69+
|default-tags | stringMap | | AWS Tags that will be applied to all AWS resources managed by this controller. Specified Tags takes highest priority |
70+
|default-ssl-policy | string | ELBSecurityPolicy-2016-08 | Default SSL Policy that will be applied to all Ingresses or Services that do not have the SSL Policy annotation |
71+
|[disable-ingress-class-annotation](#disable-ingress-class-annotation) | boolean | false | Disable new usage of the `kubernetes.io/ingress.class` annotation |
72+
|[disable-ingress-group-name-annotation](#disable-ingress-group-name-annotation) | boolean | false | Disallow new use of the `alb.ingress.kubernetes.io/group.name` annotation |
73+
|enable-leader-election | boolean | true | Enable leader election for the load balancer controller manager. Enabling this will ensure there is only one active controller manager |
74+
|enable-pod-readiness-gate-inject | boolean | true | If enabled, targetHealth readiness gate will get injected to the pod spec for the matching endpoint pods |
7375
|enable-shield | boolean | true | Enable Shield addon for ALB |
7476
|enable-waf | boolean | true | Enable WAF addon for ALB |
7577
|enable-wafv2 | boolean | true | Enable WAF V2 addon for ALB |
78+
|external-managed-tags | stringList | | AWS Tag keys that will be managed externally. Specified Tags are ignored during reconciliation |
7679
|ingress-class | string | alb | Name of the ingress class this controller satisfies |
7780
|ingress-max-concurrent-reconciles | int | 3 | Maximum number of concurrently running reconcile loops for ingress |
7881
|kubeconfig | string | in-cluster config | Path to the kubeconfig file containing authorization and API server information |
@@ -85,14 +88,34 @@ Currently, you can set only 1 namespace to watch in this flag. See [this Kuberne
8588
|targetgroupbinding-max-concurrent-reconciles | int | 3 | Maximum number of concurrently running reconcile loops for targetGroupBinding |
8689
|watch-namespace | string | | Namespace the controller watches for updates to Kubernetes objects, If empty, all namespaces are watched. |
8790
|webhook-bind-port | int | 9443 | The TCP port the Webhook server binds to |
91+
|webhook-cert-dir | string | /tmp/k8s-webhook-server/serving-certs | The directory that contains the server key and certificate |
92+
|webhook-cert-file | string | tls.crt | The server certificate name |
93+
|webhook-key-file | string | tls.key | The server key name |
94+
95+
### disable-ingress-class-annotation
96+
`--disable-ingress-class-annotation` controls whether to disable new usage of the `kubernetes.io/ingress.class` annotation.
97+
98+
Once disabled:
99+
100+
* you can no longer create Ingresses with the value of the `kubernetes.io/ingress.class` annotation equal to `alb` (can be overridden via `--ingress-class` flag of this controller).
101+
102+
* you can no longer update Ingresses to set the value of the `kubernetes.io/ingress.class` annotation equal to `alb` (can be overridden via `--ingress-class` flag of this controller).
103+
104+
* you can still create Ingresses with a `kubernetes.io/ingress.class` annotation that has other values (for example: "nginx")
105+
106+
### disable-ingress-group-name-annotation
107+
`--disable-ingress-group-name-annotation` controls whether to disable new usage of `alb.ingress.kubernetes.io/group.name` annotation.
108+
109+
Once disabled:
110+
111+
* you can no longer create Ingresses with the `alb.ingress.kubernetes.io/group.name` annotation.
112+
* you can no longer alter the value of an `alb.ingress.kubernetes.io/group.name` annotation on an existing Ingress.
88113

89114

90115
### Default throttle config
91116
```
92117
WAF Regional:^AssociateWebACL|DisassociateWebACL=0.5:1,WAF Regional:^GetWebACLForResource|ListResourcesForWebACL=1:1,WAFV2:^AssociateWebACL|DisassociateWebACL=0.5:1,WAFV2:^GetWebACLForResource|ListResourcesForWebACL=1:1
93118
```
94119
95-
AWS Web Application Firewall (WAF)
96-
97120
### Instance metadata
98121
If running on EC2, the default values are obtained from the instance metadata service.

‎docs/guide/ingress/ingress_class.md

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# [IngressClass](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class)
2+
3+
Ingresses can be implemented by different controllers, often with different configuration. Each Ingress should specify a
4+
class, a reference to an IngressClass resource that contains additional configuration including the name of the
5+
controller that should implement the class. IngressClass resources contain an optional parameters field. This can be
6+
used to reference additional implementation-specific configuration for this class.
7+
For the AWS Load Balancer controller, the implementation-specific configuration is
8+
[IngressClassParams](#ingressclassparams) in the `elbv2.k8s.aws` API group.
9+
10+
!!!example
11+
- specify controller as `ingress.k8s.aws/alb` to denote Ingresses should be managed by AWS Load Balancer Controller.
12+
```
13+
apiVersion: networking.k8s.io/v1
14+
kind: IngressClass
15+
metadata:
16+
name: awesome-class
17+
spec:
18+
controller: ingress.k8s.aws/alb
19+
```
20+
- specify additional configurations by referencing an IngressClassParams resource.
21+
```
22+
apiVersion: networking.k8s.io/v1
23+
kind: IngressClass
24+
metadata:
25+
name: awesome-class
26+
spec:
27+
controller: ingress.k8s.aws/alb
28+
parameters:
29+
apiGroup: elbv2.k8s.aws
30+
kind: IngressClassParams
31+
name: awesome-class-cfg
32+
```
33+
34+
!!!tip "[default IngressClass](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-ingress-class)"
35+
You can mark a particular IngressClass as the default for your cluster. Setting the
36+
`ingressclass.kubernetes.io/is-default-class` annotation to `true` on an IngressClass resource will ensure that new
37+
Ingresses without an `ingressClassName` field specified will be assigned this default IngressClass.
38+
39+
40+
## [Deprecated `kubernetes.io/ingress.class` annotation](https://kubernetes.io/docs/concepts/services-networking/ingress/#deprecated-annotation)
41+
42+
Before the IngressClass resource and `ingressClassName` field were added in Kubernetes 1.18, Ingress classes were
43+
specified with a `kubernetes.io/ingress.class` annotation on the Ingress. This annotation was never formally defined,
44+
but was widely supported by Ingress controllers.
45+
46+
The newer `ingressClassName` field on Ingresses is a replacement for that annotation, but is not a direct equivalent.
47+
While the annotation was generally used to reference the name of the Ingress controller that should implement the
48+
Ingress, the field is a reference to an IngressClass resource that contains additional Ingress configuration, including
49+
the name of the Ingress controller.
50+
51+
!!!tip "disable `kubernetes.io/ingress.class` annotation"
52+
In order to maintain backwards-compatibility, `kubernetes.io/ingress.class` annotation is still supported currently.
53+
You can enforce IngressClass resource adoption by disable the `kubernetes.io/ingress.class` annotation via [--disable-ingress-class-annotation](../../../deploy/configurations/#disable-ingress-class-annotation) controller flag.
54+
55+
## IngressClassParams
56+
IngressClassParams is a [CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) specific to the AWS Load Balancer Controller, which can be used along with IngressClass’s parameter field.
57+
You can use IngressClassParams to enforce settings for a set of Ingresses.
58+
59+
!!!example
60+
- with scheme & ipAddressType & tags
61+
```
62+
apiVersion: elbv2.k8s.aws/v1beta1
63+
kind: IngressClassParams
64+
metadata:
65+
name: awesome-class
66+
spec:
67+
scheme: internal
68+
ipAddressType: dualstack
69+
tags:
70+
- key: org
71+
value: my-org
72+
```
73+
- with namespaceSelector
74+
```
75+
apiVersion: elbv2.k8s.aws/v1beta1
76+
kind: IngressClassParams
77+
metadata:
78+
name: awesome-class
79+
spec:
80+
namespaceSelector:
81+
matchLabels:
82+
team: team-a
83+
```
84+
- with IngressGroup
85+
```
86+
apiVersion: elbv2.k8s.aws/v1beta1
87+
kind: IngressClassParams
88+
metadata:
89+
name: awesome-class
90+
spec:
91+
group:
92+
name: my-group
93+
```
94+
95+
### IngressClassParams specification
96+
97+
#### spec.namespaceSelector
98+
`namespaceSelector` is an optional setting that follows general Kubernetes
99+
[label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors)
100+
semantics.
101+
102+
Cluster administrators can use the `namespaceSelector` field to restrict the namespaces of Ingresses that are allowed to specify the IngressClass.
103+
104+
1. If `namespaceSelector` specified, only Ingresses in selected namespaces can use IngressClasses with this parameter. The controller will refuse to reconcile for Ingresses that violates `namespaceSelector`.
105+
2. If `namespaceSelector` un-specified, all Ingresses in any namespace can use IngressClasses with this parameter.
106+
107+
#### spec.group
108+
109+
`group` is an optional setting. The only available sub-field is `group.name`.
110+
111+
Cluster administrators can use `group.name` field to denote the groupName for all Ingresses belong to this IngressClass.
112+
113+
1. If `group.name` specified, all Ingresses with this IngressClass will belong to the same IngressGroup specified and result in a single ALB.
114+
If `group.name` is not specified, Ingresses with this IngressClass can use the older / legacy `alb.ingress.kubernetes.io/group.name` annotation to specify their IngressGroup. Ingresses that belong to the same IngressClass can form different IngressGroups via that annotation.
115+
116+
#### spec.scheme
117+
118+
`scheme` is an optional setting. The available options are `internet-facing` or `internal`.
119+
120+
Cluster administrators can use the `scheme` field to restrict the scheme for all Ingresses that belong to this IngressClass.
121+
122+
1. If `scheme` specified, all Ingresses with this IngressClass will have the specified scheme.
123+
2. If `scheme` un-specified, Ingresses with this IngressClass can continue to use `alb.ingress.kubernetes.io/scheme annotation` to specify scheme.
124+
125+
#### spec.ipAddressType
126+
127+
`ipAddressType` is an optional setting. The available options are `ipv4` or `dualstack`.
128+
129+
Cluster administrators can use `ipAddressType` field to restrict the ipAddressType for all Ingresses that belong to this IngressClass.
130+
131+
1. If `ipAddressType` specified, all Ingresses with this IngressClass will have the specified ipAddressType.
132+
2. If `ipAddressType` un-specified, Ingresses with this IngressClass can continue to use `alb.ingress.kubernetes.io/ip-address-type` annotation to specify ipAddressType.
133+
134+
#### spec.tags
135+
136+
`tags` is an optional setting.
137+
138+
Cluster administrators can use `tags` field to specify the custom tags for AWS resources provisioned for all Ingresses belong to this IngressClass.
139+
140+
1. If `tags` is set, AWS resources provisioned for all Ingresses with this IngressClass will have the specified tags.
141+
2. You can also use controller-level flag `--default-tags` or `alb.ingress.kubernetes.io/tags` annotation to specify custom tags. These tags will be merged together based on tag-key. If same tag-key appears in multiple sources, the priority is as follows:
142+
1. controller-level flag `--default-tags` will have the highest priority.
143+
2. `spec.tags` in IngressClassParams will have the middle priority.
144+
3. `alb.ingress.kubernetes.io/tags` annotation will have the lowest priority.

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ nav:
1818
- Ingress:
1919
- Annotations: guide/ingress/annotations.md
2020
- Specification: guide/ingress/spec.md
21+
- IngressClass: guide/ingress/ingress_class.md
2122
- Certificate Discovery: guide/ingress/cert_discovery.md
2223
- Service:
2324
- NLB-IP mode: guide/service/nlb_ip_mode.md

0 commit comments

Comments
 (0)