From 05655087cdb4e12c156bc028fb712cdcbe70d6cb Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Mon, 30 Sep 2024 17:51:15 +0530 Subject: [PATCH 1/6] add kargo verify doc Signed-off-by: Faeka Ansari --- docs/docs/15-concepts.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index 677fff62a..c5ed32e29 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -379,6 +379,22 @@ of the Argo Rollouts documentation for comprehensive coverage of the full range of `AnalysisTemplate` capabilities. ::: +**Using the `kargo verify` Command** + +The `kargo verify` command can be used to manage this verification process for `Stage`s. It allows you to rerun or abort the verification of a `Stage`'s current `Freight`. + +For example: + +- To rerun the verification for `test` `Stage`: + ```shell + kargo verify stage --project=kargo-demo test + ``` + +- To stop an ongoing verification process in the `test` `Stage`: + ```shell + kargo verify stage --project=kargo-demo test --abort + ``` + #### Status A `Stage` resource's `status` field records: From 61898e5f6c5da7194ecdfc42d6be7a61ceb8099c Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Mon, 28 Oct 2024 19:33:04 +0530 Subject: [PATCH 2/6] working-on-stage doc Signed-off-by: Faeka Ansari --- docs/docs/15-concepts.md | 16 ------- .../30-how-to-guides/14-working-with-stage.md | 42 +++++++++++++++++++ 2 files changed, 42 insertions(+), 16 deletions(-) create mode 100644 docs/docs/30-how-to-guides/14-working-with-stage.md diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index c5ed32e29..677fff62a 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -379,22 +379,6 @@ of the Argo Rollouts documentation for comprehensive coverage of the full range of `AnalysisTemplate` capabilities. ::: -**Using the `kargo verify` Command** - -The `kargo verify` command can be used to manage this verification process for `Stage`s. It allows you to rerun or abort the verification of a `Stage`'s current `Freight`. - -For example: - -- To rerun the verification for `test` `Stage`: - ```shell - kargo verify stage --project=kargo-demo test - ``` - -- To stop an ongoing verification process in the `test` `Stage`: - ```shell - kargo verify stage --project=kargo-demo test --abort - ``` - #### Status A `Stage` resource's `status` field records: diff --git a/docs/docs/30-how-to-guides/14-working-with-stage.md b/docs/docs/30-how-to-guides/14-working-with-stage.md new file mode 100644 index 000000000..e68e0df7e --- /dev/null +++ b/docs/docs/30-how-to-guides/14-working-with-stage.md @@ -0,0 +1,42 @@ +--- +description: Learn how to work effectively with stages +sidebar_label: Working with stage +--- + +# Working With Stage + +The `Stage` is a core concept in Kargo's application orchestration, representing a structured checkpoint in a deployment pipeline where application components (known as `Freight`—such as versioned artifacts like container images or Kubernetes manifests) are processed before moving to the next `Stage`. + +- **Requested Freight**: Defines which `Freight` should be moved into the `Stage`. +- **Promotion Templates**: Specifies the steps required to progress `Freight` from one `Stage` to another. +- **Verification**: Configures checks to ensure deployments meet specific criteria. + +:::info +To understand the basic principles of Kargo `Stage`s, please review the [Concepts documentation](../concepts). +::: + +## 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. + +## Verification + +Verification allows you to confirm that each `Freight` within a `Stage` meets the necessary requirements before promotion. Kargo provides the `kargo verify` command to manage this verification process, offering options to rerun or abort ongoing verifications. + +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 +``` + +This command stops the active verification in the `test` `Stage` of the `kargo-demo` project. From b012ab9aa20f552c2ea4c15fe904983f3f2594f7 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Tue, 29 Oct 2024 18:54:55 +0530 Subject: [PATCH 3/6] reposition && update stage information from key concepts Signed-off-by: Faeka Ansari --- docs/docs/15-concepts.md | 398 +---------------- .../30-how-to-guides/14-working-with-stage.md | 42 -- .../14-working-with-stages.md | 420 ++++++++++++++++++ 3 files changed, 424 insertions(+), 436 deletions(-) delete mode 100644 docs/docs/30-how-to-guides/14-working-with-stage.md create mode 100644 docs/docs/30-how-to-guides/14-working-with-stages.md diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index 677fff62a..7105ae1f4 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -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) in the How-to guides. +::: + ### What is Freight? **Freight** is Kargo's second most important concept. A single "piece of @@ -85,400 +89,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.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-stage.md b/docs/docs/30-how-to-guides/14-working-with-stage.md deleted file mode 100644 index e68e0df7e..000000000 --- a/docs/docs/30-how-to-guides/14-working-with-stage.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -description: Learn how to work effectively with stages -sidebar_label: Working with stage ---- - -# Working With Stage - -The `Stage` is a core concept in Kargo's application orchestration, representing a structured checkpoint in a deployment pipeline where application components (known as `Freight`—such as versioned artifacts like container images or Kubernetes manifests) are processed before moving to the next `Stage`. - -- **Requested Freight**: Defines which `Freight` should be moved into the `Stage`. -- **Promotion Templates**: Specifies the steps required to progress `Freight` from one `Stage` to another. -- **Verification**: Configures checks to ensure deployments meet specific criteria. - -:::info -To understand the basic principles of Kargo `Stage`s, please review the [Concepts documentation](../concepts). -::: - -## 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. - -## Verification - -Verification allows you to confirm that each `Freight` within a `Stage` meets the necessary requirements before promotion. Kargo provides the `kargo verify` command to manage this verification process, offering options to rerun or abort ongoing verifications. - -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 -``` - -This command stops the active verification in the `test` `Stage` of the `kargo-demo` project. 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..e048600af --- /dev/null +++ b/docs/docs/30-how-to-guides/14-working-with-stages.md @@ -0,0 +1,420 @@ +--- +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`. + +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.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. +::: + +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 +``` + +### 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 +``` + +## 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. From a197d677075f584e6c688fc59b70f861457e07e6 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Wed, 13 Nov 2024 18:12:14 +0530 Subject: [PATCH 4/6] fix link Signed-off-by: Faeka Ansari --- docs/docs/15-concepts.md | 2 +- docs/docs/30-how-to-guides/14-working-with-stages.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index 7105ae1f4..0e8ab7022 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -47,7 +47,7 @@ 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) in the How-to guides. +For more information on the Stage Resource, refer to [Working with Stages](./30-how-to-guides/14-working-with-stages.md). ::: ### What is Freight? 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 index e048600af..71a09cee0 100644 --- a/docs/docs/30-how-to-guides/14-working-with-stages.md +++ b/docs/docs/30-how-to-guides/14-working-with-stages.md @@ -199,7 +199,7 @@ 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).__ +to the [Promotion Steps Reference](../35-references/10-promotion-steps.md).__ ### Verifications From 200739c50b6734e93339c75807f4893adc7abe0e Mon Sep 17 00:00:00 2001 From: Kent Rancourt Date: Fri, 15 Nov 2024 11:48:23 -0500 Subject: [PATCH 5/6] Apply suggestions from code review Signed-off-by: Kent Rancourt --- .../14-working-with-stages.md | 387 +++++++++--------- 1 file changed, 194 insertions(+), 193 deletions(-) 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 index 71a09cee0..85bccbb92 100644 --- a/docs/docs/30-how-to-guides/14-working-with-stages.md +++ b/docs/docs/30-how-to-guides/14-working-with-stages.md @@ -9,7 +9,7 @@ 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 +* Requested Freight * Promotion template @@ -59,15 +59,16 @@ new `Freight` _directly_ from that origin: apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: -name: test -namespace: kargo-demo + name: test + namespace: kargo-demo spec: -requestedFreight: -- origin: -kind: Warehouse -name: my-warehouse -sources: -direct: true + requestedFreight: + - origin: + kind: Warehouse + name: my-warehouse + sources: + direct: true + # ... # ... ``` @@ -79,17 +80,17 @@ only after it has been _verified_ in the `test` `Stage`: apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: -name: uat -namespace: kargo-demo + name: uat + namespace: kargo-demo spec: -requestedFreight: -- origin: -kind: Warehouse -name: my-warehouse -sources: -stages: -- test -# ... + requestedFreight: + - origin: + kind: Warehouse + name: my-warehouse + sources: + stages: + - test + # ... ``` Stages may also request `Freight` from multiple sources. The following example @@ -100,21 +101,21 @@ illustrates a `Stage` that requests `Freight` from both a `microservice-a` and apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: -name: test -namespace: kargo-demo + 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 -# ... + requestedFreight: + - origin: + kind: Warehouse + name: microservice-a + sources: + direct: true + - origin: + kind: Warehouse + name: microservice-b + sources: + direct: true + # ... ``` :::tip @@ -155,47 +156,47 @@ 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 + 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 @@ -228,13 +229,13 @@ successful `Promotion`: apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: -name: test -namespace: kargo-demo + name: test + namespace: kargo-demo spec: -# ... -verification: -analysisTemplates: -- name: kargo-demo + # ... + verification: + analysisTemplates: + - name: kargo-demo ``` It is also possible to specify additional labels, annotations, and arguments @@ -245,21 +246,21 @@ that should be applied to `AnalysisRun` resources spawned from the referenced apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: -name: test -namespace: kargo-demo + name: test + namespace: kargo-demo spec: -# ... -verification: -analysisTemplates: -- name: kargo-demo -analysisRunMetadata: -labels: -foo: bar -annotations: -bat: baz -args: -- name: foo -value: bar + # ... + 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 @@ -269,25 +270,25 @@ a Kubernetes `Job` that is defined inline: apiVersion: argoproj.io/v1alpha1 kind: AnalysisTemplate metadata: -name: kargo-demo -namespace: kargo-demo + 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 + metrics: + - name: test + provider: + job: + metadata: + spec: + backoffLimit: 1 + template: + spec: + containers: + - name: test + image: alpine:latest + command: + - sleep + - "10" + restartPolicy: Never ``` :::note @@ -326,87 +327,87 @@ 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 + 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 ``` ## Refresh From 838a146a1e7e82f535a6eca7d15b5b9c427c0194 Mon Sep 17 00:00:00 2001 From: Kent Rancourt Date: Fri, 15 Nov 2024 11:49:55 -0500 Subject: [PATCH 6/6] Update docs/docs/30-how-to-guides/14-working-with-stages.md Signed-off-by: Kent Rancourt --- docs/docs/30-how-to-guides/14-working-with-stages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 85bccbb92..f110b22d4 100644 --- a/docs/docs/30-how-to-guides/14-working-with-stages.md +++ b/docs/docs/30-how-to-guides/14-working-with-stages.md @@ -5,7 +5,7 @@ sidebar_label: Working with stages # Working With Stages -Each Kargo stage is represented by a Kubernetes resource of type `Stage`. +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: