From 545eda182bd7687f6d034c2684d2788ac086b7c9 Mon Sep 17 00:00:00 2001 From: "Kostis (Codefresh)" <39800303+kostis-codefresh@users.noreply.github.com> Date: Fri, 3 Jan 2025 11:36:33 +0000 Subject: [PATCH 1/2] :docs: mention Downward API in docs 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..74d46933d5 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 pod 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. From 2773f3ad6e47ab1429c28bfc005c446a036caa96 Mon Sep 17 00:00:00 2001 From: "Kostis (Codefresh)" <39800303+kostis-codefresh@users.noreply.github.com> Date: Fri, 3 Jan 2025 11:42:55 +0000 Subject: [PATCH 2/2] :docs: Spelling mistakes Signed-off-by: Kostis (Codefresh) <39800303+kostis-codefresh@users.noreply.github.com> --- docs/features/ephemeral-metadata.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/features/ephemeral-metadata.md b/docs/features/ephemeral-metadata.md index 74d46933d5..a8a9dd7028 100644 --- a/docs/features/ephemeral-metadata.md +++ b/docs/features/ephemeral-metadata.md @@ -2,7 +2,7 @@ !!! important - 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 + 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. 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). @@ -22,7 +22,7 @@ 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 pod are in "preview" and only use the production instance of your Queue server +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 @@ -69,4 +69,4 @@ updated _in place_ to use the stable metadata (without recreating the pods). !!! 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. For application code apart from the Kubernetes Downward API you also need a programming library that automatically reloads configuration files when they change. + 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.