docs: warehouse selection strategies #2963
Conversation
Signed-off-by: Faeka Ansari <[email protected]>
✅ Deploy Preview for docs-kargo-io ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2963 +/- ##
==========================================
- Coverage 50.92% 50.91% -0.01%
==========================================
Files 279 279
Lines 25180 25175 -5
==========================================
- Hits 12823 12818 -5
Misses 11666 11666
Partials 691 691 ☔ View full report in Codecov by Sentry. 🚨 Try these New Features:
|
Signed-off-by: Faeka Ansari <[email protected]>
I addressed this under commit 40dd06f. If it's not necessary for this PR, I can revert the commit. |
| 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. |
There was a problem hiding this comment.
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.
| 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 allowTags field to limit eligibility to just those tags that conform to the expected format. i.e. You don't want to ask the the lexicographically latest tag and end up with zzzz-my-custom-build instead of nightly-20241211.
|
|
||
| - `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. |
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 allowTags to constrain the retrieval of metadata to as few images as possible.
| - `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. |
There was a problem hiding this comment.
Probably a good place to re-iterate this:
:::info
Kargo uses [semver](https://github.com/masterminds/semver#checking-version-constraints) to handle semantic versioning constraints.
:::
| 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.
| - `Lexical`: Selects the commit with the lexicographically greatest reference. | |
| - `Lexical`: Selects the commit referenced by the lexicographically greatest tag. |
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 zzz-custom over nightly-20241211.
|
|
||
| - `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. |
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.
| - `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. |
There was a problem hiding this comment.
This selects the commit referenced by a tag that best matches the constraint.
|
This is great, overall. An additional tip is that you can find more information about how different subscription fields like relate to the different strategies by reading field-level comments in |
closes #2880This addresses the aforementioned problem in its broadest sense.
However, we would prefer to have a separate "Working with Warehouses" guide in the long run, which can be completed within this PR.