docs: warehouse selection strategies #2963
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -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. | ||||||
|
There was a problem hiding this comment. It may be useful to describe the circumstances under which you might use this. It's useful for scenarios where tags incorporate a date/time stamp. With any date/time format that arranges units from most significant to least significant (for example, yyyymmdd), the lexicographically greatest tag will also be the newest. You'd typically pair this with a regex in the |
||||||
| - `NewestBuild`: Selects the image with the most recent build time. | ||||||
|
There was a problem hiding this comment. This is incredibly slow because it requires retrieval of metadata for every eligible tag. This makes it easy to blast through your registry's rate limit. This should probably come with a warning. If it must be used, it is probably best to use |
||||||
| - `SemVer`: Selects the image that best matches a semantic versioning constraint. | ||||||
|
There was a problem hiding this comment. Probably a good place to re-iterate this: |
||||||
|
|
||||||
| ### 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. | ||||||
|
There was a problem hiding this comment.
Suggested change
As with the Lexical strategy for image selection, it may we good to explain the circumstances under which this is useful. Also as with that image selection strategy, it's good to limit the acceptable format here so that you don't end up with something like |
||||||
| - `NewestFromBranch`: Selects the most recent commit from a specified branch. | ||||||
| - `NewestTag`: Selects the most recent commit associated with a tag. | ||||||
|
There was a problem hiding this comment. Not quite what it does. Unlike branches, tags are supposed to be immutable, so there should only be one commit associated with each tag. The purpose of this strategy is to select the commit associated with the newest (most recently created) tag. Again, constraining the tags that are eligible is a good idea. |
||||||
| - `SemVer`: Selects the commit that best matches a semantic versioning constraint. | ||||||
|
There was a problem hiding this comment. This selects the commit referenced by a tag that best matches the 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:`). | ||||||
| ::: | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This isn't quite what this one does. This is for people who for whatever reason are ignoring the well-established best practice of not using mutable tags like
latest.When you use this one, you must supply a value in the constaint field. That value is the name of a single "mutable" tag.
The strategy will retrieve the latest details for the image tagged that way, including new/updated digest.