From b6a1f9cf89e603a4be265b00b81e6975695583be Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Tue, 19 Nov 2024 19:40:54 +0530 Subject: [PATCH 1/2] update warehouse documentation to include subscription details Signed-off-by: Faeka Ansari --- docs/docs/15-concepts.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index 1348a7b81..ccbe8b58a 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -581,9 +581,28 @@ spec: Kargo uses [semver](https://github.com/masterminds/semver#checking-version-constraints) to handle semantic versioning constraints. ::: -#### Git Subscription Path Filtering +#### Image Subscription -In some cases, it may be necessary to constrain the paths within a Git +For subscriptions to container image repositories, the `imageSelectionStrategy` field specifies the method for selecting +the desired image. The available strategies are: + +- `Digest`: Selects the image with the specified digest. +- `Lexical`: Selects the image with the lexicographically greatest tag. +- `NewestBuild`: Selects the image with the most recent build time. +- `SemVer`: Selects the image that best matches a semantic versioning constraint. + +#### Git Subscription + +In subscriptions to Git repositories, the `commitSelectionStrategy` field +specifies the method for selecting the desired commit. +The available strategies are: + +- `Lexical`: Selects the commit with the lexicographically greatest reference. +- `NewestFromBranch`: Selects the most recent commit from a specified branch. +- `NewestTag`: Selects the most recent commit associated with a tag. +- `SemVer`: Selects the commit that best matches a semantic versioning constraint. + +Additionally, in some cases, it may be necessary to constrain the paths within a Git repository that a `Warehouse` will consider as triggers for `Freight` production. This is especially useful for GitOps repositories that are "monorepos" containing configuration for multiple applications. From 40dd06fd9005a9f276aadc7bf902dd94a21926b4 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Tue, 19 Nov 2024 20:00:37 +0530 Subject: [PATCH 2/2] created a separate working with warehouses docs Signed-off-by: Faeka Ansari --- docs/docs/15-concepts.md | 158 +---------------- .../16-working-with-warehouses.md | 161 ++++++++++++++++++ 2 files changed, 166 insertions(+), 153 deletions(-) create mode 100644 docs/docs/30-how-to-guides/16-working-with-warehouses.md diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index ccbe8b58a..26d18d1ec 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -76,6 +76,11 @@ A **warehouse** is a _source_ of freight. A warehouse subscribes to one or more: Anytime something new is discovered in any repository to which a warehouse subscribes, the warehouse produces a new piece of freight. +:::note +For technical details of the corresponding `Warehouse` resource type, +refer to [Working with Warehouses](./30-how-to-guides/16-working-with-warehouses.md). +::: + ### What is a Promotion? A **promotion** is a request to move a piece of freight into a specified stage. @@ -546,159 +551,6 @@ status: prod: {} ``` -### `Warehouse` Resources - -Each Kargo warehouse is represented by a Kubernetes resource of type -`Warehouse`. - -A `Warehouse` resource's most important field is its `spec.subscriptions` field, -which is used to subscribe to one or more: - -* Container image repositories - -* Git repositories - -* Helm charts repositories - -The following example shows a `Warehouse` resource that subscribes to a -container image repository and a Git repository: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Warehouse -metadata: - name: my-warehouse - namespace: kargo-demo -spec: - subscriptions: - - image: - repoURL: public.ecr.aws/nginx/nginx - semverConstraint: ^1.26.0 - - git: - repoURL: https://github.com/example/kargo-demo.git -``` -:::info -Kargo uses [semver](https://github.com/masterminds/semver#checking-version-constraints) to handle semantic versioning constraints. -::: - -#### Image Subscription - -For subscriptions to container image repositories, the `imageSelectionStrategy` field specifies the method for selecting -the desired image. The available strategies are: - -- `Digest`: Selects the image with the specified digest. -- `Lexical`: Selects the image with the lexicographically greatest tag. -- `NewestBuild`: Selects the image with the most recent build time. -- `SemVer`: Selects the image that best matches a semantic versioning constraint. - -#### Git Subscription - -In subscriptions to Git repositories, the `commitSelectionStrategy` field -specifies the method for selecting the desired commit. -The available strategies are: - -- `Lexical`: Selects the commit with the lexicographically greatest reference. -- `NewestFromBranch`: Selects the most recent commit from a specified branch. -- `NewestTag`: Selects the most recent commit associated with a tag. -- `SemVer`: Selects the commit that best matches a semantic versioning constraint. - -Additionally, in some cases, it may be necessary to constrain the paths within a Git -repository that a `Warehouse` will consider as triggers for `Freight` -production. This is especially useful for GitOps repositories that are -"monorepos" containing configuration for multiple applications. - -The paths that may or must not trigger `Freight` production may be specified -using a combination of the `includePaths` and `excludePaths` fields of a Git -repository subscription. - -The following example demonstrates a `Warehouse` with a Git repository -subscription that will only produce new `Freight` when the latest commit -(selected by the applicable commit selection strategy) contains changes in the -`apps/guestbook` directory since the last piece of `Freight` produced by the -`Warehouse`: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Warehouse -metadata: - name: my-warehouse - namespace: kargo-demo -spec: - subscriptions: - - git: - repoURL: https://github.com/example/kargo-demo.git - includePaths: - - apps/guestbook -``` - -The next example demonstrates the opposite: a `Warehouse` with a Git repository -subscription that will only produce new `Freight` when the latest commit -(selected by the applicable commit selection strategy) contains changes to paths -_other than_ the repository's `docs/` directory: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Warehouse -metadata: - name: my-warehouse - namespace: kargo-demo -spec: - subscriptions: - - git: - repoURL: https://github.com/example/kargo-demo.git - excludePaths: - - docs -``` - -`includePaths` and `excludePaths` may be combined to include a broad set of -paths and then exclude a subset of those. The following example demonstrates a -`Warehouse` with a Git repository subscription that will only produce new -`Freight` when the latest commit (selected by the applicable commit selection -strategy) contains changes _within_ the `apps/guestbook` directory _other than_ -the `apps/guestbook/README.md`: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Warehouse -metadata: - name: my-warehouse - namespace: kargo-demo -spec: - subscriptions: - - git: - repoURL: https://github.com/example/kargo-demo.git - includePaths: - - apps/guestbook - excludePaths: - - apps/guestbook/README.md -``` - -:::note -It is important to understand that new `Freight` will be produced when the -latest commit (selected by the applicable commit selection strategy) contains -_even a single change_ that is: - -1. Implicitly included via undefined `includePaths`. - -     OR - - Explicitly included via `includePaths`. - - AND - -2. Not explicitly excluded via `excludePaths`. -::: - -:::info -By default, the strings in the `includePaths` and `excludePaths` fields are -treated as exact paths to files or directories. (Selecting a directory will -implicitly select all paths within that directory.) - -Paths may _also_ be specified using glob patterns (by prefixing the string with -`glob:`) or regular expressions (by prefixing the string with `regex:` or -`regexp:`). -::: - ### `Promotion` Resources Each Kargo promotion is represented by a Kubernetes resource of type diff --git a/docs/docs/30-how-to-guides/16-working-with-warehouses.md b/docs/docs/30-how-to-guides/16-working-with-warehouses.md new file mode 100644 index 000000000..a111546b4 --- /dev/null +++ b/docs/docs/30-how-to-guides/16-working-with-warehouses.md @@ -0,0 +1,161 @@ +--- +description: Learn how to work effectively with Warehouses +sidebar_label: Working with Warehouses +--- + +# Working with Warehouses + +Each Kargo warehouse is represented by a Kubernetes resource of type +`Warehouse`. + +## The `Warehouse` Resource Type + +A `Warehouse` resource's most important field is its `spec.subscriptions` field, +which is used to subscribe to one or more: + +* Container image repositories + +* Git repositories + +* Helm charts repositories + +The following example shows a `Warehouse` resource that subscribes to a +container image repository and a Git repository: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Warehouse +metadata: + name: my-warehouse + namespace: kargo-demo +spec: + subscriptions: + - image: + repoURL: public.ecr.aws/nginx/nginx + semverConstraint: ^1.26.0 + - git: + repoURL: https://github.com/example/kargo-demo.git +``` +:::info +Kargo uses [semver](https://github.com/masterminds/semver#checking-version-constraints) to handle semantic versioning constraints. +::: + +### Image Subscription + +For subscriptions to container image repositories, the `imageSelectionStrategy` field specifies the method for selecting +the desired image. The available strategies for subscribing to an image repository are: + +- `Digest`: Selects the image with the specified digest. +- `Lexical`: Selects the image with the lexicographically greatest tag. +- `NewestBuild`: Selects the image with the most recent build time. +- `SemVer`: Selects the image that best matches a semantic versioning constraint. + +### Git Subscription + +In subscriptions to Git repositories, the `commitSelectionStrategy` field +specifies the method for selecting the desired commit. +The available strategies for subscribing to a git repository are: + +- `Lexical`: Selects the commit with the lexicographically greatest reference. +- `NewestFromBranch`: Selects the most recent commit from a specified branch. +- `NewestTag`: Selects the most recent commit associated with a tag. +- `SemVer`: Selects the commit that best matches a semantic versioning constraint. + +#### Git Subscription Path Filtering + +In some cases, it may be necessary to constrain the paths within a Git +repository that a `Warehouse` will consider as triggers for `Freight` +production. This is especially useful for GitOps repositories that are +"monorepos" containing configuration for multiple applications. + +The paths that may or must not trigger `Freight` production may be specified +using a combination of the `includePaths` and `excludePaths` fields of a Git +repository subscription. + +The following example demonstrates a `Warehouse` with a Git repository +subscription that will only produce new `Freight` when the latest commit +(selected by the applicable commit selection strategy) contains changes in the +`apps/guestbook` directory since the last piece of `Freight` produced by the +`Warehouse`: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Warehouse +metadata: + name: my-warehouse + namespace: kargo-demo +spec: + subscriptions: + - git: + repoURL: https://github.com/example/kargo-demo.git + includePaths: + - apps/guestbook +``` + +The next example demonstrates the opposite: a `Warehouse` with a Git repository +subscription that will only produce new `Freight` when the latest commit +(selected by the applicable commit selection strategy) contains changes to paths +_other than_ the repository's `docs/` directory: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Warehouse +metadata: + name: my-warehouse + namespace: kargo-demo +spec: + subscriptions: + - git: + repoURL: https://github.com/example/kargo-demo.git + excludePaths: + - docs +``` + +`includePaths` and `excludePaths` may be combined to include a broad set of +paths and then exclude a subset of those. The following example demonstrates a +`Warehouse` with a Git repository subscription that will only produce new +`Freight` when the latest commit (selected by the applicable commit selection +strategy) contains changes _within_ the `apps/guestbook` directory _other than_ +the `apps/guestbook/README.md`: + +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Warehouse +metadata: + name: my-warehouse + namespace: kargo-demo +spec: + subscriptions: + - git: + repoURL: https://github.com/example/kargo-demo.git + includePaths: + - apps/guestbook + excludePaths: + - apps/guestbook/README.md +``` + +:::note +It is important to understand that new `Freight` will be produced when the +latest commit (selected by the applicable commit selection strategy) contains +_even a single change_ that is: + +1. Implicitly included via undefined `includePaths`. + + OR + + Explicitly included via `includePaths`. + + AND + +2. Not explicitly excluded via `excludePaths`. +::: + +:::info +By default, the strings in the `includePaths` and `excludePaths` fields are +treated as exact paths to files or directories. (Selecting a directory will +implicitly select all paths within that directory.) + +Paths may _also_ be specified using glob patterns (by prefixing the string with +`glob:`) or regular expressions (by prefixing the string with `regex:` or +`regexp:`). +:::