From f6c05980a4c745445df143df9687d2d75ebc3d34 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Tue, 19 Nov 2024 11:14:51 +0530 Subject: [PATCH 1/4] update-argocd Signed-off-by: Faeka Ansari --- docs/docs/35-references/10-promotion-steps.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/docs/35-references/10-promotion-steps.md b/docs/docs/35-references/10-promotion-steps.md index c92adfea3..8406ad3dd 100644 --- a/docs/docs/35-references/10-promotion-steps.md +++ b/docs/docs/35-references/10-promotion-steps.md @@ -1156,3 +1156,34 @@ Although the `argocd-update` step is the only promotion step to currently utilize this health check framework, we anticipate that future built-in and third-party promotion steps will take advantage of it as well. ::: + +### Authorizing Kargo to Update Argo CD Applications + +For Kargo `Stage`s to modify and manage Argo CD `Application` resources, +explicit authorization must be granted in the `Application` manifests. +This is achieved by including the `kargo.akuity.io/authorized-stage` annotation. + +The annotation must be formatted as follows: + +```yaml + kargo.akuity.io/authorized-stage: ":" +``` + +Here: +- `` specifies the name of the Kargo `Project`. +- `` specifies the name of the `Stage` within the `Project`. + +The following example shows how to configure an Argo CD `Application` +manifest to authorize the `test` `Stage` of the `kargo-demo` `Project`: + +```yaml + apiVersion: argoproj.io/v1alpha1 + kind: Application + metadata: + name: kargo-demo-test + namespace: argocd + annotations: + kargo.akuity.io/authorized-stage: kargo-demo:test + spec: + # Application specifications go here +``` From c7150951b4e1b37a3261a61c76ab20c675a2a82f Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Wed, 20 Nov 2024 21:01:43 +0530 Subject: [PATCH 2/4] remove separate section and add a note Signed-off-by: Faeka Ansari --- docs/docs/35-references/10-promotion-steps.md | 58 +++++++++---------- 1 file changed, 27 insertions(+), 31 deletions(-) diff --git a/docs/docs/35-references/10-promotion-steps.md b/docs/docs/35-references/10-promotion-steps.md index 8406ad3dd..9c389e9c3 100644 --- a/docs/docs/35-references/10-promotion-steps.md +++ b/docs/docs/35-references/10-promotion-steps.md @@ -986,6 +986,33 @@ an Argo CD `Application` to sync after previous steps have updated a remote branch referenced by the `Application`. This step is commonly the last step in a promotion process. +:::note + For Kargo `Stage`s to modify and manage Argo CD `Application` resources, + explicit authorization must be granted in the `Application` manifests. + This is achieved by including the `kargo.akuity.io/authorized-stage` annotation. + + The annotation must be formatted as follows: + + ```yaml + kargo.akuity.io/authorized-stage: ":" + ``` + + The following example shows how to configure an Argo CD `Application` + manifest to authorize the `test` `Stage` of the `kargo-demo` `Project`: + + ```yaml + apiVersion: argoproj.io/v1alpha1 + kind: Application + metadata: + name: kargo-demo-test + namespace: argocd + annotations: + kargo.akuity.io/authorized-stage: kargo-demo:test + spec: + # Application specifications go here + ``` +::: + ### `argocd-update` Configuration | Name | Type | Required | Description | @@ -1156,34 +1183,3 @@ Although the `argocd-update` step is the only promotion step to currently utilize this health check framework, we anticipate that future built-in and third-party promotion steps will take advantage of it as well. ::: - -### Authorizing Kargo to Update Argo CD Applications - -For Kargo `Stage`s to modify and manage Argo CD `Application` resources, -explicit authorization must be granted in the `Application` manifests. -This is achieved by including the `kargo.akuity.io/authorized-stage` annotation. - -The annotation must be formatted as follows: - -```yaml - kargo.akuity.io/authorized-stage: ":" -``` - -Here: -- `` specifies the name of the Kargo `Project`. -- `` specifies the name of the `Stage` within the `Project`. - -The following example shows how to configure an Argo CD `Application` -manifest to authorize the `test` `Stage` of the `kargo-demo` `Project`: - -```yaml - apiVersion: argoproj.io/v1alpha1 - kind: Application - metadata: - name: kargo-demo-test - namespace: argocd - annotations: - kargo.akuity.io/authorized-stage: kargo-demo:test - spec: - # Application specifications go here -``` From 1c8de0a53631d9163a9f7d0c2538500b667e9171 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Wed, 20 Nov 2024 21:50:28 +0530 Subject: [PATCH 3/4] remove indents Signed-off-by: Faeka Ansari --- docs/docs/35-references/10-promotion-steps.md | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/docs/35-references/10-promotion-steps.md b/docs/docs/35-references/10-promotion-steps.md index 9c389e9c3..246491d7c 100644 --- a/docs/docs/35-references/10-promotion-steps.md +++ b/docs/docs/35-references/10-promotion-steps.md @@ -987,30 +987,30 @@ branch referenced by the `Application`. This step is commonly the last step in a promotion process. :::note - For Kargo `Stage`s to modify and manage Argo CD `Application` resources, - explicit authorization must be granted in the `Application` manifests. - This is achieved by including the `kargo.akuity.io/authorized-stage` annotation. - - The annotation must be formatted as follows: - - ```yaml - kargo.akuity.io/authorized-stage: ":" - ``` - - The following example shows how to configure an Argo CD `Application` - manifest to authorize the `test` `Stage` of the `kargo-demo` `Project`: - - ```yaml - apiVersion: argoproj.io/v1alpha1 - kind: Application - metadata: - name: kargo-demo-test - namespace: argocd - annotations: - kargo.akuity.io/authorized-stage: kargo-demo:test - spec: - # Application specifications go here - ``` +For Kargo `Stage`s to modify and manage Argo CD `Application` resources, +explicit authorization must be granted in the `Application` manifests. +This is achieved by including the `kargo.akuity.io/authorized-stage` annotation. + +The annotation must be formatted as follows: + +```yaml +kargo.akuity.io/authorized-stage: ":" +``` + +The following example shows how to configure an Argo CD `Application` +manifest to authorize the `test` `Stage` of the `kargo-demo` `Project`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: kargo-demo-test + namespace: argocd + annotations: + kargo.akuity.io/authorized-stage: kargo-demo:test +spec: + # Application specifications go here +``` ::: ### `argocd-update` Configuration From c4626957371247b8f3282585d8257aaffa523bfe Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Thu, 21 Nov 2024 04:42:00 +0530 Subject: [PATCH 4/4] address reviews by @krancour Signed-off-by: Faeka Ansari --- docs/docs/35-references/10-promotion-steps.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/docs/35-references/10-promotion-steps.md b/docs/docs/35-references/10-promotion-steps.md index 246491d7c..f0a1f1c1d 100644 --- a/docs/docs/35-references/10-promotion-steps.md +++ b/docs/docs/35-references/10-promotion-steps.md @@ -987,16 +987,17 @@ branch referenced by the `Application`. This step is commonly the last step in a promotion process. :::note -For Kargo `Stage`s to modify and manage Argo CD `Application` resources, -explicit authorization must be granted in the `Application` manifests. -This is achieved by including the `kargo.akuity.io/authorized-stage` annotation. - -The annotation must be formatted as follows: +For an Argo CD `Application` resource to be managed by a Kargo `Stage`, +the `Application` _must_ have an annotation of the following form: ```yaml kargo.akuity.io/authorized-stage: ":" ``` +Such an annotation offers proof that a user who is themselves authorized +to update the `Application` in question has consented to a specific +`Stage` updating the `Application` as well. + The following example shows how to configure an Argo CD `Application` manifest to authorize the `test` `Stage` of the `kargo-demo` `Project`: