diff --git a/modules/nw-ingress-label-propagation-concepts.adoc b/modules/nw-ingress-label-propagation-concepts.adoc new file mode 100644 index 000000000000..a854f5ed12d6 --- /dev/null +++ b/modules/nw-ingress-label-propagation-concepts.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * networking/routes/route-configuration.adoc + +:_mod-docs-content-type: CONCEPT +id="networking-ingress-label-propagation-concepts_{context}"] += About label propagation from Ingress to Route resources + +By default, the managed `Route` object described in the previous section does not inherit labels from the `Ingress` resource. + +You can opt-in to a feature that enables the Ingress Operator to automatically propagate labels. When enabled, the operator actively reconciles the labels on the generated `Route` resource to match the labels on the parent `Ingress` resource. This is useful for adding metadata that helps you track or manage resources, or to control specific behaviors that depend on labels. + +[IMPORTANT] +==== +When label propagation is enabled, the Ingress Operator **replaces** all labels on the managed `Route` resource with the exact set of labels from the parent `Ingress` resource. Any labels that were manually added to the `Route` resource are removed. +==== + +.Understanding the label reconciliation lifecycle +The propagation behavior is controlled by the `route.openshift.io/reconcile-labels` annotation on the `Ingress` resource. The operator's behavior changes depending on the state of this annotation: + + **Annotation not present (default)**: The operator does not sync labels from the `Ingress` resource to the `Route` resource. Any existing labels on the `Route` are preserved. + + **Annotation enabled (`route.openshift.io/reconcile-labels: "true"`)**: The operator enables label propagation. On the next reconciliation (triggered by the `Ingress` create or update event), the operator **replaces** all labels on the generated `Route` resource with the labels from the `Ingress` resource. + + **Annotation disabled (removed or value set to non-"true")**: The operator disables label propagation. The labels that currently exist on the `Route` resource are **kept** as-is, but the operator no longer syncs them with the `Ingress` resource. + + **Annotation re-enabled**: The operator resumes propagation. It will again **replace** all labels on the `Route` resource with the current labels from the `Ingress` resource. \ No newline at end of file diff --git a/modules/nw-ingress-label-propagation-enabling.adoc b/modules/nw-ingress-label-propagation-enabling.adoc new file mode 100644 index 000000000000..e5cb4e3145c1 --- /dev/null +++ b/modules/nw-ingress-label-propagation-enabling.adoc @@ -0,0 +1,82 @@ +// Module included in the following assemblies: +// +// * networking/routes/route-configuration.adoc + +:_mod-docs-content-type: PROCEDURE +[id="networking-ingress-label-propagation-enabling_{context}"] += Enabling label propagation from Ingress to Route resources + +You can enable the Ingress Operator to automatically propagate labels from an `Ingress` resource to the `Route` resource it manages. + +.Prerequisites +* You have access to an OpenShift Container Platform cluster. +* You have the `cluster-admin` role or permissions to create and edit `Ingress` resources in a project. + +.Procedure +To enable label propagation, you must add the `route.openshift.io/reconcile-labels: "true"` annotation to your `Ingress` resource.. Create or edit an `Ingress` resource manifest.. In the `metadata.annotations` section, add `route.openshift.io/reconcile-labels: "true"`.. In the `metadata.labels` section, add the labels you want to propagate. ++ +.Example `Ingress` resource with label propagation enabled +[source,yaml] +---- +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: example-ingress + annotations: + route.openshift.io/reconcile-labels: "true" <1> + labels: + app: my-app + owner: dev-team <2> +spec: + rules: + + host: example.com + + http: + paths: + + path: / + + pathType: Prefix + backend: + service: + name: example-service + port: + number: 8080 +---- +<1> The annotation that enables label propagation. +<2> These labels (`app: my-app` and `owner: dev-team`) will be propagated to the generated `Route` resource.. Apply the manifest to your cluster: ++ +[source,terminal] +---- +$ oc apply -f +----.Verification. Confirm that the labels exist on your `Ingress` resource: ++ +[source,terminal] +---- +$ oc get ingress example-ingress --show-labels +---- ++ +.Example output +[source,text] +---- +NAME CLASS HOSTS ADDRESS PORTS AGE LABELS +example-ingress example.com 80 1m app=my-app,owner=dev-team +----. Find the name of the `Route` resource generated by the Ingress Operator: ++ +[source,terminal] +---- +$ oc get route +----. Confirm that the same labels have been propagated to the `Route` resource: ++ +[source,terminal] +---- +$ oc get route --show-labels +---- ++ +.Example output +[source,text] +---- +NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD LABELS + example.com / example-service 8080 None app=my-app,owner=dev-team +---- \ No newline at end of file diff --git a/networking/ingress_load_balancing/routes/route-configuration.adoc b/networking/ingress_load_balancing/routes/route-configuration.adoc index 8f769472338e..e9c94e9f0fae 100644 --- a/networking/ingress_load_balancing/routes/route-configuration.adoc +++ b/networking/ingress_load_balancing/routes/route-configuration.adoc @@ -65,6 +65,12 @@ include::modules/nw-route-set-or-delete-http-headers.adoc[leveloffset=+1] include::modules/nw-route-specific-annotations.adoc[leveloffset=+1] +//About label propagation +include::modules/nw-ingress-label-propagation-concepts.adoc[leveloffset=+1] + +//Enabling label propagation +include::modules/nw-ingress-label-propagation-enabling.adoc[leveloffset=+1] + ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] include::modules/nw-route-admission-policy.adoc[leveloffset=+1]