From c1af8d4c1bd5ea704765e58edd1a323f96c923cd Mon Sep 17 00:00:00 2001
From: Tim Bannister <tim@scalefactory.com>
Date: Wed, 1 Dec 2021 22:33:19 +0000
Subject: [PATCH] Present scope for IngressClass params using tabs

Use tabs for the two different options that an IngressClass can use to
refer to another object, in order to specific parameters that relate to
that IngressClass:
- namespaced scope
- cluster scope (the default / historical behavior)
---
 .../concepts/services-networking/ingress.md   | 99 ++++++++++++++++---
 1 file changed, 86 insertions(+), 13 deletions(-)

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