docs: mention the Kubernetes Downward API in the ephemeral metadata d…

…ocumentation page (#4025) * :docs: mention Downward API in docs Signed-off-by: Kostis (Codefresh) <[email protected]> * :docs: Spelling mistakes Signed-off-by: Kostis (Codefresh) <[email protected]> --------- Signed-off-by: Kostis (Codefresh) <[email protected]>
argoproj · Jan 5, 2025 · bdbb0f1 · bdbb0f1
1 parent 8a800a8
commit bdbb0f1
Showing 1 changed file with 22 additions and 8 deletions.
diff --git a/docs/features/ephemeral-metadata.md b/docs/features/ephemeral-metadata.md
@@ -2,19 +2,31 @@
 
 !!! important
 
-    Available for canary rollouts since v0.10.0
+    This is an **optional** feature of Argo Rollouts that allows you to have more visibility while a rollout is in progress. You do **NOT** need to use emphemeral metadata in order to achieve the main functionality of Argo Rollouts.
 
-!!! important
+Normally during a deployment, Argo Rollouts automatically handles the pods of the new and old versions along with their labels and their association with your traffic provider (if you use one).
+
+In some scenarios however,
 
-    Available for blue-green rollouts since v1.0
+1. You might want to annotate the pods of each version with your own custom labels
+1. You may want the application itself know when a deployment is happening 
 
-One use case is for a Rollout to label or annotate the desired/stable pods with user-defined
+
+Argo Rollouts gives you the capability to label or annotate the desired/stable pods with user-defined
 labels/annotations, for _only_ the duration which they are the desired or stable set, and for the
 labels to be updated/removed as soon as the ReplicaSet switches roles (e.g. from desired to stable).
-The use case which this enables, is to allow prometheus, wavefront, datadog queries and dashboards
+
+In the first use case this allows prometheus, wavefront, datadog queries and dashboards
 to be built, which can rely on a consistent list of labels, rather than the `rollouts-pod-template-hash`
 which is unpredictable and changing from revision to revision.
 
+In the second use case you can have your application read the labels itself using the [Kubernetes Downward API](https://kubernetes.io/docs/concepts/workloads/pods/downward-api/) and adjust
+its behavior automatically only for the duration of the canary/blue/green deployment. For example you could point your application
+to a different Queue server while the application pods are in "preview" and only use the production instance of your Queue server
+when the pods are marked as "stable". 
+
+## Using Ephemeral labels
+
 A Rollout using the canary strategy has the ability to attach ephemeral metadata to the stable or
 canary Pods using the `stableMetadata` and `canaryMetadata` fields respectively.
 
@@ -47,12 +59,14 @@ spec:
 
 During an update, the Rollout will create the desired ReplicaSet while also merging the metadata
 defined in `canaryMetadata`/`previewMetadata` to the desired ReplicaSet's `spec.template.metadata`.
-This results in all Pods of the ReplicaSet being created with the desired metadata. When the rollout
+This results in all Pods of the ReplicaSet being created with the desired metadata. 
+
+When the rollout
 becomes fully promoted, the desired ReplicaSet becomes the stable, and is updated to use the labels
 and annotations under `stableMetadata`/`activeMetadata`. The Pods of the ReplicaSet will then be
 updated _in place_ to use the stable metadata (without recreating the pods).
 
-!!! important
+!!! tip
     In order for tooling to take advantage of this feature, they would need to recognize the change in
     labels and/or annotations that happen _after_ the Pod has already started. Not all tools may detect
-    this.
+    this. For application code apart from the Kubernetes Downward API you also need a programming library that automatically reloads configuration files when they change their contents.