diff --git a/content/en/docs/concepts/services-networking/ingress.md b/content/en/docs/concepts/services-networking/ingress.md index 5f4837fa29..4fb7a2c215 100644 --- a/content/en/docs/concepts/services-networking/ingress.md +++ b/content/en/docs/concepts/services-networking/ingress.md @@ -219,25 +219,98 @@ of the controller that should implement the class. {{< codenew file="service/networking/external-lb.yaml" >}} -IngressClass resources contain an optional parameters field. This can be used to -reference additional implementation-specific configuration for this class. +The `.spec.parameters` field of an IngressClass lets you reference another +resource that provides configuration related to that IngressClass. -#### Namespace-scoped parameters +The specific type of parameters to use depends on the ingress controller +that you specify in the `.spec.controller` field of the IngressClass. +### IngressClass scope + +Depending on your ingress controller, you may be able to use parameters +that you set cluster-wide, or just for one namespace. + +{{< tabs name="tabs_ingressclass_parameter_scope" >}} +{{% tab name="Cluster" %}} +The default scope for IngressClass parameters is cluster-wide. + +If you set the `.spec.parameters` field and don't set +`.spec.parameters.scope`, or if you set `.spec.parameters.scope` to +`Cluster`, then the IngressClass refers to a cluster-scoped resource. +The `kind` (in combination the `apiGroup`) of the parameters +refers to a cluster-scoped API (possibly a custom resource), and +the `name` of the parameters identifies a specific cluster scoped +resource for that API. + +For example: +```yaml +--- +apiVersion: networking.k8s.io/v1 +kind: IngressClass +metadata: + name: external-lb-1 +spec: + controller example.com/ingress-controller + parameters: + # The parameters for this IngressClass are specified in an + # ClusterIngressParameter (API group k8s.example.net) named + # "external-config-1". This definition tells Kubernetes to + # look for a cluster-scoped parameter resource. + scope: Cluster + apiGroup: k8s.example.net + kind: ClusterIngressParameter + name: external-config +``` +{{% /tab %}} +{{% tab name="Namespaced" %}} {{< feature-state for_k8s_version="v1.23" state="stable" >}} -`Parameters` field has a `scope` and `namespace` field that can be used to -reference a namespace-specific resource for configuration of an Ingress class. -`Scope` field defaults to `Cluster`, meaning, the default is cluster-scoped -resource. Setting `Scope` to `Namespace` and setting the `Namespace` field -will reference a parameters resource in a specific namespace: +If you set the `.spec.parameters` field and set +`.spec.parameters.scope` to `Namespace`, then the IngressClass refers +to a namespaced-scoped resource. You must also set the `namespace` +field within `.spec.parameters` to the namespace that contains +the parameters you want to use. -Namespace-scoped parameters avoid the need for a cluster-scoped CustomResourceDefinition -for a parameters resource. This further avoids RBAC-related resources -that would otherwise be required to grant permissions to cluster-scoped -resources. +The `kind` (in combination the `apiGroup`) of the parameters +refers to a namespaced API (for example: ConfigMap), and +the `name` of the parameters identifies a specific resource +in the namespace you specified in `namespace`. -{{< codenew file="service/networking/namespaced-params.yaml" >}} +Namespace-scoped parameters help the cluster operator delegate control over the +configuration (for example: load balancer settings, API gateway definition) +that is used for a workload. If you used a cluster-scoped parameter then either: + +- the cluster operator team needs to approve a different team's changes every + time there's a new configuration change being applied. +- the cluster operator must define specific access controls, such as + [RBAC](/docs/reference/access-authn-authz/rbac/) roles and bindings, that let + the application team make changes to the cluster-scoped parameters resource. + +The IngressClass API itself is always cluster-scoped. + +Here is an example of an IngressClass that refers to parameters that are +namespaced: +```yaml +--- +apiVersion: networking.k8s.io/v1 +kind: IngressClass +metadata: + name: external-lb-2 +spec: + controller example.com/ingress-controller + parameters: + # The parameters for this IngressClass are specified in an + # IngressParameter (API group k8s.example.com) named "external-config", + # that's in the "external-configuration" configuration namespace. + scope: Namespace + apiGroup: k8s.example.com + kind: IngressParameter + namespace: external-configuration + name: external-config +``` + +{{% /tab %}} +{{< /tabs >}} ### Deprecated annotation