mirror of https://github.com/fluxcd/flux2.git
RFC: draft proposal for artifact revision fmt
Signed-off-by: Hidde Beydals <hello@hidde.co>pull/3233/head
Hidde Beydals
2 years ago
parent
6f7cdde1ba
commit
fa217b8775
@ -0,0 +1,175 @@
|
|||||||
|
# RFC-NNNN Artifact Revision format and introduction of digests
|
||||||
|
|
||||||
|
**Status:** provisional
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Status represents the current state of the RFC.
|
||||||
|
Must be one of `provisional`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
|
||||||
|
-->
|
||||||
|
|
||||||
|
**Creation date:** 2022-10-20
|
||||||
|
|
||||||
|
**Last update:** 2022-10-20
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
This RFC proposes to establish a canonical format for an `Artifact` which
|
||||||
|
points to a specific checksum (e.g. an OCI manifest digest or Git commit SHA)
|
||||||
|
of a named pointer (e.g. an OCI image tag or Git tag). In addition, it proposes
|
||||||
|
to include the algorithm name (e.g. `sha256`) as a prefix to any advertised
|
||||||
|
checksum in an `Artifact` and further referring to it as a `Digest` opposed to
|
||||||
|
a `Checksum`.
|
||||||
|
|
||||||
|
## Motivation
|
||||||
|
|
||||||
|
The current `Artifact` type's `Revision` field format is not "officially"
|
||||||
|
standardized (albeit assumed throughout our code bases), and has mostly been
|
||||||
|
derived from `GitRepository` which uses `/` as a delimiter between the named
|
||||||
|
pointer (a Git branch or tag) and a specific (SHA-1, or theoretical SHA-256)
|
||||||
|
revision.
|
||||||
|
|
||||||
|
Since the introduction of `OCIRepository` and with the recent changes around
|
||||||
|
`HelmChart` objects to allow the consumption of charts from OCI registries.
|
||||||
|
This could be seen as outdated or confusing due to the format differing from
|
||||||
|
the canonical format used by OCI, which is `<tag>@<algo>:<checksum>` (the
|
||||||
|
part after `@` formally known as a "digest") to refer to a specific version
|
||||||
|
of a tagged OCI manifest.
|
||||||
|
|
||||||
|
While also taking note that Git does not have an official canonical format for
|
||||||
|
e.g. branch references at a specific commit, and `/` has less of a symbolic
|
||||||
|
meaning than `@`. Which could be interpreted as "`<branch>` _at_
|
||||||
|
`<commit SHA>`".
|
||||||
|
|
||||||
|
In addition, with the introduction of algorithm prefixes for an `Artifact`'s
|
||||||
|
checksum. It would be possible to add support and allow user configuration of
|
||||||
|
other algorithms than SHA-256. For example SHA-384 and SHA-512, or the more
|
||||||
|
performant (parallelizable) [BLAKE3][].
|
||||||
|
|
||||||
|
Besides this, it would make it easier to implement a client that can verify the
|
||||||
|
checksum without having to resort to an assumed format or guessing
|
||||||
|
method based on the length of it, and allows for a more robust solution in
|
||||||
|
which it can continue to calculate against the algorithm of a previous
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
The inclusion of the `Artifact`'s algorithm prefix has been proposed before in
|
||||||
|
[source-controller#855](https://github.com/fluxcd/source-controller/issues/855),
|
||||||
|
with supportive response from Core Maintainers.
|
||||||
|
|
||||||
|
### Goals
|
||||||
|
|
||||||
|
- Establish a canonical format to refer to an `Artifact`'s `Revision` field
|
||||||
|
which consists of a named pointer and a specific checksum reference.
|
||||||
|
- Allow easier verification of the `Artifact`'s checksum by including an
|
||||||
|
alias for the algorithm.
|
||||||
|
- Allow configuration of the algorithm used to calculate the checksum of an
|
||||||
|
`Artifact`.
|
||||||
|
- Allow configuration of [BLAKE3][] as an alternative to SHA for calculating
|
||||||
|
checksums. This has promising performance improvements over SHA-256, which
|
||||||
|
could allow for performance improvements in large scale environments.
|
||||||
|
- Allow compatability with SemVer name references which might contain an `@`
|
||||||
|
symbol already (e.g. `package@v1.0.0@sha256:...`, opposed to OCI's
|
||||||
|
`tag:v1.0.0@sha256:...`).
|
||||||
|
|
||||||
|
### Non-Goals
|
||||||
|
|
||||||
|
- Define a canonical format for an `Artifact`'s `Revision` field which contains
|
||||||
|
a named pointer and a different reference than a checksum.
|
||||||
|
|
||||||
|
## Proposal
|
||||||
|
|
||||||
|
### Establish an Artifact Revision format
|
||||||
|
|
||||||
|
Change the format of the `Revision` field of the `source.toolkit.fluxcd.io`
|
||||||
|
Group's `Artifact` type across all `Source` kinds to contain an `@` delimiter
|
||||||
|
opposed to `/`, and include the algorithm alias as a prefix to the checksum
|
||||||
|
(creating a "digest").
|
||||||
|
|
||||||
|
```text
|
||||||
|
[ <named pointer> ] [ [ "@" ] <algo> ":" <checksum> ]
|
||||||
|
```
|
||||||
|
|
||||||
|
Where `<named pointer>` is the name of e.g. a Git branch or OCI tag,
|
||||||
|
`<checksum>` is the exact revision (e.g. a Git commit SHA or OCI manifest
|
||||||
|
digest), and `<algo>` is the alias of the algorithm used to calculate the
|
||||||
|
checksum (e.g. `sha256`). In case only a named pointer or digest is advertised,
|
||||||
|
the `@` is omitted.
|
||||||
|
|
||||||
|
For a `GitRepository`'s `Artifact` pointing towards an SHA-256 Git commit on
|
||||||
|
branch `main`, the `Revision` field value would become:
|
||||||
|
|
||||||
|
```text
|
||||||
|
main@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
|
||||||
|
```
|
||||||
|
|
||||||
|
For a `GitRepository`'s `Artifact` pointing towards a specific SHA-1 Git commit
|
||||||
|
without a defined branch or tag, the `Revision` field value would become:
|
||||||
|
|
||||||
|
```text
|
||||||
|
sha1:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
|
||||||
|
```
|
||||||
|
|
||||||
|
### Change the Artifact Checksum to a Digest
|
||||||
|
|
||||||
|
Change the format of the `Checksum` field of the `source.toolkit.fluxcd.io`
|
||||||
|
Group's `Artifact` to `Digest`, and include the alias of the algorithm used to
|
||||||
|
calculate the Artifact checksum as a prefix (creating a "digest").
|
||||||
|
|
||||||
|
```text
|
||||||
|
<algo> ":" <checksum>
|
||||||
|
```
|
||||||
|
|
||||||
|
For a `GitRepository` `Artifact`'s checksum calculated using SHA-256, the
|
||||||
|
`Digest` field value would become:
|
||||||
|
|
||||||
|
```text
|
||||||
|
sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
|
||||||
|
```
|
||||||
|
|
||||||
|
### User Stories
|
||||||
|
|
||||||
|
> As a user of the source-controller, I want to be able to see the exact
|
||||||
|
> revision of an Artifact that is being used, so that I can verify that it
|
||||||
|
> matches the expected revision.
|
||||||
|
|
||||||
|
> As a user of the notification-controller, I want to be able to see the
|
||||||
|
> exact revision a notification is referring to.
|
||||||
|
|
||||||
|
> As a Flux CLI user, I want to see the current revision of my Source in a
|
||||||
|
> listed overview.
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Optional if existing discussions and/or issues are linked in the motivation section.
|
||||||
|
-->
|
||||||
|
|
||||||
|
### Alternatives
|
||||||
|
|
||||||
|
<!--
|
||||||
|
List plausible alternatives to the proposal and explain why the proposal is superior.
|
||||||
|
|
||||||
|
This is a good place to incorporate suggestions made during discussion of the RFC.
|
||||||
|
-->
|
||||||
|
|
||||||
|
## Design Details
|
||||||
|
|
||||||
|
<!--
|
||||||
|
This section should contain enough information that the specifics of your
|
||||||
|
change are understandable. This may include API specs and code snippets.
|
||||||
|
|
||||||
|
The design details should address at least the following questions:
|
||||||
|
- How can this feature be enabled / disabled?
|
||||||
|
- Does enabling the feature change any default behavior?
|
||||||
|
- Can the feature be disabled once it has been enabled?
|
||||||
|
- How can an operator determine if the feature is in use?
|
||||||
|
- Are there any drawbacks when enabling this feature?
|
||||||
|
-->
|
||||||
|
|
||||||
|
## Implementation History
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Major milestones in the lifecycle of the RFC such as:
|
||||||
|
- The first Flux release where an initial version of the RFC was available.
|
||||||
|
- The version of Flux where the RFC graduated to general availability.
|
||||||
|
- The version of Flux where the RFC was retired or superseded.
|
||||||
|
-->
|
||||||
|
|
||||||
|
[BLAKE3]: https://github.com/BLAKE3-team/BLAKE3
|
||||||
Loading…
Reference in New Issue