docs: authorizing kargo stages to modify argo apps #2921
Conversation
✅ Deploy Preview for docs-kargo-io ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2921 +/- ##
==========================================
+ Coverage 49.92% 50.92% +1.00%
==========================================
Files 275 279 +4
Lines 24668 25180 +512
==========================================
+ Hits 12315 12823 +508
+ Misses 11676 11666 -10
- Partials 677 691 +14 ☔ View full report in Codecov by Sentry. 🚨 Try these New Features:
|
I'm not sure I agree with this. It has nothing to do with user permissions. We probably need to carve out a whole separate page for "Argo CD Integration". It can be very light on content for now with a notice that the page is under construction and the real content can, for now, be limited to what you're adding here. |
Signed-off-by: Faeka Ansari <faeka6@gmail.com>
fykaa
force-pushed
the
docs/add-authorized-stage-annotation
branch
from
4f203d7
to
e0a6a70
Compare
| @@ -0,0 +1,49 @@ | |||
| --- | |||
| description: Learn how to set up Argo CD to work with Kargo-managed projects. | |||
There was a problem hiding this comment.
| description: Learn how to set up Argo CD to work with Kargo-managed projects. | |
| description: Learn how to integrate Kargo Stages with Argo CD Applications. |
| annotations: | ||
| kargo.akuity.io/authorized-stage: kargo-demo:{{stage}} | ||
| spec: | ||
| # Application Specifications |
There was a problem hiding this comment.
As an ApplicationSet, the example asks the reader to understand more about Argo CD than is actually necessary for you to get your point across. The example would be more accessible as an Application.
|
|
||
| # Argo CD Integration | ||
|
|
||
| Kargo integrates seamlessly with Argo CD to facilitate a more streamlined application lifecycle management process. While Argo CD helps with deploying Kubernetes objects and synchronizing changes in the cluster, Kargo focuses on orchestrating the promotion of these changes through various `Stage`s of development, such as from `development` to `testing` and then to `production`. |
There was a problem hiding this comment.
It totally makes sense to say a bit here about Kargo's relationship to Argo CD.
I might reword this a bit for clarity. I'll come back to it.
| To enable Kargo `Stage`s to interact with and modify Argo CD applications, applications need to explicitly authorize Kargo to perform these actions. This is accomplished using the `kargo.akuity.io/authorized-stage` annotation. | ||
|
|
||
| Kargo requires the annotation in the following format: | ||
|
|
||
| ```yaml | ||
| kargo.akuity.io/authorized-stage: "<project-name>:<stage-name>" | ||
| ``` | ||
|
|
||
| This annotation signifies consent for Kargo to manage the application on behalf of the designated `Project` and `Stage`. | ||
|
|
||
| In the following example, the `ApplicationSet` manifest is configured to allow Kargo management by dynamically setting the `kargo.akuity.io/authorized-stage: kargo-demo:{{stage}}` annotation for each `Stage` (`test`, `uat`, `prod`) to ensure that each `Stage` in the `kargo-demo` `Project` is authorized to modify its respective Argo CD Application: |
There was a problem hiding this comment.
It occurs to me now that this information probably needs to be surfaced here as this is where the information is most relevant. I failed to notice prior to my suggestion of making a whole separate page for Argo CD integration.
https://main.docs.kargo.io/references/promotion-steps#argocd-update
I wouldn't scrap this PR however. I think we should continue to expand on this topic because there's a lot to say about it.
If you open a separate PR for incorporating this information into the step documentation, that can easily be merged sooner than this new page.
Signed-off-by: Faeka Ansari <faeka6@gmail.com>
closes #2440
I have made the documentation placement for the
kargo.akuity.io/authorized-stageannotation in "Managing User Permissions" section because imo it is a key component in managing permissions between Kargo and Argo CD.While I also considered options like a dedicated
annotation referenceguide or including it inkey concepts, I believe current placement is most relevant. Please let me know if this location works or if there's an alternative section recommended.