From 8061ff01ac0bf4fa1167aed6667ea01cf8705146 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Tue, 24 Dec 2024 03:21:56 +0530 Subject: [PATCH] docs: authorizing kargo stages to modify argo apps (#2921) Signed-off-by: Faeka Ansari Signed-off-by: Kent Rancourt Co-authored-by: Kent Rancourt (cherry picked from commit 011f87af218379419d5d44c29eb5d676200b5ebc) --- .../25-argo-cd-integration.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/docs/30-how-to-guides/25-argo-cd-integration.md diff --git a/docs/docs/30-how-to-guides/25-argo-cd-integration.md b/docs/docs/30-how-to-guides/25-argo-cd-integration.md new file mode 100644 index 000000000..20604f207 --- /dev/null +++ b/docs/docs/30-how-to-guides/25-argo-cd-integration.md @@ -0,0 +1,66 @@ +--- +description: Learn how to integrate Kargo Stages with Argo CD Applications. +sidebar_label: Argo CD Integration +--- + +# Argo CD Integration + +Argo CD excels at syncing Kubernetes clusters to desired state stored in +a Git repository, but lacks any concept of a "promotion", i.e. updating +the desired state of some application instance to reflect the validated +state of some other application instance. Kargo was created to orchestrate +such processes. Because such orchestration naturally entails some direct +and indirect integration with Argo CD, this page details certain key +elements of the interactions between the two systems. + +:::note +This page is a work in progress. Thank you for your patience as as we work to add more details. +::: + +## Updating Argo CD Applications + +In the course of orchestrating the transition of an application instance +from one state to another, it is common for Kargo to updated Argo CD +`Application` resources in some way. Such updates are enabled through the +use of the +[`argocd-update` promotion step](../35-references/10-promotion-steps.md#argocd-update). +Often, these updates entail little more than modifying an `Application`'s +`operation` field to force the `Application` to be synced to recently +updated desired state. + +### Authorizing Updates + +Performing updates of any kind to an `Application` resource naturally +requires Kargo to be _authorized_ to do so. Kargo controllers have the +requisite RBAC permissions to perform such updates, but being a +multi-tenant system, Kargo must also understand, internally, when it +is acceptable to utilize those broad permissions to update a specific +`Application` resource _on behalf of_ a given `Stage`. + +To enable Kargo controllers to update an Argo CD `Application` on behalf of +a given `Stage`, that `Application` must be explicitly annotated as follows: + +```yaml +kargo.akuity.io/authorized-stage: ":" +``` + +Because an annotation such as the one above could only be added to +an `Application` by a user who, themselves, is authorized to update +that `Application`, Kargo interprets the presence of such an annotation +as delegation of that user's authority to do so. + +In the following example, an `Application` has been annotated to +authorize Kargo to update it on behalf of a `Stage` named `test` +in 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 +```