Merge pull request #30707 from sftim/20211201_tweak_ingressclass_params

Present scope for IngressClass params using tabs

Author: k8s-ci-robot

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`.
+
+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
+```
 
-{{< codenew file="service/networking/namespaced-params.yaml" >}}
+{{% /tab %}}
+{{< /tabs >}}
 
 ### Deprecated annotation