From bdbb0f17c067ad7926571ca3b41491dc574cf14d Mon Sep 17 00:00:00 2001 From: "Kostis (Codefresh)" <39800303+kostis-codefresh@users.noreply.github.com> Date: Sun, 5 Jan 2025 16:25:32 +0200 Subject: [PATCH] docs: mention the Kubernetes Downward API in the ephemeral metadata documentation page (#4025) * :docs: mention Downward API in docs Signed-off-by: Kostis (Codefresh) <39800303+kostis-codefresh@users.noreply.github.com> * :docs: Spelling mistakes Signed-off-by: Kostis (Codefresh) <39800303+kostis-codefresh@users.noreply.github.com> --------- Signed-off-by: Kostis (Codefresh) <39800303+kostis-codefresh@users.noreply.github.com> --- docs/features/ephemeral-metadata.md | 30 +++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/features/ephemeral-metadata.md b/docs/features/ephemeral-metadata.md index 346aac31d8..a8a9dd7028 100644 --- 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.