diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index 1348a7b81..cf83114cc 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -46,6 +46,11 @@ 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 technical details of the corresponding `Stage` resource type, +refer to [Working with Stages](./30-how-to-guides/14-working-with-stages.md). +::: + ### What is Freight? **Freight** is Kargo's second most important concept. A single "piece of @@ -85,400 +90,6 @@ A **promotion** is a request to move a piece of freight into a specified stage. Each of Kargo's fundamental concepts maps directly onto a custom Kubernetes resource type. -### `Stage` Resources - -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: - -* Requested freight - -* Promotion template - -* Verification - -The following sections will explore each of these in greater detail. - -#### Requested Freight - -The `spec.requestedFreight` field is used to describe one or more "types" of -`Freight`, as specified by an `origin`, that the `Stage`'s promotion process, as -specified by `spec.promotionTemplate`, will operate on, and the acceptable -sources from which to obtain that `Freight`. Those sources may include the -origin itself (e.g. a `Warehouse`) and/or any number of "upstream" `Stage` -resources. - -:::info -`Warehouse`s are the only type of origin at present, but it is anticipated that -future versions of Kargo will introduce additional origin types. This is why -"types" of `Freight` are described by an `origin` field having `kind` and `name` -subfields instead of being described only by the name of a `Warehouse`. -::: - -For each `Stage`, the Kargo controller will periodically check for `Freight` -resources that are newly available for promotion to that `Stage`. - -When a `Stage` accepts `Freight` directly from its origin, _all_ new `Freight` -created by that origin (e.g. a `Warehouse` ) are immediately available for -promotion to that `Stage`. - -When a `Stage` accepts `Freight` from one or more "upstream" `Stage` resources, -`Freight` is considered available for promotion to that `Stage` only after being -_verified_ in at least one of the upstream `Stage`s. Alternatively, users with -adequate permissions may manually _approve_ `Freight` for promotion to any given -`Stage` without requiring upstream verification. - -:::tip -Explicit approvals are a useful method for applying the occasional "hotfix" -without waiting for a `Freight` resource to traverse the entirety of a pipeline. -::: - -In the following example, the `test` `Stage` requests `Freight` that has -originated from the `my-warehouse` `Warehouse` and indicates that it will accept -new `Freight` _directly_ from that origin: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Stage -metadata: - name: test - namespace: kargo-demo -spec: - requestedFreight: - - origin: - kind: Warehouse - name: my-warehouse - sources: - direct: true - # ... -``` - -In this example, the `uat` `Stage` requests `Freight` that has originated from -the `my-warehouse` `Warehouse`, but indicates that it will accept such `Freight` -only after it has been _verified_ in the `test` `Stage`: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Stage -metadata: - name: uat - namespace: kargo-demo -spec: - requestedFreight: - - origin: - kind: Warehouse - name: my-warehouse - sources: - stages: - - test - # ... -``` - -Stages may also request `Freight` from multiple sources. The following example -illustrates a `Stage` that requests `Freight` from both a `microservice-a` and -`microservice-b` `Warehouse`: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Stage -metadata: - name: test - namespace: kargo-demo -spec: - requestedFreight: - - origin: - kind: Warehouse - name: microservice-a - sources: - direct: true - - origin: - kind: Warehouse - name: microservice-b - sources: - direct: true - # ... -``` - -:::tip -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. -::: - -#### Promotion Templates - -The `spec.promotionTemplate` field is used to describe _how_ to transition -`Freight` into the `Stage`. The `spec.promotionTemplate.spec.steps` field describes -the discrete steps of a promotion process in detail. - -In the following, very common example, the `promotionTemplate` describes steps -to: - -1. Clone a Git repository containing Kubernetes manifests and Kustomize - configuration, checking out two different branches to two different - directories. - -1. Clears the contents of one working tree, with intentions to fully replace its - contents. - -1. Runs the equivalent of `kustomize edit set image` to update a - `kustomization.yaml` file with a reference to an updated - `public.ecr.aws/nginx/nginx` container image. - -1. Renders the updated manifests using the equivalent of `kustomize build`. - -1. Commits the updated manifests and pushes them to the `stage/test` of the - remote repository. - -1. Forces Argo CD to sync the `kargo-demo-test` application to the latest commit - of the `stage/test` branch. - -```yaml -promotionTemplate: - spec: - steps: - - uses: git-clone - config: - repoURL: https://github.com/example/repo.git - checkout: - - fromFreight: true - path: ./src - - branch: stage/test - create: true - path: ./out - - uses: git-clear - config: - path: ./out - - uses: kustomize-set-image - as: update-image - config: - path: ./src/base - images: - - image: public.ecr.aws/nginx/nginx - - uses: kustomize-build - config: - path: ./src/stages/test - outPath: ./out - - uses: git-commit - as: commit - config: - path: ./out - messageFromSteps: - - update-image - - uses: git-push - config: - path: ./out - targetBranch: stage/test - - uses: argocd-update - config: - apps: - - name: kargo-demo-test - sources: - - repoURL: https://github.com/example/repo.git - desiredCommitFromStep: commit -``` - -__For complete documentation of all of Kargo's built-in promotion steps, refer -to the [Promotion Steps Reference](./35-references/10-promotion-steps.md).__ - -#### Verifications - -The `spec.verification` field is used to describe optional verification -processes that should be executed after a `Promotion` has successfully deployed -`Freight` to a `Stage`, and if applicable, after the `Stage` has reached a -healthy state. - -Verification processes are defined through _references_ to one or more -[Argo Rollouts `AnalysisTemplate` resources](https://argoproj.github.io/argo-rollouts/features/analysis/) -that reside in the same `Project`/`Namespace` as the `Stage` resource. - -:::info -Argo Rollouts `AnalysisTemplate` resources (and the `AnalysisRun` resources that -are spawned from them) were intentionally built to be re-usable in contexts -other than Argo Rollouts. Re-using this resource type to define verification -processes means those processes benefit from this rich and battle-tested feature -of Argo Rollouts. -::: - -The following example depicts a `Stage` resource that references an -`AnalysisTemplate` named `kargo-demo` to validate the `test` `Stage` after any -successful `Promotion`: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Stage -metadata: - name: test - namespace: kargo-demo -spec: - # ... - verification: - analysisTemplates: - - name: kargo-demo -``` - -It is also possible to specify additional labels, annotations, and arguments -that should be applied to `AnalysisRun` resources spawned from the referenced -`AnalysisTemplate`: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Stage -metadata: - name: test - namespace: kargo-demo -spec: - # ... - verification: - analysisTemplates: - - name: kargo-demo - analysisRunMetadata: - labels: - foo: bar - annotations: - bat: baz - args: - - name: foo - value: bar -``` - -An `AnalysisTemplate` could be as simple as the following, which merely executes -a Kubernetes `Job` that is defined inline: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: AnalysisTemplate -metadata: - name: kargo-demo - namespace: kargo-demo -spec: - metrics: - - name: test - provider: - job: - metadata: - spec: - backoffLimit: 1 - template: - spec: - containers: - - name: test - image: alpine:latest - command: - - sleep - - "10" - restartPolicy: Never -``` - -:::note -Please consult the -[relevant sections](https://argoproj.github.io/argo-rollouts/features/analysis/) -of the Argo Rollouts documentation for comprehensive coverage of the full range -of `AnalysisTemplate` capabilities. -::: - -#### Status - -A `Stage` resource's `status` field records: - -* The current phase of the `Stage` resource's lifecycle. - -* Information about the last `Promotion` and any in-progress `Promotion`. - -* History of `Freight` that has been deployed to the `Stage` (from most to - least recent) along with the results of any associated verification processes. - -* The health status of any associated Argo CD `Application` resources. - -For example: - -```yaml -status: - freightHistory: - - id: 101bca5b0e18ca7913978a1da956308d2544f741 - items: - Warehouse/my-warehouse: - commits: - - healthCheckCommit: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e - id: 961cfaedbc53aacdb65110028839a2c1c281290d - repoURL: https://github.com/example/kargo-demo.git - images: - - digest: sha256:b2487a28589657b318e0d63110056e11564e73b9fd3ec4c4afba5542f9d07d46 - repoURL: public.ecr.aws/nginx/nginx - tag: 1.27.0 - name: 666209fd9755a1e48bec6b27f5f447747410dd9e - origin: - kind: Warehouse - name: my-warehouse - verificationHistory: - - analysisRun: - name: test.01j2w7aknhf3j7jteyqs72hnbg.101bca5 - namespace: kargo-demo-09 - phase: Successful - finishTime: "2024-07-15T22:13:57Z" - id: 5535a484-bbd0-4f12-8cf4-be2c8e0041c9 - phase: Successful - startTime: "2024-07-15T22:13:34Z" - health: - argoCDApps: - - healthStatus: - status: Healthy - name: kargo-demo-09-test - namespace: argocd - syncStatus: - revision: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e - status: Synced - status: Healthy - lastPromotion: - finishedAt: "2024-07-15T22:13:25Z" - freight: - commits: - - healthCheckCommit: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e - id: 961cfaedbc53aacdb65110028839a2c1c281290d - repoURL: https://github.com/example/kargo-demo.git - name: 666209fd9755a1e48bec6b27f5f447747410dd9e - origin: - kind: Warehouse - name: kargo-demo - name: test.01j2w7a15cxjjgejresfyw6ysp.666209f - status: - finishedAt: "2024-07-15T22:13:25Z" - freight: - commits: - - healthCheckCommit: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e - id: 961cfaedbc53aacdb65110028839a2c1c281290d - repoURL: https://github.com/example/kargo-demo.git - name: 666209fd9755a1e48bec6b27f5f447747410dd9e - origin: - kind: Warehouse - name: kargo-demo - freightCollection: - id: 101bca5b0e18ca7913978a1da956308d2544f741 - items: - Warehouse/kargo-demo: - commits: - - healthCheckCommit: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e - id: 961cfaedbc53aacdb65110028839a2c1c281290d - repoURL: https://github.com/example/kargo-demo.git - name: 666209fd9755a1e48bec6b27f5f447747410dd9e - origin: - kind: Warehouse - name: kargo-demo - verificationHistory: - - analysisRun: - name: test.01j2w7aknhf3j7jteyqs72hnbg.101bca5 - namespace: kargo-demo-09 - phase: "" - id: 5535a484-bbd0-4f12-8cf4-be2c8e0041c9 - phase: Pending - startTime: "2024-07-15T22:13:34Z" - phase: Succeeded - observedGeneration: 1 - phase: Steady -``` - ### `Freight` Resources Each piece of Kargo freight is represented by a Kubernetes resource of type diff --git a/docs/docs/30-how-to-guides/14-working-with-stages.md b/docs/docs/30-how-to-guides/14-working-with-stages.md new file mode 100644 index 000000000..1d82c53b7 --- /dev/null +++ b/docs/docs/30-how-to-guides/14-working-with-stages.md @@ -0,0 +1,591 @@ +--- +description: Learn how to work effectively with Stages +sidebar_label: Working with Stages +--- + +# Working with Stages + +Each Kargo Stage is represented by a Kubernetes resource of type `Stage`. + +## The `Stage` Resource Type + +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: + +* Requested Freight + +* Promotion template + +* Verification + +The following sections will explore each of these `spec` sections as well as `status` in greater detail. + +### Requested Freight + +The `spec.requestedFreight` field is used to describe one or more "types" of +`Freight`, as specified by an `origin`, that the `Stage`'s promotion process, as +specified by `spec.promotionTemplate`, will operate on, and the acceptable +sources from which to obtain that `Freight`. Those sources may include the +origin itself (e.g. a `Warehouse`) and/or any number of "upstream" `Stage` +resources. + +:::info +`Warehouse`s are the only type of origin at present, but it is anticipated that +future versions of Kargo will introduce additional origin types. This is why +"types" of `Freight` are described by an `origin` field having `kind` and `name` +subfields instead of being described only by the name of a `Warehouse`. +::: + +For each `Stage`, the Kargo controller will periodically check for `Freight` +resources that are newly available for promotion to that `Stage`. + +When a `Stage` accepts `Freight` directly from its origin, _all_ new `Freight` +created by that origin (e.g. a `Warehouse` ) are immediately available for +promotion to that `Stage`. + +When a `Stage` accepts `Freight` from one or more "upstream" `Stage` resources, +`Freight` is considered available for promotion to that `Stage` only after being +_verified_ in at least one of the upstream `Stage`s. Alternatively, users with +adequate permissions may manually _approve_ `Freight` for promotion to any given +`Stage` without requiring upstream verification. + +:::tip +Explicit approvals are a useful method for applying the occasional "hotfix" +without waiting for a `Freight` resource to traverse the entirety of a pipeline. +::: + +In the following example, the `test` `Stage` requests `Freight` that has +originated from the `my-warehouse` `Warehouse` and indicates that it will accept +new `Freight` _directly_ from that origin: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Stage +metadata: + name: test + namespace: kargo-demo +spec: + requestedFreight: + - origin: + kind: Warehouse + name: my-warehouse + sources: + direct: true + # ... +# ... +``` + +In this example, the `uat` `Stage` requests `Freight` that has originated from +the `my-warehouse` `Warehouse`, but indicates that it will accept such `Freight` +only after it has been _verified_ in the `test` `Stage`: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Stage +metadata: + name: uat + namespace: kargo-demo +spec: + requestedFreight: + - origin: + kind: Warehouse + name: my-warehouse + sources: + stages: + - test + # ... +``` + +Stages may also request `Freight` from multiple sources. The following example +illustrates a `Stage` that requests `Freight` from both a `microservice-a` and +`microservice-b` `Warehouse`: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Stage +metadata: + name: test + namespace: kargo-demo +spec: + requestedFreight: + - origin: + kind: Warehouse + name: microservice-a + sources: + direct: true + - origin: + kind: Warehouse + name: microservice-b + sources: + direct: true + # ... +``` + +:::tip +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. + +__This is _advanced_ configuration. If you're very new to Kargo +and requesting `Freight` from multiple origins, you probably +didn't mean to.__ +::: + +### Promotion Templates + +The `spec.promotionTemplate` field is used to describe _how_ to transition +`Freight` into the `Stage`. The `spec.promotionTemplate.steps` field describes +the discrete steps of a promotion process in detail. + +In the following, very common example, the `promotionTemplate` describes steps +to: + +1. Clone a Git repository containing Kubernetes manifests and Kustomize + configuration, checking out two different branches to two different + directories. + +1. Clears the contents of one working tree, with intentions to fully replace its + contents. + +1. Runs the equivalent of `kustomize edit set image` to update a + `kustomization.yaml` file with a reference to an updated + `public.ecr.aws/nginx/nginx` container image. + +1. Renders the updated manifests using the equivalent of `kustomize build`. + +1. Commits the updated manifests and pushes them to the `stage/test` of the + remote repository. + +1. Forces Argo CD to sync the `kargo-demo-test` application to the latest commit + of the `stage/test` branch. + +```yaml +promotionTemplate: + spec: + vars: + - name: gitopsRepo + value: https://github.com/example/repo.git + - name: imageRepo + value: public.ecr.aws/nginx/nginx + - name: srcPath + value: ./src + - name: outPath + value: ./out + - name: targetBranch + value: stage/${{ ctx.stage }} + steps: + - uses: git-clone + config: + repoURL: ${{ vars.gitopsRepo }} + checkout: + - branch: main + path: ${{ vars.srcPath }} + - branch: stage/${{ ctx.stage }} + create: true + path: ${{ vars.outPath }} + - uses: git-clear + config: + path: ${{ vars.outPath }} + - uses: kustomize-set-image + as: update-image + config: + path: ${{ vars.srcPath }}/base + images: + - image: ${{ vars.imageRepo }} + - uses: kustomize-build + config: + path: ${{ vars.srcPath }}/stages/${{ ctx.stage }} + outPath: ${{ vars.outPath }}/manifests.yaml + - uses: git-commit + as: commit + config: + path: ${{ vars.outPath }} + messageFromSteps: + - update-image + - uses: git-push + config: + path: ${{ vars.outPath }} + branch: ${{ vars.targetBranch }} + - uses: argocd-update + config: + apps: + - name: kargo-demo-${{ ctx.stage }} + sources: + - repoURL: ${{ vars.gitopsRepo }} + desiredRevision: ${{ outputs.commit.commit }} +``` + +:::info +For complete documentation of all Kargo's built-in promotion steps, refer +to the [Promotion Steps Reference](../35-references/10-promotion-steps.md). +::: + +### Verifications + +The `spec.verification` field is used to describe optional verification +processes that should be executed after a `Promotion` has successfully deployed +`Freight` to a `Stage`, and if applicable, after the `Stage` has reached a +healthy state. + +Verification processes are defined through _references_ to one or more +[Argo Rollouts `AnalysisTemplate` resources](https://argoproj.github.io/argo-rollouts/features/analysis/) +that reside in the same `Project`/`Namespace` as the `Stage` resource. + +:::info +Argo Rollouts `AnalysisTemplate` resources (and the `AnalysisRun` resources that +are spawned from them) were intentionally built to be re-usable in contexts +other than Argo Rollouts. Re-using this resource type to define verification +processes means those processes benefit from this rich and battle-tested feature +of Argo Rollouts. +::: + +The following example depicts a `Stage` resource that references an +`AnalysisTemplate` named `kargo-demo` to validate the `test` `Stage` after any +successful `Promotion`: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Stage +metadata: + name: test + namespace: kargo-demo +spec: + # ... + verification: + analysisTemplates: + - name: kargo-demo +``` + +It is also possible to specify additional labels, annotations, and arguments +that should be applied to `AnalysisRun` resources spawned from the referenced +`AnalysisTemplate`: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Stage +metadata: + name: test + namespace: kargo-demo +spec: + # ... + verification: + analysisTemplates: + - name: kargo-demo + analysisRunMetadata: + labels: + foo: bar + annotations: + bat: baz + args: + - name: foo + value: bar +``` + +An `AnalysisTemplate` could be as simple as the following, which merely executes +a Kubernetes `Job` that is defined inline: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: AnalysisTemplate +metadata: + name: kargo-demo + namespace: kargo-demo +spec: + metrics: + - name: test + provider: + job: + metadata: + spec: + backoffLimit: 1 + template: + spec: + containers: + - name: test + image: alpine:latest + command: + - sleep + - "10" + restartPolicy: Never +``` + +:::note +Please consult the +[relevant sections](https://argoproj.github.io/argo-rollouts/features/analysis/) +of the Argo Rollouts documentation for comprehensive coverage of the full range +of `AnalysisTemplate` capabilities. +::: + +### Status + +The `status` field of a `Stage` resource records: + + * Conditions containing the last observations of the `Stage`'s current state. + + * The current phase of the `Stage`'s lifecycle (distilled from the conditions). + + * Details about the last `Promotion` and any in-progress `Promotion`. + + * History of `Freight` that has been deployed to the `Stage` (from most to + least recent) along with the results of any associated verification processes. + + * The health status of related Argo CD `Application` resources. + +For example: + +```yaml +status: + freightHistory: + - id: 101bca5b0e18ca7913978a1da956308d2544f741 + items: + Warehouse/my-warehouse: + commits: + - healthCheckCommit: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e + id: 961cfaedbc53aacdb65110028839a2c1c281290d + repoURL: https://github.com/example/kargo-demo.git + images: + - digest: sha256:b2487a28589657b318e0d63110056e11564e73b9fd3ec4c4afba5542f9d07d46 + repoURL: public.ecr.aws/nginx/nginx + tag: 1.27.0 + name: 666209fd9755a1e48bec6b27f5f447747410dd9e + origin: + kind: Warehouse + name: my-warehouse + verificationHistory: + - analysisRun: + name: test.01j2w7aknhf3j7jteyqs72hnbg.101bca5 + namespace: kargo-demo + phase: Successful + finishTime: "2024-07-15T22:13:57Z" + id: 5535a484-bbd0-4f12-8cf4-be2c8e0041c9 + phase: Successful + startTime: "2024-07-15T22:13:34Z" + health: + argoCDApps: + - healthStatus: + status: Healthy + name: kargo-demo-test + namespace: argocd + syncStatus: + revision: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e + status: Synced + status: Healthy + lastPromotion: + finishedAt: "2024-07-15T22:13:25Z" + freight: + commits: + - healthCheckCommit: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e + id: 961cfaedbc53aacdb65110028839a2c1c281290d + repoURL: https://github.com/example/kargo-demo.git + name: 666209fd9755a1e48bec6b27f5f447747410dd9e + origin: + kind: Warehouse + name: kargo-demo + name: test.01j2w7a15cxjjgejresfyw6ysp.666209f + status: + finishedAt: "2024-07-15T22:13:25Z" + freight: + commits: + - healthCheckCommit: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e + id: 961cfaedbc53aacdb65110028839a2c1c281290d + repoURL: https://github.com/example/kargo-demo.git + name: 666209fd9755a1e48bec6b27f5f447747410dd9e + origin: + kind: Warehouse + name: kargo-demo + freightCollection: + id: 101bca5b0e18ca7913978a1da956308d2544f741 + items: + Warehouse/kargo-demo: + commits: + - healthCheckCommit: 111eaf55aa41f21bb9bb707ba1baa748b83ec51e + id: 961cfaedbc53aacdb65110028839a2c1c281290d + repoURL: https://github.com/example/kargo-demo.git + name: 666209fd9755a1e48bec6b27f5f447747410dd9e + origin: + kind: Warehouse + name: kargo-demo + verificationHistory: + - analysisRun: + name: test.01j2w7aknhf3j7jteyqs72hnbg.101bca5 + namespace: kargo-demo + phase: "" + id: 5535a484-bbd0-4f12-8cf4-be2c8e0041c9 + phase: Pending + startTime: "2024-07-15T22:13:34Z" + phase: Succeeded + observedGeneration: 1 + phase: Steady +``` + +## Interacting with Stages + +Kargo provides tools to manage Stages using either its UI or +CLI. This section explains how to handle Stages effectively through both interfaces. + +:::info +Users with credentials for and sufficient permissions within the Kargo control plane's Kubernetes cluster can also manage `Stage` resources using `kubectl`. +::: + +### Creating a Stage + + + + +1. Navigate to your Project in the Kargo UI and locate the action menu in the upper right corner of the pipeline: + + ![create-stage](../../static/img/create-stage.png) + +1. Click the magic wand icon to open the dropdown, then select Create Stage. + + A form will appear to input details for a new `Stage`: + + ![create-stage](../../static/img/create-stage-2.png) + +1. Complete the form with the necessary details and submit it. + + The new `Stage` will be added to the pipeline, connected to other + `Stage`s based on your configuration: + + ![create-stage](../../static/img/create-stage-3.png) + + + + + +1. Define the `Stage` in a YAML file, for example: + + ```yaml + apiVersion: kargo.akuity.io/v1alpha1 + kind: Stage + metadata: + name: + namespace: + spec: + ### Add your Stage specifications here + ``` + +1. Save the file and run: + + ```shell + kargo create -f + ``` + +1. Verify the creation by listing `Stage`s: + + ```shell + kargo get stage --project + ``` + + + + +### Promoting Freight to a Stage + +:::note +For comprehensive guidance on promoting `Freight` to a `Stage`, refer to [Working with Promotions](../15-concepts.md#promotion-resources). +::: + +### Deleting a Stage + + + + +1. Select the `Stage` you want to remove. + +1. Click Delete in the upper right corner of the pop-up window: + + ![delete-stage](../../static/img/delete-stage.png) + + + + + +To delete a `Stage` using the CLI, run: + +```shell +kargo delete stage --project +``` + + + + +### Refreshing a Stage + +Refreshing a `Stage` triggers its reconciliation process, which +includes checking for any newly-completed Promotions, queueing +up the next, pending Promotion, when applicable, and executing +any applicable health check processes. + + + + +1. Select the `Stage` you want to refresh. + +1. Click Refresh in the top-right corner of the pop-up window: + + ![refresh-stage](../../static/img/refresh-stage.png) + + + + + +To refresh a `Stage`, run: + +```shell +kargo refresh stage --project +``` + + + + +### Reverifying a Stage's Current Freight + +Verification processes, which run automatically following each successful Promotion, +can also be re-run on-demand. This is useful for re-attempting a failed verification +process or just to validate that applications within the `Stage` are performing +as desired. + + + + +1. Select the `Stage` you want to reverify and click Reverify at the top of the menu: + + ![verify-stage](../../static/img/reverify-freight.png) + + :::note + If you wish to stop the in-progress verification, you can click Abort Verification. + ::: + +1. To check the `Stage`s where the `Freight` has been successfully verified, return to + the Freight Timeline and select the `Freight`. Verified `Stage` names will appear under VERIFIED IN: + + ![verify-stage](../../static/img/verified-in.png) + + + + + +1. To rerun verification using the CLI run: + + ```shell + kargo verify stage --project + ``` + + If you want to *stop* this ongoing verification process, use: + + ```shell + kargo verify stage --project --abort + ``` +1. To check the `Stage`s where the `Freight` has been successfully verified, run: + + ```shell + kargo get freight \ + --project \ + --output jsonpath-as-json={.status} + ``` + + + diff --git a/docs/static/img/create-stage-2.png b/docs/static/img/create-stage-2.png new file mode 100644 index 000000000..e888a7856 Binary files /dev/null and b/docs/static/img/create-stage-2.png differ diff --git a/docs/static/img/create-stage-3.png b/docs/static/img/create-stage-3.png new file mode 100644 index 000000000..e676a1b87 Binary files /dev/null and b/docs/static/img/create-stage-3.png differ diff --git a/docs/static/img/create-stage.png b/docs/static/img/create-stage.png new file mode 100644 index 000000000..7041e9c95 Binary files /dev/null and b/docs/static/img/create-stage.png differ diff --git a/docs/static/img/delete-stage.png b/docs/static/img/delete-stage.png new file mode 100644 index 000000000..5a10336f1 Binary files /dev/null and b/docs/static/img/delete-stage.png differ diff --git a/docs/static/img/refresh-stage.png b/docs/static/img/refresh-stage.png new file mode 100644 index 000000000..ef955819b Binary files /dev/null and b/docs/static/img/refresh-stage.png differ diff --git a/docs/static/img/reverify-freight.png b/docs/static/img/reverify-freight.png new file mode 100644 index 000000000..6c5c784aa Binary files /dev/null and b/docs/static/img/reverify-freight.png differ diff --git a/docs/static/img/verified-in.png b/docs/static/img/verified-in.png new file mode 100644 index 000000000..2035a421f Binary files /dev/null and b/docs/static/img/verified-in.png differ