spec: show RFC-0005 format and digest in examples

Signed-off-by: Hidde Beydals <hello@hidde.co>
fluxcd · Feb 9, 2023 · c2acac8 · c2acac8
1 parent 8a25e7e
commit c2acac8
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 32 deletions.
diff --git a/docs/spec/v1beta2/buckets.md b/docs/spec/v1beta2/buckets.md
@@ -48,8 +48,8 @@ In the above example:
 - A list of object keys and their [etags](https://en.wikipedia.org/wiki/HTTP_ETag)
   in the `.spec.bucketName` bucket is compiled, while filtering the keys using
   [default ignore rules](#default-exclusions).
-- The SHA256 sum of the list is used as Artifact revision, reported
-  in-cluster in the `.status.artifact.revision` field.
+- The digest (algorithm defaults to SHA256) of the list is used as Artifact
+  revision, reported in-cluster in the `.status.artifact.revision` field.
 - When the current Bucket revision differs from the latest calculated revision,
   all objects are fetched and archived.
 - The new Artifact is reported in the `.status.artifact` field.
@@ -71,7 +71,7 @@ control over.
 
    ```console
    NAME           ENDPOINT            AGE   READY   STATUS                                                                                         
-   minio-bucket   minio.example.com   34s   True    stored artifact for revision 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+   minio-bucket   minio.example.com   34s   True    stored artifact for revision 'sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
    ```
 
 3. Run `kubectl describe bucket minio-bucket` to see the [Artifact](#artifact)
@@ -82,19 +82,21 @@ control over.
    Status:
      Artifact:
        Checksum:          72aa638abb455ca5f9ef4825b949fd2de4d4be0a74895bf7ed2338622cd12686
+       Digest:            sha256:72aa638abb455ca5f9ef4825b949fd2de4d4be0a74895bf7ed2338622cd12686
        Last Update Time:  2022-02-01T23:43:38Z
        Path:              bucket/default/minio-bucket/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.tar.gz
-       Revision:          e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+       Revision:          sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+       Size:              38099
        URL:               http://source-controller.source-system.svc.cluster.local./bucket/default/minio-bucket/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.tar.gz
      Conditions:
        Last Transition Time:  2022-02-01T23:43:38Z
-       Message:               stored artifact for revision 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+       Message:               stored artifact for revision 'sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
        Observed Generation:   1
        Reason:                Succeeded
        Status:                True
        Type:                  Ready
        Last Transition Time:  2022-02-01T23:43:38Z
-       Message:               stored artifact for revision 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+       Message:               stored artifact for revision 'sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
        Observed Generation:   1
        Reason:                Succeeded
        Status:                True
@@ -104,7 +106,7 @@ control over.
    Events:
      Type    Reason                  Age   From               Message
      ----    ------                  ----  ----               -------
-     Normal  NewArtifact             82s   source-controller  fetched 16 files from 'example'
+     Normal  NewArtifact             82s   source-controller  stored artifact with 16 fetched files from 'example' bucket
    ```
 
 ## Writing a Bucket spec
@@ -906,7 +908,7 @@ lists
 ```console
 LAST SEEN   TYPE      REASON                       OBJECT                 MESSAGE
 2m30s       Normal    NewArtifact                  bucket/<bucket-name>   fetched 16 files with revision from 'my-new-bucket'
-36s         Normal    ArtifactUpToDate             bucket/<bucket-name>   artifact up-to-date with remote revision: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+36s         Normal    ArtifactUpToDate             bucket/<bucket-name>   artifact up-to-date with remote revision: 'sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
 18s         Warning   BucketOperationFailed        bucket/<bucket-name>   bucket 'my-new-bucket' does not exist
 ```
 
@@ -936,9 +938,11 @@ metadata:
 status:
   artifact:
     checksum: cbec34947cc2f36dee8adcdd12ee62ca6a8a36699fc6e56f6220385ad5bd421a
+    digest: sha256:cbec34947cc2f36dee8adcdd12ee62ca6a8a36699fc6e56f6220385ad5bd421a
     lastUpdateTime: "2022-01-28T10:30:30Z"
     path: bucket/<namespace>/<bucket-name>/c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.tar.gz
-    revision: c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
+    revision: sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
+    size: 38099
     url: http://source-controller.<namespace>.svc.cluster.local./bucket/<namespace>/<bucket-name>/c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.tar.gz
 ```
 

diff --git a/docs/spec/v1beta2/gitrepositories.md b/docs/spec/v1beta2/gitrepositories.md
@@ -49,7 +49,7 @@ You can run this example by saving the manifest into `gitrepository.yaml`.
 
    ```console
    NAME      URL                                       AGE   READY   STATUS                                                                        
-   podinfo   https://github.com/stefanprodan/podinfo   5s    True    stored artifact for revision 'master/132f4e719209eb10b9485302f8593fc0e680f4fc'
+   podinfo   https://github.com/stefanprodan/podinfo   5s    True    stored artifact for revision 'master@sha1:132f4e719209eb10b9485302f8593fc0e680f4fc'
    ```
 
 3. Run `kubectl describe gitrepository podinfo` to see the [Artifact](#artifact)
@@ -60,19 +60,21 @@ You can run this example by saving the manifest into `gitrepository.yaml`.
    Status:
      Artifact:
        Checksum:          95e386f421272710c4cedbbd8607dbbaa019d500e7a5a0b6720bc7bebefc7bf2
+       Digest:            sha256:95e386f421272710c4cedbbd8607dbbaa019d500e7a5a0b6720bc7bebefc7bf2
        Last Update Time:  2022-02-14T11:23:36Z
        Path:              gitrepository/default/podinfo/132f4e719209eb10b9485302f8593fc0e680f4fc.tar.gz
-       Revision:          master/132f4e719209eb10b9485302f8593fc0e680f4fc
+       Revision:          master@sha1:132f4e719209eb10b9485302f8593fc0e680f4fc
+       Size:              91318
        URL:               http://source-controller.source-system.svc.cluster.local./gitrepository/default/podinfo/132f4e719209eb10b9485302f8593fc0e680f4fc.tar.gz
      Conditions:
        Last Transition Time:  2022-02-14T11:23:36Z
-       Message:               stored artifact for revision 'master/132f4e719209eb10b9485302f8593fc0e680f4fc'
+       Message:               stored artifact for revision 'master@sha1:132f4e719209eb10b9485302f8593fc0e680f4fc'
        Observed Generation:   1
        Reason:                Succeeded
        Status:                True
        Type:                  Ready
        Last Transition Time:  2022-02-14T11:23:36Z
-       Message:               stored artifact for revision 'master/132f4e719209eb10b9485302f8593fc0e680f4fc'
+       Message:               stored artifact for revision 'master@sha1:132f4e719209eb10b9485302f8593fc0e680f4fc'
        Observed Generation:   1
        Reason:                Succeeded
        Status:                True
@@ -670,7 +672,7 @@ lists
 ```console
 LAST SEEN   TYPE     REASON                OBJECT                               MESSAGE
 2m14s       Normal   NewArtifact           gitrepository/<repository-name>      stored artifact for commit 'Merge pull request #160 from stefanprodan/release-6.0.3'
-36s         Normal   ArtifactUpToDate      gitrepository/<repository-name>      artifact up-to-date with remote revision: 'master/132f4e719209eb10b9485302f8593fc0e680f4fc'
+36s         Normal   ArtifactUpToDate      gitrepository/<repository-name>      artifact up-to-date with remote revision: 'master@sha1:132f4e719209eb10b9485302f8593fc0e680f4fc'
 94s         Warning  GitOperationFailed    gitrepository/<repository-name>      failed to checkout and determine revision: unable to clone 'https://github.com/stefanprodan/podinfo': couldn't find remote ref "refs/heads/invalid"
 ```
 
@@ -700,9 +702,11 @@ metadata:
 status:
   artifact:
     checksum: e750c7a46724acaef8f8aa926259af30bbd9face2ae065ae8896ba5ee5ab832b
+    digest: sha256:e750c7a46724acaef8f8aa926259af30bbd9face2ae065ae8896ba5ee5ab832b
     lastUpdateTime: "2022-01-29T06:59:23Z"
     path: gitrepository/<namespace>/<repository-name>/c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.tar.gz
-    revision: master/363a6a8fe6a7f13e05d34c163b0ef02a777da20a
+    revision: master@sha1:363a6a8fe6a7f13e05d34c163b0ef02a777da20a
+    size: 91318
     url: http://source-controller.<namespace>.svc.cluster.local./gitrepository/<namespace>/<repository-name>/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz
 ```
 

diff --git a/docs/spec/v1beta2/helmcharts.md b/docs/spec/v1beta2/helmcharts.md
@@ -65,12 +65,14 @@ helm-controller.
 
    ```console
    Status:
-     Observed Source Artifact Revision:  83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
+     Observed Source Artifact Revision:  sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
      Artifact:
        Checksum:          6c3cc3b955bce1686036ae6822ee2ca0ef6ecb994e3f2d19eaf3ec03dcba84b3
+       Digest:            sha256:6c3cc3b955bce1686036ae6822ee2ca0ef6ecb994e3f2d19eaf3ec03dcba84b3
        Last Update Time:  2022-02-13T11:24:10Z
        Path:              helmchart/default/podinfo/podinfo-5.2.1.tgz
        Revision:          5.2.1
+       Size:              14166
        URL:               http://source-controller.flux-system.svc.cluster.local./helmchart/default/podinfo/podinfo-5.2.1.tgz
      Conditions:
        Last Transition Time:  2022-02-13T11:24:10Z
@@ -555,9 +557,11 @@ metadata:
 status:
   artifact:
     checksum: e30b95a08787de69ffdad3c232d65cfb131b5b50c6fd44295f48a078fceaa44e
+    digest: sha256:e30b95a08787de69ffdad3c232d65cfb131b5b50c6fd44295f48a078fceaa44e
     lastUpdateTime: "2022-02-10T18:53:47Z"
     path: helmchart/<source-namespace>/<chart-name>/<chart-name>-<chart-version>.tgz
     revision: 6.0.3
+    size: 14166
     url: http://source-controller.flux-system.svc.cluster.local./helmchart/<source-namespace>/<chart-name>/<chart-name>-<chart-version>.tgz
 ```
 
@@ -576,9 +580,11 @@ metadata:
 status:
   artifact:
     checksum: ee68224ded207ebb18a8e9730cf3313fa6bc1f31e6d8d3943ab541113559bb52
+    digest: sha256:ee68224ded207ebb18a8e9730cf3313fa6bc1f31e6d8d3943ab541113559bb52
     lastUpdateTime: "2022-02-28T08:07:12Z"
     path: helmchart/<source-namespace>/<chart-name>/<chart-name>-6.0.3+1.tgz
     revision: 6.0.3+1
+    size: 14166
     url: http://source-controller.flux-system.svc.cluster.local./helmchart/<source-namespace>/<chart-name>/<chart-name>-6.0.3+1.tgz
   observedGeneration: 1
   ...
@@ -600,9 +606,11 @@ metadata:
 status:
   artifact:
     checksum: 8d1f0ac3f4b0e8759a32180086f17ac87ca04e5d46c356e67f97e97616ef4718
+    digest: sha256:8d1f0ac3f4b0e8759a32180086f17ac87ca04e5d46c356e67f97e97616ef4718
     lastUpdateTime: "2022-02-28T08:07:12Z"
     path: helmchart/<source-namespace>/<chart-name>/<chart-name>-6.0.3+4e5cbb7b97d0.tgz
     revision: 6.0.3+4e5cbb7b97d0
+    size: 14166
     url: http://source-controller.flux-system.svc.cluster.local./helmchart/<source-namespace>/<chart-name>/<chart-name>-6.0.3+4e5cbb7b97d0.tgz
 ```
 

diff --git a/docs/spec/v1beta2/helmrepositories.md b/docs/spec/v1beta2/helmrepositories.md
@@ -34,9 +34,9 @@ In the above example:
 - The source-controller fetches the Helm repository index YAML every five
   minutes from `https://stefanprodan.github.io/podinfo`, indicated by the
   `.spec.interval` and `.spec.url` fields.
-- The SHA256 sum of the Helm repository index after stable sorting the entries
-  is used as Artifact revision, reported in-cluster in the
-  `.status.artifact.revision` field.
+- The digest (algorithm defaults to SHA256) of the Helm repository index after
+  stable sorting the entries is used as Artifact revision, reported in-cluster
+  in the `.status.artifact.revision` field.
 - When the current HelmRepository revision differs from the latest fetched 
   revision, it is stored as a new Artifact.
 - The new Artifact is reported in the `.status.artifact` field.
@@ -53,7 +53,7 @@ You can run this example by saving the manifest into `helmrepository.yaml`.
 
    ```console
    NAME      URL                                      AGE   READY   STATUS                                                                                         
-   podinfo   https://stefanprodan.github.io/podinfo   4s    True    stored artifact for revision '83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111'
+   podinfo   https://stefanprodan.github.io/podinfo   4s    True    stored artifact for revision 'sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111'
    ```
 
 3. Run `kubectl describe helmrepository podinfo` to see the [Artifact](#artifact)
@@ -64,19 +64,21 @@ You can run this example by saving the manifest into `helmrepository.yaml`.
    Status:
      Artifact:
        Checksum:          83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
+       Digest:            sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
        Last Update Time:  2022-02-04T09:55:58Z
        Path:              helmrepository/default/podinfo/index-83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111.yaml
-       Revision:          83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
+       Revision:          sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
+       Size:              40898
        URL:               http://source-controller.flux-system.svc.cluster.local./helmrepository/default/podinfo/index-83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111.yaml
      Conditions:
        Last Transition Time:  2022-02-04T09:55:58Z
-       Message:               stored artifact for revision '83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111'
+       Message:               stored artifact for revision 'sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111'
        Observed Generation:   1
        Reason:                Succeeded
        Status:                True
        Type:                  Ready
        Last Transition Time:  2022-02-04T09:55:58Z
-       Message:               stored artifact for revision '83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111'
+       Message:               stored artifact for revision 'sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111'
        Observed Generation:   1
        Reason:                Succeeded
        Status:                True
@@ -609,7 +611,7 @@ lists
 LAST SEEN   TYPE      REASON           OBJECT                             MESSAGE
 107s        Warning   Failed           helmrepository/<repository-name>   failed to construct Helm client: scheme "invalid" not supported
 7s          Normal    NewArtifact      helmrepository/<repository-name>   fetched index of size 30.88kB from 'https://stefanprodan.github.io/podinfo'
-3s          Normal    ArtifactUpToDate helmrepository/<repository-name>   artifact up-to-date with remote revision: '83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111'
+3s          Normal    ArtifactUpToDate helmrepository/<repository-name>   artifact up-to-date with remote revision: 'sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111'
 ```
 
 Besides being reported in Events, the reconciliation errors are also logged by
@@ -640,9 +642,11 @@ metadata:
 status:
   artifact:
     checksum: 83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
+    digest: sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
     lastUpdateTime: "2022-02-04T09:55:58Z"
     path: helmrepository/<namespace>/<repository-name>/index-83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111.yaml
-    revision: 83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
+    revision: sha256:83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111
+    size: 40898
     url: http://source-controller.flux-system.svc.cluster.local./helmrepository/<namespace>/<repository-name>/index-83a3c595163a6ff0333e0154c790383b5be441b9db632cb36da11db1c4ece111.yaml
 ```