From a0cb4b2fddc06404c795689f55bca46286e0eaa2 Mon Sep 17 00:00:00 2001 From: Vaughn Dice Date: Thu, 20 Aug 2020 10:00:49 -0600 Subject: [PATCH 1/3] docs(101-bundle-json.md): add clarification around contentDigest value Signed-off-by: Vaughn Dice --- 101-bundle-json.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/101-bundle-json.md b/101-bundle-json.md index 3e91cf70..eb14ccff 100644 --- a/101-bundle-json.md +++ b/101-bundle-json.md @@ -314,7 +314,12 @@ The `imageType` field MUST describe the format of the image. The list of formats The `image` field MUST give a path-like or URI-like representation of the location of the image. It is REQUIRED. The expectation is that an installer should be able to locate the image (given the image type) without additional information. -The `contentDigest` field MUST contain a digest, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the `contentDigest` is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images are checksums). During bundle development, it may be ideal to omit the `contentDigest` field and/or skip validation. Once a bundle is ready to be transmitted as a thick or thin bundle, it must have a `contentDigest` field. If a `contentDigest` field is present, a runtime MUST validate the image digest prior to executing an action. If the `contentDigest` is not present, the runtime SHOULD report an error so the user is aware that there is no `contentDigest` provided. Runtimes MAY allow users to override this behavior and perform actions on bundles that do not have `contentDigest` values populated. +The `contentDigest` field MUST contain a digest, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the `contentDigest` is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images are checksums). + - The value for this field MUST be the registry-compressed digest (known as a repo digest, [image digest](https://docs.docker.com/engine/reference/commandline/images/#list-image-digests) and/or manifest digest) as opposed to the registry-independent image ID. + - During bundle development, it may be ideal to omit the `contentDigest` field and/or skip validation. Once a bundle is ready to be transmitted as a thick or thin bundle, it MUST have a `contentDigest` field. + - If a `contentDigest` field is present, a runtime MUST validate the image digest prior to executing an action + - If the `contentDigest` is not present, the runtime SHOULD report an error so the user is aware that there is no `contentDigest` provided. + - Runtimes MAY allow users to override this behavior and perform actions on bundles that do not have `contentDigest` values populated. The following OPTIONAL fields MAY be attached to an invocation image: @@ -353,7 +358,7 @@ Fields: - `description`: The description field provides additional context of the purpose of the image. - `imageType`: The `imageType` field MUST describe the format of the image. The list of formats is open-ended, but any CNAB-compliant system MUST implement `docker` and `oci`. The default is `oci`. - `image`: The REQUIRED `image` field provides a valid reference for the image. Note that SHOULD be a CAS SHA, as in the example above, not a version tag. - - `contentDigest`: MUST contain a digest of the contents of the image, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the contentDigest is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images use checksums.) + - `contentDigest`: MUST contain a registry-compressed digest of the contents of the image, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the contentDigest is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images use checksums.) - `size`: The image size in bytes - `labels`: Key/value pairs that used to specify identifying attributes of images: - `mediaType`: The media type of the image From d711d92ce7318069ea248d8ea574a7727e909875 Mon Sep 17 00:00:00 2001 From: Vaughn Dice Date: Thu, 20 Aug 2020 10:22:06 -0600 Subject: [PATCH 2/3] specify image types that apply to digest value reqs Signed-off-by: Vaughn Dice --- 101-bundle-json.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/101-bundle-json.md b/101-bundle-json.md index eb14ccff..800b3c1c 100644 --- a/101-bundle-json.md +++ b/101-bundle-json.md @@ -315,7 +315,7 @@ The `imageType` field MUST describe the format of the image. The list of formats The `image` field MUST give a path-like or URI-like representation of the location of the image. It is REQUIRED. The expectation is that an installer should be able to locate the image (given the image type) without additional information. The `contentDigest` field MUST contain a digest, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the `contentDigest` is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images are checksums). - - The value for this field MUST be the registry-compressed digest (known as a repo digest, [image digest](https://docs.docker.com/engine/reference/commandline/images/#list-image-digests) and/or manifest digest) as opposed to the registry-independent image ID. + - If the `imageType` is `oci` or `docker`, the value for this field MUST be the registry-compressed digest (known as a repo digest, [image digest](https://docs.docker.com/engine/reference/commandline/images/#list-image-digests) and/or manifest digest) as opposed to the registry-independent image ID. - During bundle development, it may be ideal to omit the `contentDigest` field and/or skip validation. Once a bundle is ready to be transmitted as a thick or thin bundle, it MUST have a `contentDigest` field. - If a `contentDigest` field is present, a runtime MUST validate the image digest prior to executing an action - If the `contentDigest` is not present, the runtime SHOULD report an error so the user is aware that there is no `contentDigest` provided. @@ -358,7 +358,7 @@ Fields: - `description`: The description field provides additional context of the purpose of the image. - `imageType`: The `imageType` field MUST describe the format of the image. The list of formats is open-ended, but any CNAB-compliant system MUST implement `docker` and `oci`. The default is `oci`. - `image`: The REQUIRED `image` field provides a valid reference for the image. Note that SHOULD be a CAS SHA, as in the example above, not a version tag. - - `contentDigest`: MUST contain a registry-compressed digest of the contents of the image, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the contentDigest is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images use checksums.) + - `contentDigest`: MUST contain a digest of the contents of the image, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the contentDigest is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images use checksums.) If the `imageType` is `oci` or `docker`, the value for this field MUST be the registry-compressed digest (known as a repo digest, [image digest](https://docs.docker.com/engine/reference/commandline/images/#list-image-digests) and/or manifest digest) as opposed to the registry-independent image ID. - `size`: The image size in bytes - `labels`: Key/value pairs that used to specify identifying attributes of images: - `mediaType`: The media type of the image From a8732567ec1978f4a24d945a484957a4c037e1c1 Mon Sep 17 00:00:00 2001 From: Vaughn Dice Date: Thu, 20 Aug 2020 10:25:01 -0600 Subject: [PATCH 3/3] create/use link reference for image digest link Signed-off-by: Vaughn Dice --- 101-bundle-json.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/101-bundle-json.md b/101-bundle-json.md index 800b3c1c..77a7627e 100644 --- a/101-bundle-json.md +++ b/101-bundle-json.md @@ -315,7 +315,7 @@ The `imageType` field MUST describe the format of the image. The list of formats The `image` field MUST give a path-like or URI-like representation of the location of the image. It is REQUIRED. The expectation is that an installer should be able to locate the image (given the image type) without additional information. The `contentDigest` field MUST contain a digest, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the `contentDigest` is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images are checksums). - - If the `imageType` is `oci` or `docker`, the value for this field MUST be the registry-compressed digest (known as a repo digest, [image digest](https://docs.docker.com/engine/reference/commandline/images/#list-image-digests) and/or manifest digest) as opposed to the registry-independent image ID. + - If the `imageType` is `oci` or `docker`, the value for this field MUST be the registry-compressed digest (known as a repo digest, [image digest][image-digest] and/or manifest digest) as opposed to the registry-independent image ID. - During bundle development, it may be ideal to omit the `contentDigest` field and/or skip validation. Once a bundle is ready to be transmitted as a thick or thin bundle, it MUST have a `contentDigest` field. - If a `contentDigest` field is present, a runtime MUST validate the image digest prior to executing an action - If the `contentDigest` is not present, the runtime SHOULD report an error so the user is aware that there is no `contentDigest` provided. @@ -358,7 +358,7 @@ Fields: - `description`: The description field provides additional context of the purpose of the image. - `imageType`: The `imageType` field MUST describe the format of the image. The list of formats is open-ended, but any CNAB-compliant system MUST implement `docker` and `oci`. The default is `oci`. - `image`: The REQUIRED `image` field provides a valid reference for the image. Note that SHOULD be a CAS SHA, as in the example above, not a version tag. - - `contentDigest`: MUST contain a digest of the contents of the image, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the contentDigest is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images use checksums.) If the `imageType` is `oci` or `docker`, the value for this field MUST be the registry-compressed digest (known as a repo digest, [image digest](https://docs.docker.com/engine/reference/commandline/images/#list-image-digests) and/or manifest digest) as opposed to the registry-independent image ID. + - `contentDigest`: MUST contain a digest of the contents of the image, in [OCI format](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests), to be used to compute the integrity of the image. The calculation of how the image matches the contentDigest is dependent upon image type. (OCI, for example, uses a Merkle tree while VM images use checksums.) If the `imageType` is `oci` or `docker`, the value for this field MUST be the registry-compressed digest (known as a repo digest, [image digest][image-digest] and/or manifest digest) as opposed to the registry-independent image ID. - `size`: The image size in bytes - `labels`: Key/value pairs that used to specify identifying attributes of images: - `mediaType`: The media type of the image @@ -1003,3 +1003,5 @@ A runtime can leverage appropriate [in-memory](https://docs.docker.com/v17.09/en A runtime may validate outputs based on schema references by the definition field. Next section: [The invocation image definition](102-invocation-image.md) + +[image-digest]: https://docs.docker.com/engine/reference/commandline/images/#list-image-digests \ No newline at end of file