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)
This commit is contained in:
Tim Bannister
2021-12-01 22:33:19 +00:00
parent 793c08e6be
commit c1af8d4c1b
@@ -219,25 +219,98 @@ of the controller that should implement the class.
{{< codenew file="service/networking/external-lb.yaml" >}} {{< codenew file="service/networking/external-lb.yaml" >}}
IngressClass resources contain an optional parameters field. This can be used to The `.spec.parameters` field of an IngressClass lets you reference another
reference additional implementation-specific configuration for this class. 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" >}} {{< feature-state for_k8s_version="v1.23" state="stable" >}}
`Parameters` field has a `scope` and `namespace` field that can be used to If you set the `.spec.parameters` field and set
reference a namespace-specific resource for configuration of an Ingress class. `.spec.parameters.scope` to `Namespace`, then the IngressClass refers
`Scope` field defaults to `Cluster`, meaning, the default is cluster-scoped to a namespaced-scoped resource. You must also set the `namespace`
resource. Setting `Scope` to `Namespace` and setting the `Namespace` field field within `.spec.parameters` to the namespace that contains
will reference a parameters resource in a specific namespace: the parameters you want to use.
Namespace-scoped parameters avoid the need for a cluster-scoped CustomResourceDefinition The `kind` (in combination the `apiGroup`) of the parameters
for a parameters resource. This further avoids RBAC-related resources refers to a namespaced API (for example: ConfigMap), and
that would otherwise be required to grant permissions to cluster-scoped the `name` of the parameters identifies a specific resource
resources. 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 ### Deprecated annotation