docs: working with stages documentation #2608
Conversation
✅ Deploy Preview for docs-kargo-akuity-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 #2608 +/- ##
=======================================
Coverage 50.92% 50.92%
=======================================
Files 279 279
Lines 25180 25180
=======================================
Hits 12823 12823
Misses 11666 11666
Partials 691 691 ☔ View full report in Codecov by Sentry. |
fykaa
force-pushed
the
docs-kargo-verify-command
branch
from
23c0239
to
2410cc3
Compare
|
This feels misplaced. Scanning the rest of the concepts doc, there are no other occurrences of demonstrating CLI commands. I think we should keep this page focused on concepts and how they map to CRDs. This raises the question of where this documentation of |
✅ Deploy Preview for docs-kargo-io ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| sidebar_label: Working with stage | ||
| --- | ||
|
|
||
| # Working With Stage |
There was a problem hiding this comment.
| # Working With Stage | |
| # Working With Stages |
There was a problem hiding this comment.
See this comment on another PR.
This aligns nicely with what I was suggesting there.
Doubling down on that, I think there are parts of the concepts doc that should move to this new page.
There was a problem hiding this comment.
Working With Stages
Just wondering, we want to call it "Working with Stages" because usually there will be more than 1 Stage user will be working with. Should we also rename "Working with Freight" to "Working with Freights" for keeping it consistent?
There was a problem hiding this comment.
No. Grammatically, "Freight" is a mass noun. This is why you may often see phrases like "a piece of Freight" or "two pieces of Freight" to add units where none are otherwise specified.
Not everyone is aware of this, so you'll doubtlessly encounter places in the code or docs where "Freights" is used, but it is grammatically incorrect. It may also appear in generated code because the tools in question don't understand mass nouns.
As far as documentation is concerned, we should strive for grammatical correctness when we can.
| To manage this verification process for `Stage`s you can use the `kargo verify` command. It allows you to rerun or abort the verification of a `Stage`'s current `Freight`. | ||
|
|
||
| To rerun the verification for `test` `Stage`: | ||
| ```shell | ||
| kargo verify stage --project=kargo-demo test | ||
| ``` | ||
|
|
||
| If you need to stop an ongoing verification process in a `Stage`, you can use the `--abort` flag: | ||
| ```shell | ||
| kargo verify stage --project=kargo-demo test --abort | ||
| ``` |
There was a problem hiding this comment.
This contains details regarding the kargo verify command.
Instead of separating CRD and CLI information, as we discussed in the previous meeting, I have put it back with other information from the Verification section.
There was a problem hiding this comment.
This still feels misplaced. Everything up to this point in the page has discussed the structure of the Stage type and now, all of the sudden, we're jumping into CLI usage. And then after this, we're right back to discussing structure. It doesn't fit.
See this comment about improving how the page is organized.
| ## Refresh | ||
|
|
||
| Refreshing a `Stage` helps update its state based on any new changes in `Freight` or configuration. By refreshing, you can ensure that the `Stage` reflects the latest deployment status or artifact updates. | ||
|
|
||
| ```shell | ||
| kargo refresh stage --project=kargo-demo staging | ||
| ``` | ||
|
|
||
| Running this command updates the `staging` `Stage` of the `kargo-demo` project to reflect the most recent `Freight` or configuration changes. |
There was a problem hiding this comment.
This contains details regarding the refresh command.
If this does not need to be documented, please let me know.
There was a problem hiding this comment.
It's worth documenting, but as noted in other comments, let's pull verification details down to here as well and also add docs for other important Stage-related commands.
Signed-off-by: Faeka Ansari <[email protected]>
Signed-off-by: Faeka Ansari <[email protected]>
Signed-off-by: Faeka Ansari <[email protected]>
fykaa
force-pushed
the
docs-kargo-verify-command
branch
from
f28e5bd
to
b012ab9
Compare
Signed-off-by: Faeka Ansari <[email protected]>
Signed-off-by: Kent Rancourt <[email protected]>
Signed-off-by: Kent Rancourt <[email protected]>
docs/docs/15-concepts.md
Outdated
| @@ -46,6 +46,10 @@ directed acyclic graph to describe a delivery pipeline. Typically, such a | |||
| pipeline may feature a "test" or "dev" stage as its starting point, with one or | |||
| more "prod" stages at the end. | |||
|
|
|||
| :::note | |||
| For more information on the Stage Resource, refer to [Working with Stages](./30-how-to-guides/14-working-with-stages.md). | |||
There was a problem hiding this comment.
| For more information on the Stage Resource, refer to [Working with Stages](./30-how-to-guides/14-working-with-stages.md). | |
| For technical details of the corresponding `Stage` resource type, refer to [Working with Stages](./30-how-to-guides/14-working-with-stages.md). |
| @@ -0,0 +1,421 @@ | |||
| --- | |||
| description: Learn how to work effectively with stages | |||
| sidebar_label: Working with stages | |||
There was a problem hiding this comment.
| sidebar_label: Working with stages | |
| sidebar_label: Working with Stages |
| # Working With Stages | ||
|
|
||
| Each Kargo Stage is represented by a Kubernetes resource of type `Stage`. | ||
|
|
There was a problem hiding this comment.
| ## The `Stage` Resource Type | |
Adding this fixes a couple problems:
- The heading levels are off by one throughout the doc, but adding this makes them right.
- This page now fundamentally covers two things that are deserving of separate sections:
- Important info on how a
Stageis structured - How to interact with them
- Important info on how a
There was a problem hiding this comment.
I see, so
- The Stage resource type includes the Stage's structure, such as requestedFreight, promotionTemplate, Verifications, status.
- Interacting with Stage will cover Refresh and verification
|
|
||
| Each Kargo Stage is represented by a Kubernetes resource of type `Stage`. | ||
|
|
||
| A `Stage` resource's `spec` field decomposes into three main areas of concern: |
There was a problem hiding this comment.
| A `Stage` resource's `spec` field decomposes into three main areas of concern: | |
| Like most Kubernetes resources, a `Stage` is composed of a user-defined `spec` field and a system-populated `status` field. | |
| A `Stage` resource's `spec` field is itself composed of three main areas of concern: |
|
|
||
| * Verification | ||
|
|
||
| The following sections will explore each of these in greater detail. |
There was a problem hiding this comment.
| The following sections will explore each of these in greater detail. | |
| The following sections will explore each these `spec` sections as well as `status` in greater detail. |
| By requesting `Freight` from multiple sources, a `Stage` can effectively | ||
| participate in _multiple pipelines_ that may each deliver different collections | ||
| of artifacts independently of the others. At present, this is most useful for | ||
| the delivery of microservices that are developed and deployed in parallel, | ||
| although other uses of this feature are anticipated in the future. |
There was a problem hiding this comment.
| By requesting `Freight` from multiple sources, a `Stage` can effectively | |
| participate in _multiple pipelines_ that may each deliver different collections | |
| of artifacts independently of the others. At present, this is most useful for | |
| the delivery of microservices that are developed and deployed in parallel, | |
| although other uses of this feature are anticipated in the future. | |
| By requesting `Freight` from multiple sources, a `Stage` can effectively | |
| participate in _multiple pipelines_ that may each deliver different collections | |
| of artifacts independently of the others. |
Removing this because we're already seeing this used in a number of different ways.
There was a problem hiding this comment.
Do we want to mention other use cases as well, including microservices, to showcase the broader applicability? Or should we keep it more general and let users infer potential use cases on their own?
| observedGeneration: 1 | ||
| phase: Steady | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Right here seems to be the right place to add something like ## Interacting with Stages.
You can show how to create, delete, and refresh Stages. Info on promoting to a Stage probably belongs in a not-yet-written "Working with Promotions" page, so I would not include it here (but you can link to it later when it exists). Verifying the Stage's current Freight could also be discussed here. i.e. Refer back to this comment and relocate those details to this new section.
For each of create, delete, refresh, and verify, you can show how these can be accomplished with either the UI or CLI.
There was a problem hiding this comment.
Let's use tabs for separating UI instructions and CLI instructions. UI as the default.
The instructions do not need to be super in-depth. i.e. You do not need to walk the reader through defining a Stage. They've already worked their way through sections about how they are structured. That information need not be repeated. Just show the relevant commands. Likewise, you do not need to walk through the UI's Stage creation wizard. Just point out how to access it.
krancour
changed the title
Signed-off-by: Faeka Ansari <[email protected]>
fixes #2339