From 5c1c9ea149f8aaedafbf2e2db37be23e5ad93899 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Fri, 8 Mar 2024 15:48:17 +0100 Subject: [PATCH 01/14] correct links --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 650cae7..918795a 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,7 @@ The following chapters provide a formal description of the format to describe so ## Central OCM project web page -Check out the main project [web page](https://ocm.software) to find out more about OCM. It is your central entry point to all kinds of ocm related [docs and guides](https://ocm.software/docoverview/context), this [spec](https://ocm.software/spec/) and all project-related [github repositories](https://github.com/open-component-model). It also offers a [Getting Started](https://ocm.software/docguides/getting-started-with-ocm) to quickly make your hands dirty with ocm, its toolset and concepts :-) +Check out the main project [web page](https://ocm.software) to find out more about OCM. It is your central entry point to all kinds of ocm related [docs and guides](https://ocm.software/docoverview/context), this [spec](https://ocm.software/spec/) and all project-related [github repositories](https://github.com/open-component-model). It also offers a [Getting Started](https://ocm.software/docs/guides/getting-started-with-ocm) to quickly make your hands dirty with ocm, its toolset and concepts :-) ## Contributing From af4fa7df8f67b243cf95b28aaa3e184b12a66c6b Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 10:36:47 +0100 Subject: [PATCH 02/14] correct links and markdown --- CONTRIBUTING.md | 4 +- README.md | 172 ++--- doc/01-model/01-model.md | 1 - doc/01-model/02-elements-toplevel.md | 19 +- doc/01-model/03-elements-sub.md | 6 +- doc/01-model/07-extensions.md | 99 ++- doc/01-model/README.md | 48 +- doc/02-processing/01-references.md | 3 +- .../{03-signing.md => 02-signing.md} | 23 +- doc/02-processing/03-signing-process.md | 111 +++ doc/02-processing/04-digest.md | 676 ------------------ doc/02-processing/04-signing-examples.md | 189 +++++ .../05-component-descriptor-normalization.md | 294 ++++++++ .../06-artifact-normalization.md | 87 +++ doc/02-processing/README.md | 57 +- doc/03-persistence/01-operations.md | 11 +- doc/03-persistence/02-mappings.md | 1 + .../00-component-descriptor/README.md | 2 +- .../00-component-descriptor/v2.md | 8 +- .../00-component-descriptor/v3.md | 3 +- doc/04-extensions/01-artifact-types/README.md | 9 +- doc/04-extensions/01-artifact-types/blob.md | 4 +- .../01-artifact-types/blueprint.md | 10 +- .../01-artifact-types/executable.md | 8 +- .../01-artifact-types/file-system.md | 22 +- doc/04-extensions/01-artifact-types/gitops.md | 7 +- .../01-artifact-types/helmchart.md | 8 +- doc/04-extensions/01-artifact-types/npm.md | 7 +- .../01-artifact-types/oci-artifact.md | 6 +- .../01-artifact-types/oci-image.md | 10 +- doc/04-extensions/01-artifact-types/sbom.md | 24 +- .../01-artifact-types/template.md | 6 +- .../01-artifact-types/toiexecutor.md | 4 +- doc/04-extensions/02-access-types/README.md | 2 +- doc/04-extensions/02-access-types/github.md | 6 +- doc/04-extensions/02-access-types/helm.md | 8 +- .../02-access-types/localblob.md | 5 +- doc/04-extensions/02-access-types/npm.md | 10 +- .../02-access-types/ociartifact.md | 8 +- doc/04-extensions/02-access-types/ociblob.md | 8 +- doc/04-extensions/02-access-types/s3.md | 6 +- .../03-storage-backends/README.md | 15 +- .../03-storage-backends/component-archive.md | 3 +- doc/04-extensions/03-storage-backends/ctf.md | 15 +- doc/04-extensions/03-storage-backends/oci.md | 12 +- doc/04-extensions/03-storage-backends/s3.md | 4 +- doc/04-extensions/04-algorithms/README.md | 2 +- .../artifact-normalization-types.md | 1 + ...ent-descriptor-normalization-algorithms.md | 4 +- .../04-algorithms/label-merge-algorithms.md | 23 +- doc/04-extensions/README.md | 42 +- doc/04-extensions/common/formatspec.md | 19 +- doc/05-guidelines/01-transport.md | 15 +- doc/05-guidelines/02-contract.md | 4 +- doc/05-guidelines/03-references.md | 4 +- doc/05-guidelines/README.md | 1 - doc/glossary.md | 68 +- doc/markdownlint.json | 5 + 58 files changed, 1163 insertions(+), 1066 deletions(-) rename doc/02-processing/{03-signing.md => 02-signing.md} (87%) create mode 100644 doc/02-processing/03-signing-process.md delete mode 100644 doc/02-processing/04-digest.md create mode 100644 doc/02-processing/04-signing-examples.md create mode 100644 doc/02-processing/05-component-descriptor-normalization.md create mode 100644 doc/02-processing/06-artifact-normalization.md create mode 100644 doc/markdownlint.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2b55ed..8858c2e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,5 @@ -Welcome to the OCM community! +# Welcome to the OCM community We welcome many different types of contributions. -Please refer to the [Contributing Guide in the Community repository](https://github.com/open-component-model/community/blob/main/CONTRIBUTING.md) for more information on how to get support from maintainers, find work to contribute, the Pull Request checklist, the Pull Request process, and other useful information on contributing to the OCM projects. \ No newline at end of file +Please refer to the [Contributing Guide in the Community repository](https://github.com/open-component-model/community/blob/main/CONTRIBUTING.md) for more information on how to get support from maintainers, find work to contribute, the Pull Request checklist, the Pull Request process, and other useful information on contributing to the OCM projects. diff --git a/README.md b/README.md index 918795a..58836d2 100644 --- a/README.md +++ b/README.md @@ -16,90 +16,90 @@ The following chapters provide a formal description of the format to describe so ## Core Parts -* 1.[Model](doc/01-model/README.md) - * 1.1.[OCM Model](doc/01-model/01-model.md#ocm-model) - * 1.1.1.[Introduction](doc/01-model/01-model.md#introduction) - * 1.1.2.[Components and Component Versions](doc/01-model/01-model.md#components-and-component-versions) - * 1.1.3.[Component Repositories](doc/01-model/01-model.md#component-repositories) - * 1.1.4.[Summary](doc/01-model/01-model.md#summary) - * 1.2.[Model Elements](doc/01-model/02-elements-toplevel.md#model-elements) - * 1.2.1.[Components and Component Versions](doc/01-model/02-elements-toplevel.md#components-and-component-versions) - * 1.2.2.[Artifacts (Resources and Sources)](doc/01-model/02-elements-toplevel.md#artifacts-resources-and-sources) - * 1.2.3.[Sources](doc/01-model/02-elements-toplevel.md#sources) - * 1.2.4.[Resources](doc/01-model/02-elements-toplevel.md#resources) - * 1.2.5.[References](doc/01-model/02-elements-toplevel.md#references) - * 1.2.6.[Summary](doc/01-model/02-elements-toplevel.md#summary) - * 1.3.[Model Elements - Fundamentals](doc/01-model/03-elements-sub.md) - * 1.3.1.[Identifiers](doc/01-model/03-elements-sub.md#identifiers) - * 1.3.2.[Access Specification](doc/01-model/03-elements-sub.md#access-specification) - * 1.3.3.[Access Types](doc/01-model/03-elements-sub.md#access-types) - * 1.3.4.[Labels](doc/01-model/03-elements-sub.md#labels) - * 1.3.5.[Repository Contexts](doc/01-model/03-elements-sub.md#repository-contexts) - * 1.3.6.[Signatures](doc/01-model/03-elements-sub.md#signatures) - * 1.3.7.[Digest Info](doc/01-model/03-elements-sub.md#digest-info) - * 1.3.8.[Signature Info](doc/01-model/03-elements-sub.md#signature-info) - * 1.4.[Example of a complete Component Version](doc/01-model/04-example.md#example-of-a-complete-component-version) - * 1.5.[Conventions](doc/01-model/06-conventions.md#conventions) - * 1.5.1.[Intended Environments](doc/01-model/06-conventions.md#intended-environments) - * 1.5.2.[Selection of Usage Scenarios](doc/01-model/06-conventions.md#selection-of-usage-scenarios) - * 1.6.[Extending the Open Component Model](doc/01-model/07-extensions.md#extending-the-open-component-model) - * 1.6.1.[Functional extensions](doc/01-model/07-extensions.md#functional-extensions) - * 1.6.2.[Semantic extensions](doc/01-model/07-extensions.md#semantic-extensions) -* 2.[Processing](doc/02-processing/README.md) - * 2.1.[Referencing](doc/02-processing/01-references.md#referencing) - * 2.1.1.[Example](doc/02-processing/01-references.md#example) - * 2.2.[Signing](doc/02-processing/03-signing.md#signing) - * 2.2.1.[Verification Procedure](doc/02-processing/03-signing.md#verification-procedure) - * 2.3.[Normalization](doc/02-processing/04-digest.md#normalization) - * 2.3.1.[Artifact Digest](doc/02-processing/04-digest.md#artifact-digest) - * 2.3.2.[Normalization Types](doc/02-processing/04-digest.md#normalization-types) - * 2.3.3.[Serialization Format](doc/02-processing/04-digest.md#serialization-format) - * 2.3.4.[Recursive Digest Calculation](doc/02-processing/04-digest.md#recursive-digest-calculation) - * 2.4.[Example](doc/02-processing/04-digest.md#example) - * 2.4.1.[Simple Component-Version](doc/02-processing/04-digest.md#simple-component-version) - * 2.4.2.[Component-Version With Reference](doc/02-processing/04-digest.md#component-version-with-reference) - * 2.5.[Component Descriptor Normalization](doc/02-processing/04-digest.md#component-descriptor-normalization) - * 2.5.1.[Relevant information in Component Descriptors](doc/02-processing/04-digest.md#relevant-information-in-component-descriptors) - * 2.5.2.[Labels](doc/02-processing/04-digest.md#labels) - * 2.5.3.[Exclude Resources from Normalization/Signing](doc/02-processing/04-digest.md#exclude-resources-from-normalizationsigning) - * 2.5.4.[Generic Normalization Format](doc/02-processing/04-digest.md#generic-normalization-format) - * 2.6.[Artifact Normalization](doc/02-processing/04-digest.md#artifact-normalization) - * 2.6.1.[Blob Representation Format for Resource Types](doc/02-processing/04-digest.md#blob-representation-format-for-resource-types) - * 2.6.2.[Interaction of Local Blobs, Access Methods, Uploaders and Media Types](doc/02-processing/04-digest.md#interaction-of-local-blobs-access-methods-uploaders-and-media-types) -* 3.[Persistence](doc/03-persistence/README.md) - * 3.1.[Model Operations](doc/03-persistence/01-operations.md#model-operations) - * 3.2.[Abstract Operations defined by the Open Component Model](doc/03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) - * 3.2.1.[Repository Operations](doc/03-persistence/01-operations.md#repository-operations) - * 3.2.2.[Access Method Operations](doc/03-persistence/01-operations.md#access-method-operations) - * 3.3.[Mappings for OCM Persistence](doc/03-persistence/02-mappings.md#mappings-for-ocm-persistence) - * 3.3.1.[Storage Backend Mappings for the Open Component Model](doc/03-persistence/02-mappings.md#storage-backend-mappings-for-the-open-component-model) +* 1. [Model](doc/01-model/README.md) + * 1.1. [OCM Model](doc/01-model/01-model.md#ocm-model) + * 1.1.1. [Introduction](doc/01-model/01-model.md#introduction) + * 1.1.2. [Components and Component Versions](doc/01-model/01-model.md#components-and-component-versions) + * 1.1.3. [Component Repositories](doc/01-model/01-model.md#component-repositories) + * 1.1.4. [Summary](doc/01-model/01-model.md#summary) + * 1.2. [Model Elements](doc/01-model/02-elements-toplevel.md#model-elements) + * 1.2.1. [Components and Component Versions](doc/01-model/02-elements-toplevel.md#components-and-component-versions) + * 1.2.2. [Artifacts (Resources and Sources)](doc/01-model/02-elements-toplevel.md#artifacts-resources-and-sources) + * 1.2.3. [Sources](doc/01-model/02-elements-toplevel.md#sources) + * 1.2.4. [Resources](doc/01-model/02-elements-toplevel.md#resources) + * 1.2.5. [References](doc/01-model/02-elements-toplevel.md#references) + * 1.2.6. [Summary](doc/01-model/02-elements-toplevel.md#summary) + * 1.3. [Model Elements - Fundamentals](doc/01-model/03-elements-sub.md) + * 1.3.1. [Identifiers](doc/01-model/03-elements-sub.md#identifiers) + * 1.3.2. [Access Specification](doc/01-model/03-elements-sub.md#access-specification) + * 1.3.3. [Access Types](doc/01-model/03-elements-sub.md#access-types) + * 1.3.4. [Labels](doc/01-model/03-elements-sub.md#labels) + * 1.3.5. [Repository Contexts](doc/01-model/03-elements-sub.md#repository-contexts) + * 1.3.6. [Signatures](doc/01-model/03-elements-sub.md#signatures) + * 1.3.7. [Digest Info](doc/01-model/03-elements-sub.md#digest-info) + * 1.3.8. [Signature Info](doc/01-model/03-elements-sub.md#signature-info) + * 1.4. [Example of a complete Component Version](doc/01-model/04-example.md#example-of-a-complete-component-version) + * 1.5. [Conventions](doc/01-model/06-conventions.md#conventions) + * 1.5.1. [Intended Environments](doc/01-model/06-conventions.md#intended-environments) + * 1.5.2. [Selection of Usage Scenarios](doc/01-model/06-conventions.md#selection-of-usage-scenarios) + * 1.6. [Extending the Open Component Model](doc/01-model/07-extensions.md#extending-the-open-component-model) + * 1.6.1. [Functional extensions](doc/01-model/07-extensions.md#functional-extensions) + * 1.6.2. [Semantic extensions](doc/01-model/07-extensions.md#semantic-extensions) +* 2. [Processing](doc/02-processing/README.md) + * 2.1. [Referencing](doc/02-processing/01-references.md#referencing) + * 2.1.1. [Example](doc/02-processing/01-references.md#example) + * 2.2. [Signing](doc/02-processing/03-signing.md#signing) + * 2.2.1. [Verification Procedure](doc/02-processing/03-signing.md#verification-procedure) + * 2.3. [Normalization](doc/02-processing/04-digest.md#normalization) + * 2.3.1. [Artifact Digest](doc/02-processing/04-digest.md#artifact-digest) + * 2.3.2. [Normalization Types](doc/02-processing/04-digest.md#normalization-types) + * 2.3.3. [Serialization Format](doc/02-processing/04-digest.md#serialization-format) + * 2.3.4. [Recursive Digest Calculation](doc/02-processing/04-digest.md#recursive-digest-calculation) + * 2.4. [Example](doc/02-processing/04-digest.md#example) + * 2.4.1. [Simple Component-Version](doc/02-processing/04-digest.md#simple-component-version) + * 2.4.2. [Component-Version With Reference](doc/02-processing/04-digest.md#component-version-with-reference) + * 2.5. [Component Descriptor Normalization](doc/02-processing/04-digest.md#component-descriptor-normalization) + * 2.5.1. [Relevant information in Component Descriptors](doc/02-processing/04-digest.md#relevant-information-in-component-descriptors) + * 2.5.2. [Labels](doc/02-processing/04-digest.md#labels) + * 2.5.3. [Exclude Resources from Normalization/Signing](doc/02-processing/04-digest.md#exclude-resources-from-normalizationsigning) + * 2.5.4. [Generic Normalization Format](doc/02-processing/04-digest.md#generic-normalization-format) + * 2.6. [Artifact Normalization](doc/02-processing/04-digest.md#artifact-normalization) + * 2.6.1. [Blob Representation Format for Resource Types](doc/02-processing/04-digest.md#blob-representation-format-for-resource-types) + * 2.6.2. [Interaction of Local Blobs, Access Methods, Uploaders and Media Types](doc/02-processing/04-digest.md#interaction-of-local-blobs-access-methods-uploaders-and-media-types) +* 3. [Persistence](doc/03-persistence/README.md) + * 3.1. [Model Operations](doc/03-persistence/01-operations.md#model-operations) + * 3.2. [Abstract Operations defined by the Open Component Model](doc/03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) + * 3.2.1. [Repository Operations](doc/03-persistence/01-operations.md#repository-operations) + * 3.2.2. [Access Method Operations](doc/03-persistence/01-operations.md#access-method-operations) + * 3.3. [Mappings for OCM Persistence](doc/03-persistence/02-mappings.md#mappings-for-ocm-persistence) + * 3.3.1. [Storage Backend Mappings for the Open Component Model](doc/03-persistence/02-mappings.md#storage-backend-mappings-for-the-open-component-model) ## Extensible Parts * 4 [Extensions](doc/04-extensions/README.md) * 4.1 [Artifact Types](doc/04-extensions/01-artifact-types/README.md) - * 4.1.1 [blob](doc/04-extensions/01-artifact-types/blob.md) - * 4.1.2 [directoryTree, fileSystem](doc/04-extensions/01-artifact-types/file-system.md) - * 4.1.3 [gitOpsTemplate](doc/04-extensions/01-artifact-types/gitops.md) - * 4.1.4 [helmChart](doc/04-extensions/01-artifact-types/helmchart.md) - * 4.1.5 [npmPackage](doc/04-extensions/01-artifact-types/npm.md) - * 4.1.6 [ociArtifact](doc/04-extensions/01-artifact-types/oci-artifact.md) - * 4.1.7 [ociImage](doc/04-extensions/01-artifact-types/oci-image.md) - * 4.1.8 [executable](doc/04-extensions/01-artifact-types/executable.md) + * 4.1.1 [blob](doc/04-extensions/01-artifact-types/blob.md) + * 4.1.2 [directoryTree, fileSystem](doc/04-extensions/01-artifact-types/file-system.md) + * 4.1.3 [gitOpsTemplate](doc/04-extensions/01-artifact-types/gitops.md) + * 4.1.4 [helmChart](doc/04-extensions/01-artifact-types/helmchart.md) + * 4.1.5 [npmPackage](doc/04-extensions/01-artifact-types/npm.md) + * 4.1.6 [ociArtifact](doc/04-extensions/01-artifact-types/oci-artifact.md) + * 4.1.7 [ociImage](doc/04-extensions/01-artifact-types/oci-image.md) + * 4.1.8 [executable](doc/04-extensions/01-artifact-types/executable.md) * 4.1.9 [sbom](doc/04-extensions/01-artifact-types/sbom.md) * 4.2 [Access Method Types](doc/04-extensions/02-access-types/README.md) - * 4.2.1 [localBlob](doc/04-extensions/02-access-types/localblob.md) - * 4.2.2 [ociArtifact](doc/04-extensions/02-access-types/ociartifact.md) - * 4.2.3 [ociBlob](doc/04-extensions/02-access-types/ociblob.md) - * 4.2.4 [helm](doc/04-extensions/02-access-types/helm.md) - * 4.2.5 [gitHub](doc/04-extensions/02-access-types/github.md) - * 4.2.6 [s3](doc/04-extensions/02-access-types/s3.md) - * 4.2.7 [npm](doc/04-extensions/02-access-types/npm.md) + * 4.2.1 [localBlob](doc/04-extensions/02-access-types/localblob.md) + * 4.2.2 [ociArtifact](doc/04-extensions/02-access-types/ociartifact.md) + * 4.2.3 [ociBlob](doc/04-extensions/02-access-types/ociblob.md) + * 4.2.4 [helm](doc/04-extensions/02-access-types/helm.md) + * 4.2.5 [gitHub](doc/04-extensions/02-access-types/github.md) + * 4.2.6 [s3](doc/04-extensions/02-access-types/s3.md) + * 4.2.7 [npm](doc/04-extensions/02-access-types/npm.md) * 4.3 [Storage Backend Mappings](doc/04-extensions/03-storage-backends/README.md) - * 4.3.1 [OCIRegistry](doc/04-extensions/03-storage-backend/soci.md) - * 4.3.2 [FileSystem (CTF)](doc/04-extensions/03-storage-backends/ctf.md) - * 4.3.3 [FileSystem (Component Archive)](doc/04-extensions/03-storage-backends/component-archive.md) - * 4.3.4 [AWS S3](doc/04-extensions/03-storage-backends/s3.md) + * 4.3.1 [OCIRegistry](doc/04-extensions/03-storage-backend/soci.md) + * 4.3.2 [FileSystem (CTF)](doc/04-extensions/03-storage-backends/ctf.md) + * 4.3.3 [FileSystem (Component Archive)](doc/04-extensions/03-storage-backends/component-archive.md) + * 4.3.4 [AWS S3](doc/04-extensions/03-storage-backends/s3.md) * 4.4 [Algorithms](doc/04-extensions/04-algorithms/README.md) * 4.4.1 [Artifact Normalization](doc/04-algorithms/04-algorithms/artifact-normalization-types.md) * 4.4.2 [Digest Algorithms](doc/04-algorithms/04-algorithms/label-merge-algorithms.md) @@ -109,16 +109,18 @@ The following chapters provide a formal description of the format to describe so ## Guidelines and Conventions -* 5.[Guidelines](doc/05-guidelines/README.md) - * 5.1.[Transport](doc/05-guidelines/01-transport.md#transport) - * 5.1.1.[Kinds of Transports](doc/05-guidelines/01-transport.md#kinds-of-transports) - * 5.2.[Model Contract](doc/05-guidelines/02-contract.md#model-contract) - * 5.2.1.[Example: Helm deployment](doc/05-guidelines/02-contract.md#example-helm-deployment) - * 5.3.[References](doc/05-guidelines/03-references.md#references) - * 5.3.1.[Relative Artifact References](doc/05-guidelines/03-references.md#relative-artifact-references) - * 5.3.2.[Absolute Artifact References](doc/05-guidelines/03-references.md#absolute-artifact-references) +* 5. [Guidelines](doc/05-guidelines/README.md) + * 5.1. [Transport](doc/05-guidelines/01-transport.md#transport) + * 5.1.1. [Kinds of Transports](doc/05-guidelines/01-transport.md#kinds-of-transports) + * 5.2. [Model Contract](doc/05-guidelines/02-contract.md#model-contract) + * 5.2.1. [Example: Helm deployment](doc/05-guidelines/02-contract.md#example-helm-deployment) + * 5.3. [References](doc/05-guidelines/03-references.md#references) + * 5.3.1. [Relative Artifact References](doc/05-guidelines/03-references.md#relative-artifact-references) + * 5.3.2. [Absolute Artifact References](doc/05-guidelines/03-references.md#absolute-artifact-references) -6. [Glossary](doc/glossary.md) +## Glossary + +* 6. [Glossary](doc/glossary.md) ## Central OCM project web page diff --git a/doc/01-model/01-model.md b/doc/01-model/01-model.md index 96fb133..b23bc65 100644 --- a/doc/01-model/01-model.md +++ b/doc/01-model/01-model.md @@ -8,7 +8,6 @@ The Open Compoment Model consists of a core model plus extensions. The core mode The following chapters will provide more details about these concepts. - ## Components and Component Versions Usually, complex software products are divided into logical units (called components in this specification). A component is typically maintained in a version control system. It has a build procedure generating binary artifacts from source code and a release process to make it available for consumers. Usually, releases are repeated from time to time, making new versions available. A component is a logical unit within a software product. It is a semantic bracket around software pieces belonging together because they fulfill a specific purpose. E.g. like, "This is the Frontend Component," "This is the Database component," and "This is the Kubernetes vertical autoscale component." diff --git a/doc/01-model/02-elements-toplevel.md b/doc/01-model/02-elements-toplevel.md index ef51f70..073e01d 100644 --- a/doc/01-model/02-elements-toplevel.md +++ b/doc/01-model/02-elements-toplevel.md @@ -21,11 +21,7 @@ A *Component* is technically defined by a globally unique identifier. The component identity uses the following naming scheme: -
- -*<DNS domain>* `/` *<name component> {* `/` *<name component> }* - -
+*\* `/` *\* { `/` *\* } Hereby the DNS domain plus optionally any number of leading name components MUST be owned by the provider of a component. For example, `github.com`, as DNS domain @@ -42,6 +38,7 @@ specification (e.g. `github.com/gardener/external-dns-management:0.15.1`). ## Artifacts (Resources and Sources) The Open Component Model distinguishes two kinds of artifacts: + - *Sources* are optional artifacts that contain the sources, which were used to generate the deployment-relevant *Resources*. - *Resources* are artifacts that finally make up the deployment-relevant set of artifacts. @@ -71,7 +68,6 @@ Those attributes are described by formal fields in the component descriptor: The access specification for the actual artifact (see below) - ### Artifact Types The formal type of an artifact uniquely specifies the logical interpretation of an artifact and its kind, @@ -161,7 +157,7 @@ There are two kinds of types: So, the complete pattern looks as follows: - ``` + ```text /[a-z][a-zA-Z0-9]* ``` @@ -206,8 +202,8 @@ In addition to the common artifact information, a resource may optionally descri A resource uses the following additional formal fields: - **`relation`** (required) *string['local', 'external']* - Indicates whether the entity providing a component is also the provider of the resource ('local') or whether the - resource is provided by a separate entity ('external'). This may be useful to determine whether the entity responsible + Indicates whether the entity providing a component is also the provider of the resource ('local') or whether the + resource is provided by a separate entity ('external'). This may be useful to determine whether the entity responsible for the component is also responsible for the resource. This property is purely informational and completely unrelated to the access method type. @@ -223,12 +219,12 @@ A resource uses the following additional formal fields: This field is used to describe the sources used to generate the resource. The selection is done by the following two fields: - - **`identitySelector`** *map[string]string* + - **`identitySelector`** *map[string]string* Identity attributes determining an appropriate source element. - - **`labels`** (optional) *[]Label* + - **`labels`** (optional) *[]Label* A list of arbitrary labels @@ -285,6 +281,7 @@ A `references` element has the following fields: The extra identity of the referenced component. Example: + ```yaml ... references: diff --git a/doc/01-model/03-elements-sub.md b/doc/01-model/03-elements-sub.md index d1213fe..efa904d 100644 --- a/doc/01-model/03-elements-sub.md +++ b/doc/01-model/03-elements-sub.md @@ -49,6 +49,7 @@ of constraints is then just a partial match of the set of identity attributes. You want to describe different image versions to be used for different Kubernetes versions deployed on different OS platforms and CPU architectures. With identity attributes this can be easily modeled by using + - the `name` attribute for the purpose (e.g. OCM CLI) - the `version` attribute for the version - and an `extraIdentity` attribute for the intended Kubernetes OS platform and architecture @@ -120,7 +121,7 @@ The content of a described artifact is accessible by applying its global identit Structure of OCM Specification -The access specification of an artifact may change when component versions are transported among repositories. +The access specification of an artifact may change when component versions are transported among repositories. Examples for access specification types are: @@ -189,7 +190,7 @@ attributes are not allowed at the label entry level. They can be changed in any repository the component version has been transferred to. This is supported to attach evolving information to a component version. But it also implies, that a component version must be updatable (re-transferable) in a certain target repository. - This may lead to conflicting changes which might need to be resolved in a non-trivial way. + This may lead to conflicting changes which might need to be resolved in a non-trivial way. The merge behaviour can be specified together with the label definition using the `merge` attribute. It has the following fields: @@ -246,7 +247,6 @@ Every signature entry has the following formal fields: The signature for the specified digest. - ## Digest Info A digest is specified by the following fields: diff --git a/doc/01-model/07-extensions.md b/doc/01-model/07-extensions.md index bd0eba6..8b490f1 100644 --- a/doc/01-model/07-extensions.md +++ b/doc/01-model/07-extensions.md @@ -9,22 +9,22 @@ to be known either by dedicated implementations of the model or by applications There are two different kinds of extensions: functional and semantic. -### Functional extensions +## Functional extensions - Functional extensions offer the possibility to enrich an implementation of the Open Component Model core + Functional extensions offer the possibility to enrich an implementation of the Open Component Model core with technology-specific parts to support more technology environments, like storage backends or artifact types. The functional extension points are: - - [Component Descriptor Serialization](#component-descriptor-serialization) - - [Storage Backends](#storage-backends) - - [Access Methods](#access-methods) - - [Digest Algorithms](#digest-algorithms) - - [Signing Algorithms](#signing-algorithms) - - [Artifact Normalization](#artifact-normalization) - - [Component Descriptor Normalization](#component-descriptor-normalization) - - [Label Merge Algorithms](#label-merge-algorithms) +- [Component Descriptor Serialization](#component-descriptor-serialization) +- [Storage Backends](#storage-backends) +- [Access Methods](#access-methods) +- [Digest Algorithms](#digest-algorithms) +- [Signing Algorithms](#signing-algorithms) +- [Artifact Normalization](#artifact-normalization) +- [Component Descriptor Normalization](#component-descriptor-normalization) +- [Label Merge Algorithms](#label-merge-algorithms) ### Semantic extensions @@ -33,8 +33,8 @@ There are two different kinds of extensions: functional and semantic. The semantic extension points are: - - [Artifact Types](#artifact-types) - - [Label Types](#label-types) +- [Artifact Types](#artifact-types) +- [Label Types](#label-types)

@@ -45,11 +45,10 @@ The elements used to describe a component version can be represented in a serial typically as yaml document. This document MUST contain a format specification version with the concrete representation of the model elements of a component version. The defined formats are described [here](../04-extensions/00-component-descriptor/README.md). - ## Storage Backends -The Open Component Model specification does not describe a dedicated remotely accessible +The Open Component Model specification does not describe a dedicated remotely accessible repository API (like for example the [OCI distribution specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md)). Instead, the model is intended to be stored in any kind of storage sub system, which is able to store a potentially unlimited number of blobs with @@ -77,12 +76,12 @@ A concrete implementation of a storage backend extension consists of two parts: - a language-independent mapping of the OCM elements to the elements available in the storage backend and a formal specification how the abstract model operations are mapped to operations provided by the storage backend. -- a language-specific binding of the formerly described mapping +- a language-specific binding of the formerly described mapping By defining the language-independent part used for those operations the interoperability between different implementations is assured. -#### Repository Specification +### Repository Specification An OCM repository is defined by the type of the storage backend and a set of attributes specific for this type, which specify the instance of the used backend. For example, this could @@ -106,10 +105,11 @@ implementation of the [abstract model operations](../03-persistence/01-operation The repository type used in a repository specification consists of two parts: + - a repository type name - a version -The type name specifies the kind of storage backend mapping to be +The type name specifies the kind of storage backend mapping to be used to implement an OCM repository interface. The version is used to specify the attribute structure that describes @@ -157,7 +157,7 @@ There are two kinds of type name: The compattern for `name` is: - ``` + ```text [a-z][a-zA-Z0-9]. ``` @@ -167,8 +167,8 @@ The `version` follows this regexp: v[1-9][0-9]* ``` -The repository specification type consists of the -repository type name, optionally followed by a version separated by a +The repository specification type consists of the +repository type name, optionally followed by a version separated by a slash (`/`). If not specified, version `v1` is assumed. #### Data Formats @@ -254,7 +254,7 @@ or the [artifact type](#artifact-types). To fulfill its task an access method ge The list of centrally defined access methods types can be found [here](../04-extensions/02-access-types/README.md) -#### Access Specification +### Access Specification The technical access to the physical content of an artifact described as part of a Component Version is expressed by an *Access Specification*. It specifies which access method to use and additionally the type-specific attributes, @@ -271,6 +271,7 @@ An access specification consists at least of the following fields: The access type used in a access specification consists of two parts: + - an access type name - a version @@ -320,7 +321,7 @@ There are two kinds of type name: So, the complete pattern looks as follows: - ``` + ```text [a-z][a-zA-Z0-9]. ``` @@ -335,11 +336,11 @@ access method type name optionally followed by a version separated by a slash (`/`). If not specified the version `v1` is assumed. Examples: + - `ociArtifact/v1` - `myprotocol.acme.org/v1alpha1` - -#### Access specification format +#### Access specification format Every access method MUST define a specification of the attributes required to locate the content. This specification MAY be versioned. The type of the access specification MUST contain the access method name @@ -354,10 +355,10 @@ v[1-9][0-9]* ``` Examples: + - `ociArtifact/v1` - `myprotocol.acme.org/v1alpha1` - If no version is specified, implicitly the version `v1` is assumed. The access method type is part of the access specification. The access method type may define additional specification attributes required to specify the access path to the artifact blob. @@ -371,7 +372,7 @@ For example, the access method `ociBlob` requires the OCI repository reference a imageReference: ghcr.io/jensh007/ctf/github.com/open-component-model/ocmechoserver/echoserver:0.1.0 ``` -#### Access Method Operations +#### Access Method Operations There must be an implementation for all supported external access methods according to their specifications. The local access method is mapped @@ -397,13 +398,11 @@ and stream access for the denoted blob is required. of its access specification. If this operation is not supported or proveds an empty string, an identity will be calculated based on accessing the byte stream. - ## Digest Algorithms Digest algorithms describe the way digests are calculated from a byte stream. The defined algorithms can be found [here](../04-extensions/04-algorithms/digest-algorithms.md). - ## Signing Algorithms A signing algorithm is used to provide a signature byte sequence for a given digest. @@ -420,12 +419,12 @@ The result of a signing is a structured data set with the following fields: The mediatype used to represent the signature value. Possible values: - `application/x-pem-file` signature is stored as multi-block PEM document. - The signature block uses the type `SIGNATURE`. This block might describe the - signature algorithm with the block header `Signature Algorithm`. + The signature block uses the type `SIGNATURE`. This block might describe the + signature algorithm with the block header `Signature Algorithm`. Additionally there might be blocks describing the certificate chain of the used public key. - `application/vnd.ocm.signature.rsa` signature is stored as HEX encoded byte stream. -- **`value`** (required) *string* +- **`value`** (required) *string* The signature byte stream according to the specified media type. @@ -439,13 +438,12 @@ The result of a signing is a structured data set with the following fields: The distinguished name of the subject of the public key certificate. - ## Artifact Normalization If a component is signed this signature should cover the content provided by the component resources. Therefore a digest is calculated for the resource content blobs. To be able to provide a format-independent digest, the resource blob can be normalized -before a digest is calculated. For example, an OCI artifact is represented +before a digest is calculated. For example, an OCI artifact is represented as blob following the [OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). Unfortunately the byte stream of the resulting artifact blob is not stable, @@ -476,7 +474,7 @@ the normalization is a *digest specification* with the following fields The already defined digesters can be found [here](../04-extensions/04-algorithms/artifact-normalization-types.md). -Example: +Example: ```yaml resources: @@ -497,13 +495,14 @@ resources: ## Component Descriptor Normalization The component descriptor contains several kinds of information: + - volatile label settings, which might be changeable. - artifact access information, which might be changed during transport steps. - static information describing the features and artifacts of a component version. The digest of a component descriptor is calculated on a normalized form of its elements. The normalized form contains only the signature -relevant information, everything else gets removed during the normalization process. +relevant information, everything else gets removed during the normalization process. The resulting string is the source for calculating the digest. This digest is then finally signed (and verified). @@ -515,7 +514,7 @@ different normalization algorithms and formats. The algorithms used for normalization are listed in the [extensions](../04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md) section. -#### Signing-relevant Information in Component Descriptors +### Signing-relevant Information in Component Descriptors Relevant fields are: @@ -527,14 +526,14 @@ Relevant fields are: - Sources without access method specification see [below](#artifacts) - References see [below](#references) -#### Artifacts +#### Artifacts Access method specifications for sources and resources are completely ignored. A resource or source is ignored, if the access method type is `none` -or the hash algorithm of the digest specification is `NO-DIGEST` and the +or the hash algorithm of the digest specification is `NO-DIGEST` and the normalization algorithm is `EXCLUDE-FROM-SIGNATURE`. -#### Labels +#### Labels Labels by default are removed before signing, but can be marked with a special boolean property `signing` set to `true`. This property indicates that the label is @@ -556,7 +555,7 @@ labels: `label1` will be excluded from the digest, whereas `label2` will be included. The value of any label is taken as is, preserving a potentially deeply nested structure. -#### References +#### References If a component version contains references to other component versions, their digests are stored along with the reference as digest descriptor. @@ -579,22 +578,22 @@ componentReferences: ... ``` -#### Applying Normalization Algorithms +#### Applying Normalization Algorithms -The normalization algorithm provides a stable deserialization format based on the +The normalization algorithm provides a stable deserialization format based on the elements of a component descriptor, excluding the fields not relevant for signing. Afterwards the resulting byte stream is hashed using a [digest algorithm](#digest-algorithms). The resulting digest is the digest of the component version. ## Label Merge Algorithms -Value merge algorithms are used during a transfer of a component version into a target repository +Value merge algorithms are used during a transfer of a component version into a target repository to merge label values, in case the transferred version is already present and the new content does not hamper the digest of the old one. - + This scenario is used to re-transfer updated content of non-signature relevant labels (for example updated routing slips). - + Hereby, potential changes in the target must be merged with the new inbound content. This is done by executing value merge algorithms for changed label values. @@ -609,7 +608,7 @@ a hierarchical name prefixed at least with a DNS-like domain owned by the provid /[a-z][a-zA-Z0-9]* ``` -The merge algorithm is described by a specification descriptor optionally provided +The merge algorithm is described by a specification descriptor optionally provided by the field `merge` as part of a label descriptor. It has the following fields: - **`algorithm`** (required) *string* @@ -645,7 +644,7 @@ as part of the component descriptor. The currently specified algorithms for label merge can be found in the [extensions](../04-extensions/04-algorithms/label-merge-algorithms.md) section. -## Artifact Types +## Artifact Types Artifact types describe the meaning of an artifact independent of their technical representation in a blob format. The artifact types defined by the core model (this specification) are described @@ -658,7 +657,7 @@ Dynamic attribution of model elements with additional information is possible us To be interpretable by tools the meaning of a label must be uniquely derivable from its name, regardless of the creator of a concrete label entry in a component version. To assure that every consumer of a component version has the same understanding odf the label, -label names MUST be globally unique. +label names MUST be globally unique. To combine globally uniqueness and arbitrarely extensibility of label names, they must comply with some namespaced naming scheme. @@ -698,7 +697,7 @@ There are two flavors of labels: /[a-z][a-zA-Z0-9]* ``` -#### Format Versions +### Format Versions To be interpretable by tools, every label MUST define a specification of its attributes, to describe its value space. This specification may be versioned. @@ -709,6 +708,6 @@ The version must match the following regexp v[0-9]+([a-z][a-z0-9]*)? ``` -#### Predefined Labels +#### Predefined Labels So far, no centrally predefined labels have been defined. diff --git a/doc/01-model/README.md b/doc/01-model/README.md index 4e99774..79dce0d 100644 --- a/doc/01-model/README.md +++ b/doc/01-model/README.md @@ -30,27 +30,27 @@ This chapter describes the elements of the Open Component Model and their syntax * 5.1.1.[Operating System and CPU Architecture](06-conventions.md#operating-system-and-cpu-architecture) * 5.2.[Selection of Usage Scenarios](06-conventions.md#selection-of-usage-scenarios) * 6.[Extending the Open Component Model](07-extensions.md#extending-the-open-component-model) - * 6.1.[Component Descriptor Serialization](07-extensions.md#component-descriptor-serialization) - * 6.2.[Storage Backends](07-extensions.md#storage-backends) - * 6.2.1.[Data Formats](07-extensions.md#data-formats) - * 6.2.2.[Mandatory Operations](07-extensions.md#mandatory-operations) - * 6.2.3.[Optional Operations](07-extensions.md#optional-operations) - * 6.3.[Access Methods](07-extensions.md#access-methods) - * 6.3.1.[Access Specification](07-extensions.md#access-specification) - * 6.3.2[Access Method Names](07-extensions.md#access-method-names) - * 6.3.3.[Access specification format](07-extensions.md#access-specification-format) - * 6.3.4[Access Method Operations](07-extensions.md#access-method-operations) - * 6.4.[Digest Algorithms](07-extensions.md#digest-algorithms) - * 6.5.[Signing Algorithms](07-extensions.md#signing-algorithms) - * 6.6.[Artifact Normalization](07-extensions.md#artifact-normalization) - * 6.7.[Component Descriptor Normalization](07-extensions.md#component-descriptor-normalization) - * 6.7.1.[Signing-relevant Information in Component Descriptors](07-extensions.md#signing-relevant-information-in-component-descriptors) - * 6.7.2.[Artifacts](07-extensions.md#artifacts) - * 6.7.3.[Labels](07-extensions.md#labels) - * 6.7.4.[References](07-extensions.md#references) - * 6.7.5.[Applying Normalization Algorithms](07-extensions.md#applying-normalization-algorithms) - * 6.8.[Label Merge Algorithms](07-extensions.md#label-merge-algorithms) - * 6.9.[Artifact Types](07-extensions.md#artifact-types) - * 6.10.[Label Types](07-extensions.md#label-types) - * 6.10.1.[Format Versions](07-extensions.md#format-versions) - * 6.10.2.[Predefined Labels](07-extensions.md#predefined-labels) + * 6.1.[Component Descriptor Serialization](07-extensions.md#component-descriptor-serialization) + * 6.2.[Storage Backends](07-extensions.md#storage-backends) + * 6.2.1.[Data Formats](07-extensions.md#data-formats) + * 6.2.2.[Mandatory Operations](07-extensions.md#mandatory-operations) + * 6.2.3.[Optional Operations](07-extensions.md#optional-operations) + * 6.3.[Access Methods](07-extensions.md#access-methods) + * 6.3.1.[Access Specification](07-extensions.md#access-specification) + * 6.3.2[Access Method Names](07-extensions.md#access-method-names) + * 6.3.3.[Access specification format](07-extensions.md#access-specification-format) + * 6.3.4[Access Method Operations](07-extensions.md#access-method-operations) + * 6.4.[Digest Algorithms](07-extensions.md#digest-algorithms) + * 6.5.[Signing Algorithms](07-extensions.md#signing-algorithms) + * 6.6.[Artifact Normalization](07-extensions.md#artifact-normalization) + * 6.7.[Component Descriptor Normalization](07-extensions.md#component-descriptor-normalization) + * 6.7.1.[Signing-relevant Information in Component Descriptors](07-extensions.md#signing-relevant-information-in-component-descriptors) + * 6.7.2.[Artifacts](07-extensions.md#artifacts) + * 6.7.3.[Labels](07-extensions.md#labels) + * 6.7.4.[References](07-extensions.md#references) + * 6.7.5.[Applying Normalization Algorithms](07-extensions.md#applying-normalization-algorithms) + * 6.8.[Label Merge Algorithms](07-extensions.md#label-merge-algorithms) + * 6.9.[Artifact Types](07-extensions.md#artifact-types) + * 6.10.[Label Types](07-extensions.md#label-types) + * 6.10.1.[Format Versions](07-extensions.md#format-versions) + * 6.10.2.[Predefined Labels](07-extensions.md#predefined-labels) diff --git a/doc/02-processing/01-references.md b/doc/02-processing/01-references.md index 15c7650..90647b0 100644 --- a/doc/02-processing/01-references.md +++ b/doc/02-processing/01-references.md @@ -9,6 +9,7 @@ A component version reference refers to another component version by using its i ## Example Let's take the following component: + ```yaml component: name: github.com/jensh007/mariadb @@ -50,5 +51,5 @@ component: meta: ... ``` -The reference target is described by the component version identifier and not by the repository location. +The reference target is described by the component version identifier and not by the repository location. diff --git a/doc/02-processing/03-signing.md b/doc/02-processing/02-signing.md similarity index 87% rename from doc/02-processing/03-signing.md rename to doc/02-processing/02-signing.md index cdbd70d..d91164b 100644 --- a/doc/02-processing/03-signing.md +++ b/doc/02-processing/02-signing.md @@ -1,6 +1,7 @@ # Signing Signing of a component version consists of several steps: + 1. digests for all reference component versions are determined and put into the dedicated reference element of the component descriptor. This is done by recursively following this procedure, but without the signing step. @@ -31,19 +32,19 @@ Verifying a component descriptor consist of three steps. Any failing step 1. Verify the digest of all resources and component references. Recursively follow component references and create an in-memory representation of the referenced component-descriptor by accessing and digesting all resources and references. Do not trust any digest data in child component-descriptors. The digest of the normalised in-memory representation of a component-reference **MUST** match the digest in the root component-descriptor (that contains a signature we verify in the next step). -```go -func digestForComponentDescriptor(cd) -> digest: - for reference in cd.component.componentReferences: - referencedCd = loadCdForReference(reference) - reference.Digest = digestForComponentDescriptor(referencedCd) + ```go + func digestForComponentDescriptor(cd) -> digest: + for reference in cd.component.componentReferences: + referencedCd = loadCdForReference(reference) + reference.Digest = digestForComponentDescriptor(referencedCd) - for resource in cd.component.Resource: - resource.Digest = loadAndDigestResource(resource) + for resource in cd.component.Resource: + resource.Digest = loadAndDigestResource(resource) - normalisedCd = normaliseComponentDescriptor(cd) - digest = createDigestForNormalisedCd - return digest -``` + normalisedCd = normaliseComponentDescriptor(cd) + digest = createDigestForNormalisedCd + return digest + ``` 2. check if calculated digest of the normalized component descriptor matches the digest in signatures.digest with hashAlgorithm, NormalisationAlgorithm and Value diff --git a/doc/02-processing/03-signing-process.md b/doc/02-processing/03-signing-process.md new file mode 100644 index 0000000..5a837e0 --- /dev/null +++ b/doc/02-processing/03-signing-process.md @@ -0,0 +1,111 @@ +# Signing Process and Normalization + +The signing of a component version is based on three things: + +* selected content of the component descriptor +* the content of the described artifacts +* the referenced component versions. + +A signature of a component version is based on digests of the involved elements. +Therefore, there must be a defined way, how to calculate digests. +This has to happen in a recursive way to handle aggregations. + +## Determing the Artifact Digests + +The content of every artifact is provided in a dedicated blob format by the various access methods. +A digest can be calculated based on this blob. This is the default behaviour. + +Nevertheless, there might be technology specific ways to provide an immutable digest for a dedicated type of artifact, +independent of the blob format generation (typically an archive). +For example, an OCI artifact is always uniquely identified by its manifest digest. +This characteristic can be used for the calculation of OCM artifact digests. + +There might be various ways to determine a digest for an artifact blob. +The algorithm to do this is called *artifact normalization type*. +Together with the digest and its digesting algorithm (e.g. SHA-256) +the normalization type is kept for an artifact. + +Example for the digest of an OCI artifact: + +```yaml + digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: ociArtifactDigest/v1 + value: 5e28862f7ad5b71f3f5c5dc7a4ccc8c3d3cb87f5e5774458d895d831d3765548 +``` + +This normalization algorithm specifies the way the digest is determined. For example, for OCI artifacts, +the algorithm `ociArtifactDigest/v1` is used by default. This behaviour can be controlled by appropriate digest handlers. + +If not explicitly requested, an appropiate digest handler is automatically determined based on the available digest handlers, +when the digest of an artifact is calculated for the first time. +This selection depends on the media type of the artifact blob and the artifact type. + +Normalization algorithm types may be versioned and SHOULD match the following regexp + +```text +[a-z][a-zA-Z0-9]*/v[0-9]+([a-z][a-z0-9]*) +``` + +For example: `ociArtifactDigest/v1` or `jsonNormalisationV2` + +If the digest algorithm `NO-DIGEST` is specified for an artifact, +this artifact content is not included into the component version digest. +This is typically configured for source artifacts, which are not deliverable. + +The artifact digest normalization algorithms are listed in the [extensions](../04-extensions/04-algorithms/README.md#artifact-normalization-types) +section of the specification. + +## Normalization Types + +To be able to sign a component version, the content of the described artifacts must be incorporated +and a digest for the artifact content needs to be calculated. + +By default, this digest is calculated based on the blob provided by the access specification of an artifact. There might be technology specific ways to uniquely identify the content for specific artifact types. + +Together with the digest and its algorithm, an artifact normalization algorithm is specified in the component descriptor. + +It contains signature +relevant information and volatile information (e.g. the access specification). Therefore, there is a normalization for component descriptors. + +Normalization algorithm types may be versioned and SHOULD match the following regexp + +```text +[a-z][a-zA-Z0-9]*/v[0-9]+([a-z][a-z0-9]*) +``` + +For example: `ociArtifactDigest/v1` or `jsonNormalisationV2` + +The normalization algorithms are listed in the [extensible parts](../04-extensions/01-extensions.md#normalization-algorithms) of the specification + +## Serialization Format + +A digest for a component version is stored along with a signature in a +component descriptor. A component descriptor can have multiple signatures and with this +multiple digests. + +Example: + +```text +digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: jsonNormalisation/v2 + value: 01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2 +``` + +## Recursive Digest Calculation + +A digest for a component version is calculated recursively including all referenced component versions. For each referenced component the component descriptor will get a `digest` section for each `reference` contained in `spec`: + +```yaml +spec: + ... + references: + - componentName: ocm.software/simpleapp + digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: jsonNormalisation/v2 + value: 01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2 + name: myhelperapp + version: 0.1.0 +``` diff --git a/doc/02-processing/04-digest.md b/doc/02-processing/04-digest.md deleted file mode 100644 index d5fd735..0000000 --- a/doc/02-processing/04-digest.md +++ /dev/null @@ -1,676 +0,0 @@ -# Signing Process - -The signing of a component version is based on three things: - -* selected content of the component descriptor -* the content of the described artifacts -* the referenced component versions. - -A signature of a component version is based on digests of the involved elements. -Therefore, there must be a defined way, how to calculate digests. -This has to happen in a recursive way to handle aggregations. - -## Determing the Artifact Digests - -The content of every artifact is provided in a dedicated blob format by the various access methods. -A digest can be calculated based on this blob. This is the default behaviour. - -Nevertheless, there might be technology specific ways to provide an immutable digest for a dedicated type of artifact, -independent of the blob format generation (typically an archive). -For example, an OCI artifact is always uniquely identified by its manifest digest. -This characteristic can be used for the calculation of OCM artifact digests. - -There might be various ways to determine a digest for an artifact blob. -The algorithm to do this is called *artifact normalization type*. -Together with the digest and its digesting algorithm (e.g. SHA-256) -the normalization type is kept for an artifact. - -Example for the digest of an OCI artifact: - -```yaml - digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: ociArtifactDigest/v1 - value: 5e28862f7ad5b71f3f5c5dc7a4ccc8c3d3cb87f5e5774458d895d831d3765548 -``` - -This normalization algorithm specifies the way the digest is determined. For example, for OCI artifacts, -the algorithm `ociArtifactDigest/v1` is used by default. This behaviour can be controlled by appropriate digest handlers. - -If not explicitly requested, an appropiate digest handler is automatically determined based on the available digest handlers, -when the digest of an artifact is calculated for the first time. -This selection depends on the media type of the artifact blob and the artifact type. - -Normalization algorithm types may be versioned and SHOULD match the following regexp - -``` -[a-z][a-zA-Z0-9]*/v[0-9]+([a-z][a-z0-9]*) -``` - -For example: `ociArtifactDigest/v1` or `jsonNormalisationV2` - -If the digest algorithm `NO-DIGEST` is specified for an artifact, -this artifact content is not included into the component version digest. -This is typically configured for source artifacts, which are not deliverable. - -The artifact digest normalization algorithms are listed in the [extensions](../04-extensions/04-algorithms/README.md#artifact-normalization-types) -section of the specification. - - -## Normalization Types - -To be able to sign a component version, the content of the described artifacts must be incorporated -and a digest for the artifact content needs to be calculated. - -By default, this digest is calculated based on the blob provided by the access specification of an artifact. There might be technology specific ways to uniquely identify the content for specific artifact types. - -Together with the digest and its algorithm, an artifact normalization algorithm is specified in the component descriptor. - -It contains signature -relevant information and volatile information (e.g. the access specification). Therefore, there is a normalization for component descriptors. - -Normalization algorithm types may be versioned and SHOULD match the following regexp - -``` -[a-z][a-zA-Z0-9]*/v[0-9]+([a-z][a-z0-9]*) -``` - -For example: `ociArtifactDigest/v1` or `jsonNormalisationV2` - -The normalization algorithms are listed in the [extensible parts](../04-extensions/01-extensions.md#normalization-algorithms) of the specification - -## Serialization Format - -A digest for a component version is stored along with a signature in a -component descriptor. A component descriptor can have multiple signatures and with this -multiple digests. - -Example: - -``` -digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: jsonNormalisation/v2 - value: 01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2 -``` - -## Recursive Digest Calculation - -A digest for a component version is calculated recursively including all referenced component versions. For each referenced component the component descriptor will get a `digest` section for each `reference` contained in `spec`: - -```yaml -spec: - ... - references: - - componentName: ocm.software/simpleapp - digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: jsonNormalisation/v2 - value: 01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2 - name: myhelperapp - version: 0.1.0 -``` -# Examples for Signing of Component Versions - -## Simple Component Version - -The component descriptor to be signed is: - -``` -apiVersion: ocm.software/v3alpha1 -kind: ComponentVersion -metadata: - name: ocm.software/simpleapp - provider: - name: ocm.software - version: 0.1.0 -repositoryContexts: [] -spec: - resources: - - access: - localReference: sha256:dea5de3e6f20fc58bfa8c2a25043f628c730960d46100b83540a30ed0a4e7910 - mediaType: application/vnd.oci.image.manifest.v1+tar+gzip - referenceName: ocm.software/simpleapp/echoserver:0.1.0 - type: localBlob - name: chart - relation: local - type: helmChart - version: 0.1.0 - - access: - imageReference: gcr.io/google_containers/echoserver:1.10 - type: ociArtifact - name: image - relation: external - type: ociImage - version: "1.0" - sources: - - access: - commit: e39625d6e919d33267da4778a1842670ce2bbf77 - repoUrl: github.com/open-component-model/ocm - type: github - name: source - type: filesytem - version: 0.1.0 -``` - -The normalized form of the component descriptor in `jsonNormalisation/v2` is the string: - -``` -[{"component":[{"componentReferences":[]},{"name":"ocm.software/simpleapp"},{"provider":[{"name":"ocm.software"}]},{"resources":[[{"digest":[{"hashAlgorithm":"SHA-256"},{"normalisationAlgorithm":"ociArtifactDigest/v1"},{"value":"5e28862f7ad5b71f3f5c5dc7a4ccc8c3d3cb87f5e5774458d895d831d3765548"}]},{"name":"chart"},{"relation":"local"},{"type":"helmChart"},{"version":"0.1.0"}],[{"digest":[{"hashAlgorithm":"SHA-256"},{"normalisationAlgorithm":"ociArtifactDigest/v1"},{"value":"cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229"}]},{"name":"image"},{"relation":"external"},{"type":"ociImage"},{"version":"1.0"}]]},{"sources":[[{"name":"source"},{"type":"filesytem"},{"version":"0.1.0"}]]},{"version":"0.1.0"}]}] -``` - -The `SHA-256` digest of this string is: `01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2` - -Adding the signature and digests for all artifacts leads to this signed component descriptor: - -``` -apiVersion: ocm.software/v3alpha1 -kind: ComponentVersion -metadata: - name: ocm.software/simpleapp - provider: - name: ocm.software - version: 0.1.0 -repositoryContexts: [] -signatures: -- digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: jsonNormalisation/v2 - value: 01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2 - name: mysig - signature: - algorithm: RSASSA-PKCS1-V1_5 - mediaType: application/vnd.ocm.signature.rsa - value: ae7e7a215d970c036773221642693bded5cf6a039597113d5ec522d5ebd491a40e3f6d850689a749aaa2de3c0cc2a9e5f564c8353f514385fae7c9554e00aead4890483a0ae5cef5c3629eb63ba4ee061659b06737b4985b4c04d286d19a09735482a769e82dd4a0b396cb0dda0822817b72b7daa1dfd2a1c071dd4a7e7bea1e25ee4156594efc5a567ac092ae8518995843bef1e79c7bfd95651cf66725f3740ef8b0202485900a0445df327543963322baf61dd91d4b30356b996bd99e513e2b5a7643a8ddfc706773603dfb3f8f38d7a9fbd10c48fe813c8149b1e0be20f7fcf54bdd5efe4da37c60730fbf33f3ea26b793cf6ac531b8c6f66bea3e3d2ffc -spec: - resources: - - access: - localReference: sha256:dea5de3e6f20fc58bfa8c2a25043f628c730960d46100b83540a30ed0a4e7910 - mediaType: application/vnd.oci.image.manifest.v1+tar+gzip - referenceName: ocm.software/simpleapp/echoserver:0.1.0 - type: localBlob - digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: ociArtifactDigest/v1 - value: 5e28862f7ad5b71f3f5c5dc7a4ccc8c3d3cb87f5e5774458d895d831d3765548 - name: chart - relation: local - type: helmChart - version: 0.1.0 - - access: - imageReference: gcr.io/google_containers/echoserver:1.10 - type: ociArtifact - digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: ociArtifactDigest/v1 - value: cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229 - name: image - relation: external - type: ociImage - version: "1.0" - sources: - - access: - commit: e39625d6e919d33267da4778a1842670ce2bbf77 - repoUrl: github.com/open-component-model/ocm - type: github - name: source - type: filesytem - version: 0.1.0 -``` - -## Component Version with Reference - -Here is a component descriptor containing a reference to the component in the previous [example](#simple-component-version). - -``` -apiVersion: ocm.software/v3alpha1 -kind: ComponentVersion -metadata: - name: ocm.software/complexapp - provider: - name: ocm.software - version: 0.1.0 -repositoryContexts: [] -spec: - references: - - componentName: ocm.software/simpleapp - name: myhelperapp - version: 0.1.0 - resources: - - access: - imageReference: gcr.io/google_containers/pause:3.2 - type: ociArtifact - name: image - relation: external - type: ociImage - version: "1.0" -``` - -The normalized form of the component descriptor in `jsonNormalisation/v2` is the string: - -``` -[{"component":[{"componentReferences":[[{"componentName":"ocm.software/simpleapp"},{"digest":[{"hashAlgorithm":"SHA-256"},{"normalisationAlgorithm":"jsonNormalisation/v2"},{"value":"01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2"}]},{"name":"myhelperapp"},{"version":"0.1.0"}]]},{"name":"ocm.software/complexapp"},{"provider":[{"name":"ocm.software"}]},{"resources":[[{"digest":[{"hashAlgorithm":"SHA-256"},{"normalisationAlgorithm":"ociArtifactDigest/v1"},{"value":"927d98197ec1141a368550822d18fa1c60bdae27b78b0c004f705f548c07814f"}]},{"name":"image"},{"relation":"external"},{"type":"ociImage"},{"version":"1.0"}]]},{"sources":[]},{"version":"0.1.0"}]}] -``` - -The `SHA-256` digest of this string is: `01801dfb56ba7b4033b8177e53e689644f1447c8270004b2c05c5fe45aa1063f` - -Adding the signature and digests for all artifacts leads to this signed component descriptor: - -``` -apiVersion: ocm.software/v3alpha1 -kind: ComponentVersion -metadata: - name: ocm.software/complexapp - provider: - name: ocm.software - version: 0.1.0 -repositoryContexts: [] -signatures: -- digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: jsonNormalisation/v2 - value: 01801dfb56ba7b4033b8177e53e689644f1447c8270004b2c05c5fe45aa1063f - name: mysig - signature: - algorithm: RSASSA-PKCS1-V1_5 - mediaType: application/vnd.ocm.signature.rsa - value: 727b067cd67003338b83149220a36fdb7e16f29d4d5790474c95ee3547adcbe64d699efce3d19fa2e85424904265c0364e95f15cbf816e093b633943a632ba9f3b862e1f5adb62620cf7eb2d85b60796f329afb1df26019ca84b42c58ebc6e691094e34eca223195f96cee3a8a1552e4ac7d1821e32072213f6cc762355c5974be56f239a270a9c67056ec3455f10339eb76eb8ca1905f0201190130fac0683bc2d09fa9bc3a9cd30af414b6f29e97397621d2f6b715353a7f793813139ed9707824b648aa84f2b38cc27fd7f6e89633ba83eb1fd34ab68a3b9c098eddd659f94a06d0225a4ed607b4c7682ca8d824ee005e618a25d3dde9d6aaf626aa7e1556 -spec: - references: - - componentName: ocm.software/simpleapp - digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: jsonNormalisation/v2 - value: 01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2 - name: myhelperapp - version: 0.1.0 - resources: - - access: - imageReference: gcr.io/google_containers/pause:3.2 - type: ociArtifact - digest: - hashAlgorithm: SHA-256 - normalisationAlgorithm: ociArtifactDigest/v1 - value: 927d98197ec1141a368550822d18fa1c60bdae27b78b0c004f705f548c07814f - name: image - relation: external - type: ociImage - version: "1.0" -``` - -Note that the `references` section in `spec` now contains a `digest` for the referenced component `ocm.software/simpleapp`. The value of the digest therefore is the same as in the previous example. - -# Component Descriptor Normalization - -The component descriptor contains several kinds of information: -- volatile label settings, which might be changeable. -- artifact access information, which might be changed during transport steps. -- static information describing the features and artifacts of a component version. - -The digest of a component descriptor is calculated on a normalized form of the -elements of the component descriptor. The normalized form contains only the signature -relevant information, everything else gets removed during the normalization process. -The resulting string is the source for calculating the digest. This digest is then finally signed (and verified). - -A normalized component descriptor is a subset of its elements containing only the properties relevant for signing: - -- based on JSON -- map serializes as alphanumerically ordered list of fields (to define unique order) -- field is map with two keys 'name', 'value' - -Like for signature algorithms, the model offers the possibility to work with -different normalization algorithms and formats. - -The algorithms used for normalization are listed in the [extensible parts](../04-extensions/01-extensions.md#normalization-algorithms) of the specification. - - -## Signing-relevant Information in Component Descriptors - -A component descriptor contains static information and -information, which may change over time, e.g. access method -specifications might be changed during transport steps. A digest should be -stable even after a transport and therefore should only hash static -information. Therefore, a component descriptor is transformed into a format -that only contains immutable fields, finally relevant for the signing -process and assuring data integrity. - -Relevant fields and their mapping to the normalized data structure for `JsonNormalisationV2` are: - -- Component Name: mapped to `component.name` -- Component Version: mapped to `component.version` -- Component Labels: mapped to `component.labels` (see [Labels](#labels)]) -- Component Provider: mapped to `component.provider` -- Resources: mapped to `component.resources`, always empty list enforced, without the source references (see [Labels](#labels)] and [Access Methods](#access-methods)]) -- Sources: mapped to `component.sources`, always empty list enforced, (see [Labels](#labels)] and [Access Methods](#access-methods)]) -- References: mapped to `component.references`, always empty list enforced, (see [Labels](#labels)]) - -### Access Methods - -Access method specifications are completely ignored. -A resource or source is ignored, if the access method type is `none`. - -### Labels - -Labels by default are removed before signing, but can be marked with a special boolean -property `signing`. This property indicates that the label is -signing-relevant and therefore becomes part of the digest. As a consequence such -labels cannot be changed during the lifecycle of a component version anymore -and should only describe static information. -The structure of signing-relevant labels is preserved from the component -descriptor version `v2`. - -Example: - -```yaml -labels: -- name: label1 - value: foo -- name: label2 - value: bar - signing: true -``` - -`label1` will be excluded from the digest, whereas `label2` will be included. -The value of any label is taken as is, preserving a potentially deeply nested structure. - -## Exclude Resources from Normalization/Signing - -If a resource should not be part of the normalization and later signing, the resource needs a special digest in the following format: - -```yaml -digest: - hashAlgorithm: NO-DIGEST - normalisationAlgorithm: EXCLUDE-FROM-SIGNATURE - value: NO-DIGEST -``` - -## Generic Normalization Format - -The generic format is based on a data structure consisting of dictionaries, lists and -simple values, like strings and integers. - -The signing relevant information described by a component descriptor is mapped -to such a data structure according to the format specifications described below. - -This data structure is mapped to a formal JSON representation, which -only contains clearly ordered elements. It is marshalled without whitespaces contained -in the representation. The resulting byte stream is directly defined -by the inbound data structure and independent of the order of marshalling -dictionaries/objects. -Its digest can be used as basis for calculating a signature. - -To map lists and dictionaries into such clearly ordered elements the rules -below are used. The inbound data structures in the examples are shown in -YAML notation. - -### Simple Values - -Simple values are kept as they are. - -Example: -```yaml - "bob" -``` -will result in : - -```json - "bob" -``` - -### Dictionary - -All dictionaries are converted into lists where each element is a single-entry -dictionary containing the key/value pair of the original entry. This list is -ordered by lexicographical order of the keys. - -Example: -```yaml - bob: 26 - alice: 25 -``` -will result in : - -```json - [{"alice":25},{"bob":26}] -``` - -The values are converted according to the same rules, recursively. - -Example: - -```yaml - people: - bob: 26 - alice: 25 -``` -will result in : - -```json - [{"people":[{"alice":25},{"bob":26}]}] -``` - -### Lists - -Lists are converted into JSON arrays and preserve the order of the elements. - -Example: -```yaml -- bob -- alice -``` - -normalized to: -```json -["bob","alice"] -``` - -The values are converted according to the same rules, recursively. - -Example: -```yaml - - bob: 26 - - alice: 25 -``` - -will result in : - -```json - [[{"bob":26}],[{"alice":25}]] -``` - -### Combined example - -The following snippet is taken from a real component descriptor. - -```yaml -resources: -- access: - localReference: blob - mediaType: text/plain - referenceName: ref - type: localBlob - extraIdentity: - additional: value - other: othervalue - name: elem1 - relation: local - type: elemtype - version: 1 -``` - -This will be normalized to - -```json -[{"resources":[[{"access":[{"localReference":"blob"},{"mediaType":"text/plain"},{"referenceName":"ref"},{"type":"localBlob"}]},{"extraIdentity":[{"additional":"value"},{"other":"othervalue"}]},{"name":"elem1"},{"relation":"local"},{"type":"elemtype"},{"version":1}]]}] -``` - -Formatted with whitespaces for better readability it looks like: - -```json -[ - { - "resources": [ - [ - { - "access": [ - { - "localReference": "blob" - }, - { - "mediaType": "text/plain" - }, - { - "referenceName": "ref" - }, - { - "type": "localBlob" - } - ] - }, - { - "extraIdentity": [ - { - "additional": "value" - }, - { - "other": "othervalue" - } - ] - }, - { - "name": "elem1" - }, - { - "relation": "local" - }, - { - "type": "elemtype" - }, - { - "version": 1 - } - ] - ] - } -] -``` - -### Empty values: - -Empty lists are normalized as empty lists - -```yaml -myList: [] -``` - -```json -[{"myList":[]}] -``` - -Null values are skipped during initialization - -```yaml -myList: ~ -``` - -```yaml -myList: null -``` - -```yaml -myList: -``` - -and are all normalized to: - -```json -[] -``` - -# Artifact Normalization - -To be able to sign a component version a digest for the artifact **content** must be determined. - -By default, this digest is calculated based on the blob provided by the access specification. -There might be technology specific ways to uniquely identify the content for dedicated artifact types. -Therefore an artifact normalization algorithm is kept in the component descriptor. - -## Blob Representation Format for Resource Types - -The central task of a component version is to provide information about versioned sets of resources. -For the component model such content of resources are just simple typed blobs. -The evaluation of an access specification always results in a simple blob, representing the content of the described resource. -This way blobs can be stored in any supported external blob store. - -An access method MUST always be able to return a blob representation for the accessed artifact. -If there are native storage technologies for dedicated artifact types they must also deliver such a blob. - -Whenever a new resource type is supported, corresponding blob formats MUST be defined for this type. -Type-agnostic access method types, like `localBlob` or `ociBlob` never need to know anything about their internal format. -But specific access methods, e.g. the `ociArtifact` method, MAY provide dedicated blob formats. - -These blob formats may depend on the combination of artifact type and access method type. -Therefore, a blob always has a *media type* specifying the technical format. -For every artifact type the possible media types with their technical format specifications MUST be defined. - -When using the component repository to transport content from one repository to -another the access information may change. But all variants MUST describe the same -content. - -If multiple media types are possible for blobs, the digest of the artifact content -MUST be immutable to avoid invalidating signatures. In such a case a -dedicated artifact normalization algorithm MUST be provided for such media types. - -Available artifact normalization types can be found [above](#normalization-types). - -## Interaction of Local Blobs, Access Methods, Uploaders and Media Types - -The Open Component Model is desiged to support transports of artifacts. -To assure the integrity of digests and signatures some rules must be obeyed by the involved model extensions. - -### Access Methods - -A remote access method MUST return the artifact content as blob. - -By default, this blob is used to calculate the content digest for an artifact. -Therefore, the byte-stream of this blob must be deterministic. -Multiple calls for the same content must return the identical blob. -If this cannot be guaranteed, a blob digest handler for the media type of this blob format MUST be defined. - -For example, the `ociArtifact` access method provides content as artifact set blob, -with a format based on the OCI artifact structure, which is defined by a dedicated media type. -For this media type a digest handler is defined, which replaces the default blob digest by the manifest digest of the artifact. -This way the digest is independent from the creation of the archive blob containing the artifact. - -Once the artifact content has been converted to a blob and stored as local blob, -this blob is by default kept for further transport steps. -This way, the digest calculation always provides the same result. - -### Blob Uploaders - -Blob Uploaders can be used as part of the transport process, to automatically -provide transported artifacts in technology specific local storage systems, e.g. OCI registries. -The Open Component Model allows to change access locations -of artifact content during transport. Therefore an automatic upload -with modification of the access method is principally allowed. -In such scenarios, it's essential to adhere to specific rules to ensure the integrity of digests and signatures. - -If a blob uploader is used to upload the artifact to a remote repository after a transfer again, -the access method can potentially be changed. But this MUST guarantee the same digest calculation. -The new access method must again provide a blob with a media type and digest handler combination, providing the same digest. - -For example, storing an OCI artifact delivered as local blob in an OCI repository again, the manifest digest will be the same. -This is guaranteed because it is the identity of the artifact according to the OCI specification. -As a result, a new transformation to a blob representation in combination with the digest handler -will always provide the same artifact digest. The access method can be switched again, -from `localBlob` to `ociArtifact` regardless of the artifact type. - -If this can not be guaranteed, once a blob representation is chosen, it must be kept as it is. -In such a case a blob uploader must preserve the local access method, -even if it uploads the content to an external storage system. - -This can be described in the component version by adding the new remote access specification -as part of the existing local one, using the `globalAccess` attribute. - -The artifact digest is always calculated based on the local access, -but tools may use the information provided by the global access to use technology native ways to access the artifact. diff --git a/doc/02-processing/04-signing-examples.md b/doc/02-processing/04-signing-examples.md new file mode 100644 index 0000000..bde6086 --- /dev/null +++ b/doc/02-processing/04-signing-examples.md @@ -0,0 +1,189 @@ +# Examples for Signing of Component Versions + +## Simple Component Version + +The component descriptor to be signed is: + +```yaml +apiVersion: ocm.software/v3alpha1 +kind: ComponentVersion +metadata: + name: ocm.software/simpleapp + provider: + name: ocm.software + version: 0.1.0 +repositoryContexts: [] +spec: + resources: + - access: + localReference: sha256:dea5de3e6f20fc58bfa8c2a25043f628c730960d46100b83540a30ed0a4e7910 + mediaType: application/vnd.oci.image.manifest.v1+tar+gzip + referenceName: ocm.software/simpleapp/echoserver:0.1.0 + type: localBlob + name: chart + relation: local + type: helmChart + version: 0.1.0 + - access: + imageReference: gcr.io/google_containers/echoserver:1.10 + type: ociArtifact + name: image + relation: external + type: ociImage + version: "1.0" + sources: + - access: + commit: e39625d6e919d33267da4778a1842670ce2bbf77 + repoUrl: github.com/open-component-model/ocm + type: github + name: source + type: filesytem + version: 0.1.0 +``` + +The normalized form of the component descriptor in `jsonNormalisation/v2` is the string: + +```json +[{"component":[{"componentReferences":[]},{"name":"ocm.software/simpleapp"},{"provider":[{"name":"ocm.software"}]},{"resources":[[{"digest":[{"hashAlgorithm":"SHA-256"},{"normalisationAlgorithm":"ociArtifactDigest/v1"},{"value":"5e28862f7ad5b71f3f5c5dc7a4ccc8c3d3cb87f5e5774458d895d831d3765548"}]},{"name":"chart"},{"relation":"local"},{"type":"helmChart"},{"version":"0.1.0"}],[{"digest":[{"hashAlgorithm":"SHA-256"},{"normalisationAlgorithm":"ociArtifactDigest/v1"},{"value":"cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229"}]},{"name":"image"},{"relation":"external"},{"type":"ociImage"},{"version":"1.0"}]]},{"sources":[[{"name":"source"},{"type":"filesytem"},{"version":"0.1.0"}]]},{"version":"0.1.0"}]}] +``` + +The `SHA-256` digest of this string is: `01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2` + +Adding the signature and digests for all artifacts leads to this signed component descriptor: + +```yaml +apiVersion: ocm.software/v3alpha1 +kind: ComponentVersion +metadata: + name: ocm.software/simpleapp + provider: + name: ocm.software + version: 0.1.0 +repositoryContexts: [] +signatures: +- digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: jsonNormalisation/v2 + value: 01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2 + name: mysig + signature: + algorithm: RSASSA-PKCS1-V1_5 + mediaType: application/vnd.ocm.signature.rsa + value: ae7e7a215d970c036773221642693bded5cf6a039597113d5ec522d5ebd491a40e3f6d850689a749aaa2de3c0cc2a9e5f564c8353f514385fae7c9554e00aead4890483a0ae5cef5c3629eb63ba4ee061659b06737b4985b4c04d286d19a09735482a769e82dd4a0b396cb0dda0822817b72b7daa1dfd2a1c071dd4a7e7bea1e25ee4156594efc5a567ac092ae8518995843bef1e79c7bfd95651cf66725f3740ef8b0202485900a0445df327543963322baf61dd91d4b30356b996bd99e513e2b5a7643a8ddfc706773603dfb3f8f38d7a9fbd10c48fe813c8149b1e0be20f7fcf54bdd5efe4da37c60730fbf33f3ea26b793cf6ac531b8c6f66bea3e3d2ffc +spec: + resources: + - access: + localReference: sha256:dea5de3e6f20fc58bfa8c2a25043f628c730960d46100b83540a30ed0a4e7910 + mediaType: application/vnd.oci.image.manifest.v1+tar+gzip + referenceName: ocm.software/simpleapp/echoserver:0.1.0 + type: localBlob + digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: ociArtifactDigest/v1 + value: 5e28862f7ad5b71f3f5c5dc7a4ccc8c3d3cb87f5e5774458d895d831d3765548 + name: chart + relation: local + type: helmChart + version: 0.1.0 + - access: + imageReference: gcr.io/google_containers/echoserver:1.10 + type: ociArtifact + digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: ociArtifactDigest/v1 + value: cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229 + name: image + relation: external + type: ociImage + version: "1.0" + sources: + - access: + commit: e39625d6e919d33267da4778a1842670ce2bbf77 + repoUrl: github.com/open-component-model/ocm + type: github + name: source + type: filesytem + version: 0.1.0 +``` + +## Component Version with Reference + +Here is a component descriptor containing a reference to the component in the previous [example](#simple-component-version). + +```yaml +apiVersion: ocm.software/v3alpha1 +kind: ComponentVersion +metadata: + name: ocm.software/complexapp + provider: + name: ocm.software + version: 0.1.0 +repositoryContexts: [] +spec: + references: + - componentName: ocm.software/simpleapp + name: myhelperapp + version: 0.1.0 + resources: + - access: + imageReference: gcr.io/google_containers/pause:3.2 + type: ociArtifact + name: image + relation: external + type: ociImage + version: "1.0" +``` + +The normalized form of the component descriptor in `jsonNormalisation/v2` is the string: + +```json +[{"component":[{"componentReferences":[[{"componentName":"ocm.software/simpleapp"},{"digest":[{"hashAlgorithm":"SHA-256"},{"normalisationAlgorithm":"jsonNormalisation/v2"},{"value":"01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2"}]},{"name":"myhelperapp"},{"version":"0.1.0"}]]},{"name":"ocm.software/complexapp"},{"provider":[{"name":"ocm.software"}]},{"resources":[[{"digest":[{"hashAlgorithm":"SHA-256"},{"normalisationAlgorithm":"ociArtifactDigest/v1"},{"value":"927d98197ec1141a368550822d18fa1c60bdae27b78b0c004f705f548c07814f"}]},{"name":"image"},{"relation":"external"},{"type":"ociImage"},{"version":"1.0"}]]},{"sources":[]},{"version":"0.1.0"}]}] +``` + +The `SHA-256` digest of this string is: `01801dfb56ba7b4033b8177e53e689644f1447c8270004b2c05c5fe45aa1063f` + +Adding the signature and digests for all artifacts leads to this signed component descriptor: + +```yaml +apiVersion: ocm.software/v3alpha1 +kind: ComponentVersion +metadata: + name: ocm.software/complexapp + provider: + name: ocm.software + version: 0.1.0 +repositoryContexts: [] +signatures: +- digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: jsonNormalisation/v2 + value: 01801dfb56ba7b4033b8177e53e689644f1447c8270004b2c05c5fe45aa1063f + name: mysig + signature: + algorithm: RSASSA-PKCS1-V1_5 + mediaType: application/vnd.ocm.signature.rsa + value: 727b067cd67003338b83149220a36fdb7e16f29d4d5790474c95ee3547adcbe64d699efce3d19fa2e85424904265c0364e95f15cbf816e093b633943a632ba9f3b862e1f5adb62620cf7eb2d85b60796f329afb1df26019ca84b42c58ebc6e691094e34eca223195f96cee3a8a1552e4ac7d1821e32072213f6cc762355c5974be56f239a270a9c67056ec3455f10339eb76eb8ca1905f0201190130fac0683bc2d09fa9bc3a9cd30af414b6f29e97397621d2f6b715353a7f793813139ed9707824b648aa84f2b38cc27fd7f6e89633ba83eb1fd34ab68a3b9c098eddd659f94a06d0225a4ed607b4c7682ca8d824ee005e618a25d3dde9d6aaf626aa7e1556 +spec: + references: + - componentName: ocm.software/simpleapp + digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: jsonNormalisation/v2 + value: 01c211f5c9cfd7c40e5b84d66a2fb7d19cb0d65174b06c57b403c2ad9fdf8ed2 + name: myhelperapp + version: 0.1.0 + resources: + - access: + imageReference: gcr.io/google_containers/pause:3.2 + type: ociArtifact + digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: ociArtifactDigest/v1 + value: 927d98197ec1141a368550822d18fa1c60bdae27b78b0c004f705f548c07814f + name: image + relation: external + type: ociImage + version: "1.0" +``` + +Note that the `references` section in `spec` now contains a `digest` for the referenced component `ocm.software/simpleapp`. The value of the digest therefore is the same as in the previous example. diff --git a/doc/02-processing/05-component-descriptor-normalization.md b/doc/02-processing/05-component-descriptor-normalization.md new file mode 100644 index 0000000..2b8c551 --- /dev/null +++ b/doc/02-processing/05-component-descriptor-normalization.md @@ -0,0 +1,294 @@ +# Component Descriptor Normalization + +The component descriptor contains several kinds of information: + +* volatile label settings, which might be changeable. +* artifact access information, which might be changed during transport steps. +* static information describing the features and artifacts of a component version. + +The digest of a component descriptor is calculated on a normalized form of the +elements of the component descriptor. The normalized form contains only the signature +relevant information, everything else gets removed during the normalization process. +The resulting string is the source for calculating the digest. This digest is then finally signed (and verified). + +A normalized component descriptor is a subset of its elements containing only the properties relevant for signing: + +* based on JSON +* map serializes as alphanumerically ordered list of fields (to define unique order) +* field is map with two keys 'name', 'value' + +Like for signature algorithms, the model offers the possibility to work with +different normalization algorithms and formats. + +The algorithms used for normalization are listed in the [extensible parts](../04-extensions/01-extensions.md#normalization-algorithms) of the specification. + +## Signing-relevant Information in Component Descriptors + +A component descriptor contains static information and +information, which may change over time, e.g. access method +specifications might be changed during transport steps. A digest should be +stable even after a transport and therefore should only hash static +information. Therefore, a component descriptor is transformed into a format +that only contains immutable fields, finally relevant for the signing +process and assuring data integrity. + +Relevant fields and their mapping to the normalized data structure for `JsonNormalisationV2` are: + +* Component Name: mapped to `component.name` +* Component Version: mapped to `component.version` +* Component Labels: mapped to `component.labels` (see [Labels](#labels)]) +* Component Provider: mapped to `component.provider` +* Resources: mapped to `component.resources`, always empty list enforced, without the source references (see [Labels](#labels)] and [Access Methods](#access-methods)]) +* Sources: mapped to `component.sources`, always empty list enforced, (see [Labels](#labels)] and [Access Methods](#access-methods)]) +* References: mapped to `component.references`, always empty list enforced, (see [Labels](#labels)]) + +### Access Methods + +Access method specifications are completely ignored. +A resource or source is ignored, if the access method type is `none`. + +### Labels + +Labels by default are removed before signing, but can be marked with a special boolean +property `signing`. This property indicates that the label is +signing-relevant and therefore becomes part of the digest. As a consequence such +labels cannot be changed during the lifecycle of a component version anymore +and should only describe static information. +The structure of signing-relevant labels is preserved from the component +descriptor version `v2`. + +Example: + +```yaml +labels: +- name: label1 + value: foo +- name: label2 + value: bar + signing: true +``` + +`label1` will be excluded from the digest, whereas `label2` will be included. +The value of any label is taken as is, preserving a potentially deeply nested structure. + +## Exclude Resources from Normalization/Signing + +If a resource should not be part of the normalization and later signing, the resource needs a special digest in the following format: + +```yaml +digest: + hashAlgorithm: NO-DIGEST + normalisationAlgorithm: EXCLUDE-FROM-SIGNATURE + value: NO-DIGEST +``` + +## Generic Normalization Format + +The generic format is based on a data structure consisting of dictionaries, lists and +simple values, like strings and integers. + +The signing relevant information described by a component descriptor is mapped +to such a data structure according to the format specifications described below. + +This data structure is mapped to a formal JSON representation, which +only contains clearly ordered elements. It is marshalled without whitespaces contained +in the representation. The resulting byte stream is directly defined +by the inbound data structure and independent of the order of marshalling +dictionaries/objects. +Its digest can be used as basis for calculating a signature. + +To map lists and dictionaries into such clearly ordered elements the rules +below are used. The inbound data structures in the examples are shown in +YAML notation. + +### Simple Values + +Simple values are kept as they are. + +Example: + +```yaml + "bob" +``` + +will result in : + +```json + "bob" +``` + +### Dictionary + +All dictionaries are converted into lists where each element is a single-entry +dictionary containing the key/value pair of the original entry. This list is +ordered by lexicographical order of the keys. + +Example: + +```yaml + bob: 26 + alice: 25 +``` + +will result in : + +```json + [{"alice":25},{"bob":26}] +``` + +The values are converted according to the same rules, recursively. + +Example: + +```yaml + people: + bob: 26 + alice: 25 +``` + +will result in : + +```json + [{"people":[{"alice":25},{"bob":26}]}] +``` + +### Lists + +Lists are converted into JSON arrays and preserve the order of the elements. + +Example: + +```yaml +- bob +- alice +``` + +normalized to: + +```json +["bob","alice"] +``` + +The values are converted according to the same rules, recursively. + +Example: + +```yaml + - bob: 26 + - alice: 25 +``` + +will result in : + +```json + [[{"bob":26}],[{"alice":25}]] +``` + +### Combined example + +The following snippet is taken from a real component descriptor. + +```yaml +resources: +- access: + localReference: blob + mediaType: text/plain + referenceName: ref + type: localBlob + extraIdentity: + additional: value + other: othervalue + name: elem1 + relation: local + type: elemtype + version: 1 +``` + +This will be normalized to + +```json +[{"resources":[[{"access":[{"localReference":"blob"},{"mediaType":"text/plain"},{"referenceName":"ref"},{"type":"localBlob"}]},{"extraIdentity":[{"additional":"value"},{"other":"othervalue"}]},{"name":"elem1"},{"relation":"local"},{"type":"elemtype"},{"version":1}]]}] +``` + +Formatted with whitespaces for better readability it looks like: + +```json +[ + { + "resources": [ + [ + { + "access": [ + { + "localReference": "blob" + }, + { + "mediaType": "text/plain" + }, + { + "referenceName": "ref" + }, + { + "type": "localBlob" + } + ] + }, + { + "extraIdentity": [ + { + "additional": "value" + }, + { + "other": "othervalue" + } + ] + }, + { + "name": "elem1" + }, + { + "relation": "local" + }, + { + "type": "elemtype" + }, + { + "version": 1 + } + ] + ] + } +] +``` + +### Empty values + +Empty lists are normalized as empty lists + +```yaml +myList: [] +``` + +```json +[{"myList":[]}] +``` + +Null values are skipped during initialization + +```yaml +myList: ~ +``` + +```yaml +myList: null +``` + +```yaml +myList: +``` + +and are all normalized to: + +```json +[] +``` diff --git a/doc/02-processing/06-artifact-normalization.md b/doc/02-processing/06-artifact-normalization.md new file mode 100644 index 0000000..2dcddbe --- /dev/null +++ b/doc/02-processing/06-artifact-normalization.md @@ -0,0 +1,87 @@ +# Artifact Normalization + +To be able to sign a component version a digest for the artifact **content** must be determined. + +By default, this digest is calculated based on the blob provided by the access specification. +There might be technology specific ways to uniquely identify the content for dedicated artifact types. +Therefore an artifact normalization algorithm is kept in the component descriptor. + +## Blob Representation Format for Resource Types + +The central task of a component version is to provide information about versioned sets of resources. +For the component model such content of resources are just simple typed blobs. +The evaluation of an access specification always results in a simple blob, representing the content of the described resource. +This way blobs can be stored in any supported external blob store. + +An access method MUST always be able to return a blob representation for the accessed artifact. +If there are native storage technologies for dedicated artifact types they must also deliver such a blob. + +Whenever a new resource type is supported, corresponding blob formats MUST be defined for this type. +Type-agnostic access method types, like `localBlob` or `ociBlob` never need to know anything about their internal format. +But specific access methods, e.g. the `ociArtifact` method, MAY provide dedicated blob formats. + +These blob formats may depend on the combination of artifact type and access method type. +Therefore, a blob always has a *media type* specifying the technical format. +For every artifact type the possible media types with their technical format specifications MUST be defined. + +When using the component repository to transport content from one repository to +another the access information may change. But all variants MUST describe the same +content. + +If multiple media types are possible for blobs, the digest of the artifact content +MUST be immutable to avoid invalidating signatures. In such a case a +dedicated artifact normalization algorithm MUST be provided for such media types. + +Available artifact normalization types can be found [here](./03-signing-process.md#normalization-types). + +## Interaction of Local Blobs, Access Methods, Uploaders and Media Types + +The Open Component Model is desiged to support transports of artifacts. +To assure the integrity of digests and signatures some rules must be obeyed by the involved model extensions. + +### Access Methods + +A remote access method MUST return the artifact content as blob. + +By default, this blob is used to calculate the content digest for an artifact. +Therefore, the byte-stream of this blob must be deterministic. +Multiple calls for the same content must return the identical blob. +If this cannot be guaranteed, a blob digest handler for the media type of this blob format MUST be defined. + +For example, the `ociArtifact` access method provides content as artifact set blob, +with a format based on the OCI artifact structure, which is defined by a dedicated media type. +For this media type a digest handler is defined, which replaces the default blob digest by the manifest digest of the artifact. +This way the digest is independent from the creation of the archive blob containing the artifact. + +Once the artifact content has been converted to a blob and stored as local blob, +this blob is by default kept for further transport steps. +This way, the digest calculation always provides the same result. + +### Blob Uploaders + +Blob Uploaders can be used as part of the transport process, to automatically +provide transported artifacts in technology specific local storage systems, e.g. OCI registries. +The Open Component Model allows to change access locations +of artifact content during transport. Therefore an automatic upload +with modification of the access method is principally allowed. +In such scenarios, it's essential to adhere to specific rules to ensure the integrity of digests and signatures. + +If a blob uploader is used to upload the artifact to a remote repository after a transfer again, +the access method can potentially be changed. But this MUST guarantee the same digest calculation. +The new access method must again provide a blob with a media type and digest handler combination, providing the same digest. + +For example, storing an OCI artifact delivered as local blob in an OCI repository again, the manifest digest will be the same. +This is guaranteed because it is the identity of the artifact according to the OCI specification. +As a result, a new transformation to a blob representation in combination with the digest handler +will always provide the same artifact digest. The access method can be switched again, +from `localBlob` to `ociArtifact` regardless of the artifact type. + +If this can not be guaranteed, once a blob representation is chosen, it must be kept as it is. +In such a case a blob uploader must preserve the local access method, +even if it uploads the content to an external storage system. + +This can be described in the component version by adding the new remote access specification +as part of the existing local one, using the `globalAccess` attribute. + +The artifact digest is always calculated based on the local access, +but tools may use the information provided by the global access to use technology native ways to access the artifact. diff --git a/doc/02-processing/README.md b/doc/02-processing/README.md index d6acef7..7215376 100644 --- a/doc/02-processing/README.md +++ b/doc/02-processing/README.md @@ -4,32 +4,31 @@ This chapter explains how to create and use components. * 1.[Referencing](01-references.md#referencing) * 1.1.[Example](01-references.md#example) -* 2.[Signing](03-signing.md#signing) - * 2.1.[Verification Procedure](03-signing.md#verification-procedure) - * 2.1.1.[Verify with RSA](03-signing.md#verify-with-rsa) - * 2.1.2.[Verify with X509](03-signing.md#verify-with-x509) -* 3.[Normalization](04-digest.md#normalization) - * 3.1.[Artifact Digest](04-digest.md#artifact-digest) - * 3.2.[Normalization Types](04-digest.md#normalization-types) - * 3.3.[Serialization Format](04-digest.md#serialization-format) - * 3.4.[Recursive Digest Calculation](04-digest.md#recursive-digest-calculation) -* 4.[Example](04-digest.md#example) - * 4.1.[Simple Component-Version](04-digest.md#simple-component-version) - * 4.2.[Component-Version With Reference](04-digest.md#component-version-with-reference) -* 5.[Component Descriptor Normalization](04-digest.md#component-descriptor-normalization) - * 5.1.[Relevant information in Component Descriptors](04-digest.md#relevant-information-in-component-descriptors) - * 5.1.1.[Access Methods](04-digest.md#access-methods) - * 5.2.[Labels](04-digest.md#labels) - * 5.3.[Exclude Resources from Normalization/Signing](04-digest.md#exclude-resources-from-normalizationsigning) - * 5.4.[Generic Normalization Format](04-digest.md#generic-normalization-format) - * 5.4.1.[Simple Values](04-digest.md#simple-values) - * 5.4.2.[Dictionary](04-digest.md#dictionary) - * 5.4.3.[Lists](04-digest.md#lists) - * 5.4.4.[Combined example](04-digest.md#combined-example) - * 5.4.5.[Empty values:](04-digest.md#empty-values) -* 6.[Artifact Normalization](04-digest.md#artifact-normalization) - * 6.1.[Blob Representation Format for Resource Types](04-digest.md#blob-representation-format-for-resource-types) - * 6.2.[Interaction of Local Blobs, Access Methods, Uploaders and Media Types](04-digest.md#interaction-of-local-blobs-access-methods-uploaders-and-media-types) - * 6.2.1.[Access Methods](04-digest.md#access-methods) - * 6.2.2.[Blob Uploaders](04-digest.md#blob-uploaders) - +* 2.[Signing](02-signing.md#signing) + * 2.1.[Verification Procedure](02-signing.md#verification-procedure) + * 2.1.1.[Verify with RSA](02-signing.md#verify-with-rsa) + * 2.1.2.[Verify with X509](02-signing.md#verify-with-x509) +* 3.[Normalization](03-signing-process.md#signing-process-and-normalization) + * 3.1.[Artifact Digest](03-signing-process.md#determing-the-artifact-digests) + * 3.2.[Normalization Types](03-signing-process.md#normalization-types) + * 3.3.[Serialization Format](03-signing-process.md#serialization-format) + * 3.4.[Recursive Digest Calculation](03-signing-process.md#recursive-digest-calculation) +* 4.[Example](04-signing-examples.md#examples-for-signing-of-component-versions) + * 4.1.[Simple Component-Version](04-signing-examples.md#simple-component-version) + * 4.2.[Component-Version With Reference](04-signing-examples.md#component-version-with-reference) +* 5.[Component Descriptor Normalization](04-signing-examples.md#component-descriptor-normalization) + * 5.1.[Relevant information in Component Descriptors](04-signing-examples.md#relevant-information-in-component-descriptors) + * 5.1.1.[Access Methods](05-component-descriptor-normalization.md#access-methods) + * 5.2.[Labels](05-component-descriptor-normalization.md#labels) + * 5.3.[Exclude Resources from Normalization/Signing](05-component-descriptor-normalization.md#exclude-resources-from-normalizationsigning) + * 5.4.[Generic Normalization Format](05-component-descriptor-normalization.md#generic-normalization-format) + * 5.4.1.[Simple Values](05-component-descriptor-normalization.md#simple-values) + * 5.4.2.[Dictionary](05-component-descriptor-normalization.md#dictionary) + * 5.4.3.[Lists](05-component-descriptor-normalization.md#lists) + * 5.4.4.[Combined example](05-component-descriptor-normalization.md#combined-example) + * 5.4.5.[Empty values](05-component-descriptor-normalization.md#empty-values) +* 6.[Artifact Normalization](06-artifact-normalization.md#artifact-normalization) + * 6.1.[Blob Representation Format for Resource Types](06-artifact-normalization.md#blob-representation-format-for-resource-types) + * 6.2.[Interaction of Local Blobs, Access Methods, Uploaders and Media Types](06-artifact-normalization.md#interaction-of-local-blobs-access-methods-uploaders-and-media-types) + * 6.2.1.[Access Methods](06-artifact-normalization.md#access-methods) + * 6.2.2.[Blob Uploaders](06-artifact-normalization.md#blob-uploaders) diff --git a/doc/03-persistence/01-operations.md b/doc/03-persistence/01-operations.md index 08e0462..835d4d7 100644 --- a/doc/03-persistence/01-operations.md +++ b/doc/03-persistence/01-operations.md @@ -2,7 +2,7 @@ This chapter describes the abstract operations an implementation must provide to interact with model elements stored in an OCM persistence. -# Abstract Operations defined by the Open Component Model +## Abstract Operations defined by the Open Component Model The Open Component Model defines abstract operations that must be available to work with a component repository view as interpretation layer on-top of dedicated well-known storage subsystems (like an OCI registry or an S3 blob store). These operations build the first extension point of OCM, which allows to map the OCM functionality onto any blobstore-like storage system. @@ -12,7 +12,7 @@ The concrete incarnation of those repository and access method operations depend By defining the data formats used for those operations the interoperability between different implementations is enabled. -## Repository Operations +### Repository Operations The Open Component Model specification does not describe a dedicated remotely accessible repository API (like for example the [OCI distribution specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md)). @@ -26,7 +26,7 @@ to work with component information stored in such a storage backend. Every such binding must support at least the mandatory set of abstract operations working with elements of the component model (see below). -### Mandatory Operations +#### Mandatory Operations The following operations are mandatory: @@ -63,7 +63,7 @@ The following operations are mandatory: List all the known versions of a component specified by its component identity. -### Optional Operations +#### Optional Operations Optional operations might be: @@ -89,7 +89,7 @@ Optional operations might be: It should not only return component identities, that are direct children, but traverse the complete subtree. -## Access Method Operations +### Access Method Operations There must be an implementation for all supported external access methods according to their specifications. The local access method is mapped to the local blob access provided by the repository. @@ -103,4 +103,3 @@ They have to support read access, only. At least a media type and stream access - **`.GetStream(RepositoryContext, ComponentVersion, AccessSpecification) (Byte Stream, error)`** Provide access to the blob content described by a dedicated access specification. - diff --git a/doc/03-persistence/02-mappings.md b/doc/03-persistence/02-mappings.md index e3edd09..a21bee9 100644 --- a/doc/03-persistence/02-mappings.md +++ b/doc/03-persistence/02-mappings.md @@ -13,6 +13,7 @@ The OCM specification describes an interpretation layer on-top of well-known sto Therefore, for every storage technology a mapping must be defined to ensure interoperability between different OCM implementations. These mappings describe: + - the repository specification type and format used to specify a dedicated repository instance - the mapping of the OCM elements to the elements provided by the storage technology. diff --git a/doc/04-extensions/00-component-descriptor/README.md b/doc/04-extensions/00-component-descriptor/README.md index 8bfe527..115cf60 100644 --- a/doc/04-extensions/00-component-descriptor/README.md +++ b/doc/04-extensions/00-component-descriptor/README.md @@ -4,4 +4,4 @@ This specification covers two serialization versions for component descriptors: - [v2](v2.md) the version used prior to this specification -- [v3alpha1](v3.md) a serialization format oriented on the Kubernetes manifest structure \ No newline at end of file +- [v3alpha1](v3.md) a serialization format oriented on the Kubernetes manifest structure diff --git a/doc/04-extensions/00-component-descriptor/v2.md b/doc/04-extensions/00-component-descriptor/v2.md index b08adcd..9f460a4 100644 --- a/doc/04-extensions/00-component-descriptor/v2.md +++ b/doc/04-extensions/00-component-descriptor/v2.md @@ -13,8 +13,8 @@ thus allowing conversion to a JSON representation. YAML is recommended as preferred serialization format. YAML permits the usage of comments, and allows different formatting options. -None of those are by contract part of a *Component Descriptor*, -thus implementations may arbitrarily choose to retain or not retain +None of those are by contract part of a *Component Descriptor*, +thus implementations may arbitrarily choose to retain or not retain comments or formatting options. The order of attributes is arbitrary, and MUST NOT be relied upon. @@ -33,7 +33,7 @@ A *Component Descriptor* document consists of two top level elements: `meta` and Example: -``` +```yaml meta: - schemaVersion: "v2" component: @@ -62,7 +62,7 @@ also called component name and component version. Name and version are the identifier for a *Component Descriptor* and the component version described by it. -``` +```yaml meta: - schemaVersion: "v2" component: diff --git a/doc/04-extensions/00-component-descriptor/v3.md b/doc/04-extensions/00-component-descriptor/v3.md index 40adb73..2cd6f39 100644 --- a/doc/04-extensions/00-component-descriptor/v3.md +++ b/doc/04-extensions/00-component-descriptor/v3.md @@ -1,5 +1,6 @@ # Component Descriptor Serialization Version v3 + The component descriptor V2 is specified in this [schema](https://github.com/open-component-model/ocm/blob/main/resources/component-descriptor-ocm-v3-schema.yaml). -Note that the schemas are maintained in a different [Git repository](https://github.com/open-component-model/ocm/blob/main/resources). \ No newline at end of file +Note that the schemas are maintained in a different [Git repository](https://github.com/open-component-model/ocm/blob/main/resources). diff --git a/doc/04-extensions/01-artifact-types/README.md b/doc/04-extensions/01-artifact-types/README.md index 8ff6bb8..e8fd144 100644 --- a/doc/04-extensions/01-artifact-types/README.md +++ b/doc/04-extensions/01-artifact-types/README.md @@ -12,7 +12,7 @@ tree or an OCI artifact blob, as described by a mime type. The access method alw The definition of an artifact type MUST contain a unique name, the meaning of the content and possible blob formats in form of mime types. -The following table contains all artifact types defined in the core specification. +The following table contains all artifact types defined in the core specification. | TYPE NAME | DESCRIPTION | |-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| @@ -21,10 +21,10 @@ The following table contains all artifact types defined in the core specificatio | [`gitOpsTemplate`](gitops.md) | Filesystem content (tar, tgz) used as GitOps Template, e.g. to set up a git repo used for continuous e using FluxCD | | [`helmChart`](helmchart.md) | A Helm Chart stored as OCI artifact or as tar blob (`mediaType` tar) | | [`npmPackage`](npm.md) | A Node Package Manager [npm](https://www.npmjs.com) archive | -| [`ociArtifact`](oci-artifact.md) | A generic OCI artifact following the [open containers image specification](https://github.com/spec/blob/main/spec.md) | -| [`ociImage`](#oci-image.md) | An OCI image or image list | +| [`ociArtifact`](oci-artifact.md) | A generic OCI artifact following the [open containers image specification](https://github.com/opencontainers/image-spec/blob/main/spec.md) | +| [`ociImage`](oci-image.md) | An OCI image or image list | | [`executable`](executable.md) | A blob describing an executable program | -| [`sbom`](sbom.md) | A list of ingredients that make up software components (https://www.cisa.gov/sbom) | +| [`sbom`](sbom.md) | A list of ingredients that make up software components () | Some additional types are defined, but not part of the core specification. Support is optional, but the list of names is reserved. @@ -33,4 +33,3 @@ Some additional types are defined, but not part of the core specification. Suppo | [`blueprint`](blueprint.md) | An installation description for the [landscaper](https://github.com/gardener/landscaper) installation | | [`toiExecutor`](toiExecutor.md) | A toolset for simple installation in the [OCM CLI](https://github.com/open-component-model/ocm/blob/cm_toi.md) installation environment. | | [`toiPackage`](toiPackackage.md) | A YAML resource describing the installation for the [OCM CLI](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi.md) TOI installation. | - diff --git a/doc/04-extensions/01-artifact-types/blob.md b/doc/04-extensions/01-artifact-types/blob.md index 1a92559..ea15286 100644 --- a/doc/04-extensions/01-artifact-types/blob.md +++ b/doc/04-extensions/01-artifact-types/blob.md @@ -1,10 +1,12 @@ # Blob ## Type Name + **`blob`** A blob represents any data without a dedicated logical type. ## Format Variants + Any arbitrary media type is used to define the logical and/or technical format of the byte-stream represented by the blob. -By default the media type `application/octet-stream` can be used for an anoymous byte sequence. +By default the media type `application/octet-stream` can be used for an anoymous byte sequence. diff --git a/doc/04-extensions/01-artifact-types/blueprint.md b/doc/04-extensions/01-artifact-types/blueprint.md index 1e25828..1538009 100644 --- a/doc/04-extensions/01-artifact-types/blueprint.md +++ b/doc/04-extensions/01-artifact-types/blueprint.md @@ -1,3 +1,9 @@ - `blueprint` — Landscaper Installation Blueprint +# Blob -An installation description for the [*landscaper*](https://github.com/gardener/landscaper) installation environment. \ No newline at end of file +## Type Name + +**`blueprint`** + +## Description + +An installation description for the [*landscaper*](https://github.com/gardener/landscaper) installation environment. diff --git a/doc/04-extensions/01-artifact-types/executable.md b/doc/04-extensions/01-artifact-types/executable.md index 1d0d829..4b1f4aa 100644 --- a/doc/04-extensions/01-artifact-types/executable.md +++ b/doc/04-extensions/01-artifact-types/executable.md @@ -1,16 +1,20 @@ # Executable ## Type Name + **`executable`** ## Description + A blob describing an executable program. The artifact SHOULD use [extraIdentity](../../01-model/03-elements-sub.md#identifiers) properties to describe the OS architecture and platform the program is intended for + - `os`: Operating system according to Golang property GOOS - `architecture`: Architecture according to Golang property GOARCH ## Format Variants Media Types: - - `application/octet-stream` - - `application/octet-stream+gzip` + +- `application/octet-stream` +- `application/octet-stream+gzip` diff --git a/doc/04-extensions/01-artifact-types/file-system.md b/doc/04-extensions/01-artifact-types/file-system.md index 49e29bf..3af2c50 100644 --- a/doc/04-extensions/01-artifact-types/file-system.md +++ b/doc/04-extensions/01-artifact-types/file-system.md @@ -1,23 +1,27 @@ # [NAME] ## Type Name + - **`directoryTree`** - **`filesystem`** (legacy) - ## Description + Filesystem content represented in tar format. ## Format Variants - or for content compressed with GNU Zip application/gzip, application/x-gzip, application/x-gtar, and application/x-tgz or application/x-tar+gzip. -The media type SHOULD be - - `application/x-tar` + For content compressed with GNU Zip application/gzip, application/x-gzip, application/x-gtar, and application/x-tgz or application/x-tar+gzip. + +The media type SHOULD be + +- `application/x-tar` or for content compressed with GNU Zip - - `application/x-tgz` - - `application/x-tar+gzip` - - `application/gzip` - - `application/x-gzip` - - `application/x-gtar` + +- `application/x-tgz` +- `application/x-tar+gzip` +- `application/gzip` +- `application/x-gzip` +- `application/x-gtar` diff --git a/doc/04-extensions/01-artifact-types/gitops.md b/doc/04-extensions/01-artifact-types/gitops.md index 34e5f54..2b83170 100644 --- a/doc/04-extensions/01-artifact-types/gitops.md +++ b/doc/04-extensions/01-artifact-types/gitops.md @@ -1,10 +1,13 @@ -# GitOps +# GitOps ## Type Name + **`gitOpsTemplate`** ## Description -Filesystem content (tar, tgz) used as GitOps Template, e.g. to set up a git repo used for continuous e using FluxCD + +Filesystem content (tar, tgz) used as GitOps Template, e.g. to set up a git repo used for continuous e using FluxCD ## Format Variants + It supports the same formats as the [`directoryTree`](file-system.md) type. diff --git a/doc/04-extensions/01-artifact-types/helmchart.md b/doc/04-extensions/01-artifact-types/helmchart.md index 70eacf3..4c0fbf7 100644 --- a/doc/04-extensions/01-artifact-types/helmchart.md +++ b/doc/04-extensions/01-artifact-types/helmchart.md @@ -1,9 +1,11 @@ # Helm Chart ## Type Name + **`helmChart`** ## Description + A Kubernetes installation resource representing a Helm chart, either stored as OCI artifact or as tar blob. ## Format Variants @@ -13,8 +15,8 @@ A Kubernetes installation resource representing a Helm chart, either stored as O A Helm chart might be stored as OCI artifact following the [Artifact Set Archive Format](../common/formatspec.md#artifact-set-archive-format). This format is for example provided by the access method type [`ociArtifact`](../02-access-types/oci-artifact.md) Media types: - - `application/vnd.oci.image.manifest.v1+tar` - - `application/vnd.oci.image.manifest.v1+tar+gzip` + - `application/vnd.oci.image.manifest.v1+tar` + - `application/vnd.oci.image.manifest.v1+tar+gzip` The config blob media type described in the OCI manifest MUST be - `application/vnd.cncf.helm.config.v1+json` @@ -23,7 +25,7 @@ A Kubernetes installation resource representing a Helm chart, either stored as O If stored in the Helm tar format (for the filesystem), the tar media type MUST be used. - Media types: + Media types: - `application/vnd.cncf.helm.chart.content.v1.tar` - `application/vnd.cncf.helm.chart.content.v1.tar+gzip` diff --git a/doc/04-extensions/01-artifact-types/npm.md b/doc/04-extensions/01-artifact-types/npm.md index c1f45b9..f327d85 100644 --- a/doc/04-extensions/01-artifact-types/npm.md +++ b/doc/04-extensions/01-artifact-types/npm.md @@ -1,12 +1,15 @@ # npm Package ## Type Name + **`npmPackage`** ## Description -A Node Package Manager ([npm](https://www.npmjs.com)) archive that is located in an npm registry. By default npm packages use the npm public registry at https://registry.npmjs.org. + +A Node Package Manager ([npm](https://www.npmjs.com)) archive that is located in an npm registry. By default npm packages use the npm public registry at . ## Format Variants Media Types: - - `application/x-tar` \ No newline at end of file + +- `application/x-tar` diff --git a/doc/04-extensions/01-artifact-types/oci-artifact.md b/doc/04-extensions/01-artifact-types/oci-artifact.md index 81a2af0..a5f778f 100644 --- a/doc/04-extensions/01-artifact-types/oci-artifact.md +++ b/doc/04-extensions/01-artifact-types/oci-artifact.md @@ -1,12 +1,14 @@ # OCI Artifact or Artifact Index ## Type Name + **`ociArtifact`** ## Description + A generic OCI artifact following the [open containers image specification](https://github.com/opencontainers/image-spec/blob/main/spec.md). -## Format Variants: +## Format Variants When provided as a blob, the [Artifact Set Archuive Format](../common/formatspec.md#artifact-set-archive-format) MUST be used to represent the content of the OCI artifact. @@ -18,7 +20,7 @@ Media Types: - `application/vnd.oci.image.manifest.v1+tar+gzip`: OCI image manifests - `application/vnd.oci.image.index.v1+tar.gzip`: OCI index manifests -## Special Support: +## Special Support There is a dedicated uploader available for local blobs. It converts a blob with the media type shown above into a regular OCI artifact in an OCI repository. diff --git a/doc/04-extensions/01-artifact-types/oci-image.md b/doc/04-extensions/01-artifact-types/oci-image.md index 414b5ad..9680f77 100644 --- a/doc/04-extensions/01-artifact-types/oci-image.md +++ b/doc/04-extensions/01-artifact-types/oci-image.md @@ -1,9 +1,11 @@ # OCI Image ## Type Name + **`ociImage`** ## Description + This type describes an OCI artifact containing an OCI container image. `ociImage` is a dedicated variant using the container image Media Types used by OCI registries. @@ -14,12 +16,12 @@ A general [ociArtifact](oci-artifact.md) describes any kind of content, dependin The blob uses the [Artifact Set Archive Format](../common/formatspec.md#artifact-set-archive-format). Media Types: -- `application/vnd.oci.image.manifest.v1+tar` -- `application/vnd.oci.image.manifest.v1+tar+gzip` -## Special Support: +- `application/vnd.oci.image.manifest.v1+tar` +- `application/vnd.oci.image.manifest.v1+tar+gzip` + +## Special Support There is a dedicated uploader available for local blobs. It converts a blob with the media type shown above into a regular OCI artifact in an OCI repository. It uses the reference hint attribute of the [`localBlob` access method](../02-access-types/localblob.md) to determine an appropriate OCI repository. If the import target of the OCM component version is an OCI registry, by default, the used OCI repository will be the base repository of the [OCM mapping](../../03-persistence/02-mappings.md#mappings-for-ocm-persistence) with the appended reference hint. - diff --git a/doc/04-extensions/01-artifact-types/sbom.md b/doc/04-extensions/01-artifact-types/sbom.md index 8e798ba..583c6a4 100644 --- a/doc/04-extensions/01-artifact-types/sbom.md +++ b/doc/04-extensions/01-artifact-types/sbom.md @@ -1,33 +1,35 @@ # SBOM ## Type Name + **`sbom`** ## Description -An SBOM is a nested inventory, a list of ingredients that make up software components (https://www.cisa.gov/sbom) + +An SBOM is a nested inventory, a list of ingredients that make up software components () ## Format Variants -- **CycloneDX** (https://cyclonedx.org/specification/overview) +- **CycloneDX** () Media Types: - - `application/vnd.cyclonedx+xml` for CycloneDX files in XML format - - `application/vnd.cyclonedx+json` for CycloneDX files in JSON format + - `application/vnd.cyclonedx+xml` for CycloneDX files in XML format + - `application/vnd.cyclonedx+json` for CycloneDX files in JSON format -- **SPDX** (https://spdx.github.io/spdx-spec/v2.3) +- **SPDX** () Media Types: - - `text/spdx` for SPDX files in tag-value format - - `application/spdx+xml` for SPDX files in RDF format - - `application/spdx+json` for SPDX files in JSON format + - `text/spdx` for SPDX files in tag-value format + - `application/spdx+xml` for SPDX files in RDF format + - `application/spdx+json` for SPDX files in JSON format - `application/spdx+yaml` for SPDX files in YAML format - **SWID** ([NIST](https://csrc.nist.gov/projects/software-identification-swid/guidelines) and [ISO](https://www.iso.org/standard/65666.html)) Media Types: - - `application/swid+xml` for SWID files in XML format + - `application/swid+xml` for SWID files in XML format -- **Syft** (https://github.com/anchore/syft) +- **Syft** () Media Types: - - `application/vnd.syft+json` for Syft generated SBOMs in JSON format \ No newline at end of file + - `application/vnd.syft+json` for Syft generated SBOMs in JSON format diff --git a/doc/04-extensions/01-artifact-types/template.md b/doc/04-extensions/01-artifact-types/template.md index 5552e9e..de862cd 100644 --- a/doc/04-extensions/01-artifact-types/template.md +++ b/doc/04-extensions/01-artifact-types/template.md @@ -1,13 +1,17 @@ # [NAME] ## Type Name + **`[TYPE]`** ## Description + [DESCRIPTION] ## Format Variants + [FORMAT VARIANTS] Media Types: - - `application/vnd.oci.image.manifest.v1+tar` + +- `application/vnd.oci.image.manifest.v1+tar` diff --git a/doc/04-extensions/01-artifact-types/toiexecutor.md b/doc/04-extensions/01-artifact-types/toiexecutor.md index f99e373..a848329 100644 --- a/doc/04-extensions/01-artifact-types/toiexecutor.md +++ b/doc/04-extensions/01-artifact-types/toiexecutor.md @@ -6,10 +6,10 @@ a possibility to run images taken from a component version with user configuration and feed them with the content of this component version. It is some basic mechanism which can be used to execute simple installation steps based on content described by the Open Component Model -(see https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi-bootstrapping.md). +(see ). A TOI executor is YAML resource describing the features of an TOI executor image. It is used by a [`toiPackage` resource](toiPackage.md), which -describes its instantiation for a dedicated installation object. \ No newline at end of file +describes its instantiation for a dedicated installation object. diff --git a/doc/04-extensions/02-access-types/README.md b/doc/04-extensions/02-access-types/README.md index 2772cf6..9635d85 100644 --- a/doc/04-extensions/02-access-types/README.md +++ b/doc/04-extensions/02-access-types/README.md @@ -16,4 +16,4 @@ The following access method types are centrally defined: | [`helm`](helm.md) | a Helm chart stored in a Helm Repository | | [`gitHub`](github.md) | a commit in a GitHub-based Git repository | | [`s3`](s3.md) | a blob stored in an AWS S3 bucket | -| [`npm`](npm.md) | a NodeJS package stored in an NPM repository | \ No newline at end of file +| [`npm`](npm.md) | a NodeJS package stored in an NPM repository | diff --git a/doc/04-extensions/02-access-types/github.md b/doc/04-extensions/02-access-types/github.md index 305fdb5..223eb79 100644 --- a/doc/04-extensions/02-access-types/github.md +++ b/doc/04-extensions/02-access-types/github.md @@ -1,11 +1,13 @@ # gitHub — Git Commit hosted by GitHub ## Synopsis -``` + +```text type: gitHub/v1 ``` ## Description + Access to a commit in a Git repository. ## Supported Media Types @@ -30,4 +32,4 @@ Attributes: - **`commit`** *string* - The sha/id of the git commit \ No newline at end of file + The sha/id of the git commit diff --git a/doc/04-extensions/02-access-types/helm.md b/doc/04-extensions/02-access-types/helm.md index 9e07e98..9c3eb56 100644 --- a/doc/04-extensions/02-access-types/helm.md +++ b/doc/04-extensions/02-access-types/helm.md @@ -1,17 +1,19 @@ # helm — Helm Package in Helm Repository *Synopsis:* -``` + +```text type: helm[/VERSION] [ATTRIBUTES] ``` ## Description + Access to a Helm chart in a Helm repository. ## Supported Media Types - - `application/vnd.cncf.helm.chart.content.v1.tar+gzip` +- `application/vnd.cncf.helm.chart.content.v1.tar+gzip` ## Specification Version @@ -35,4 +37,4 @@ Attributes: - **`keyring`** *string* - An optional keyring used to verify the chart. \ No newline at end of file + An optional keyring used to verify the chart. diff --git a/doc/04-extensions/02-access-types/localblob.md b/doc/04-extensions/02-access-types/localblob.md index 46fb862..dbbe625 100644 --- a/doc/04-extensions/02-access-types/localblob.md +++ b/doc/04-extensions/02-access-types/localblob.md @@ -1,7 +1,8 @@ # localBlob — Blob Hosted in OCM Repository ## Synopsis -``` + +```text type: localBlob/[VERSION] [ATTRIBUTES] ``` @@ -49,5 +50,3 @@ Attributes: If a resource blob is stored locally, the repository implementation may decide to provide an external access information (usable by non OCM-aware tools). For example, an OCI artifact stored as local blob can be additionally stored as regular OCI artifact in an OCI registry. This additional external access information can be added using a second external access method specification. - - diff --git a/doc/04-extensions/02-access-types/npm.md b/doc/04-extensions/02-access-types/npm.md index aa50f12..c3392e7 100644 --- a/doc/04-extensions/02-access-types/npm.md +++ b/doc/04-extensions/02-access-types/npm.md @@ -1,17 +1,19 @@ # npm — Node Package Manager archive -# Synopsis -``` +## Synopsis + +```text type: npm[/VERSION] [ATTRIBUTES] ``` -# Description +## Description + Access to an NodeJS package in an NPM registry. ## Supported Media Types - - `application/x-tar` +- `application/x-tar` ## Specification Version diff --git a/doc/04-extensions/02-access-types/ociartifact.md b/doc/04-extensions/02-access-types/ociartifact.md index 31ddb87..973b5d4 100644 --- a/doc/04-extensions/02-access-types/ociartifact.md +++ b/doc/04-extensions/02-access-types/ociartifact.md @@ -2,12 +2,13 @@ ## Synopsis -``` +```text type: ociArtifact[/VERSION] [ATTRIBUTES] ``` ## Description + Access of an OCI artifact stored in an OCI registry. ## Supported Media Types @@ -28,6 +29,5 @@ Attributes: - **`imageReference`** *string* OCI image/artifact reference following the possible docker schemes: - - `/:@` - - `[]/repo path>/:@` - + - `/:@` + - `[]/repo path>/:@` diff --git a/doc/04-extensions/02-access-types/ociblob.md b/doc/04-extensions/02-access-types/ociblob.md index 5d669dc..a59f52b 100644 --- a/doc/04-extensions/02-access-types/ociblob.md +++ b/doc/04-extensions/02-access-types/ociblob.md @@ -1,12 +1,14 @@ # ociBlob — Blob hosted in OCI Repository ## Synopsis -``` + +```text type: ociBlob[/VERSION] [ATTRIBUTES] ``` -# Description +## Description + Access of an OCI blob stored in an OCI repository. ## Supported Media Types @@ -35,4 +37,4 @@ Attributes: - **`size`** *integer* - The size of the blob \ No newline at end of file + The size of the blob diff --git a/doc/04-extensions/02-access-types/s3.md b/doc/04-extensions/02-access-types/s3.md index 1370cc5..7839ec3 100644 --- a/doc/04-extensions/02-access-types/s3.md +++ b/doc/04-extensions/02-access-types/s3.md @@ -1,12 +1,14 @@ # s3 — Blob hosted in S3 Blob Store ## Synopsis -``` + +```text type: s3[/VERSION] [ATTRIBUTES] ``` ## Description + Access to a blob stored in an S3 API compatible bucket. ## Supported Media Types @@ -36,4 +38,4 @@ Attributes: - **`mediaType`** *string* The media type of the blob used to store the resource. It may add - format information like `+tar` or `+gzip`. \ No newline at end of file + format information like `+tar` or `+gzip`. diff --git a/doc/04-extensions/03-storage-backends/README.md b/doc/04-extensions/03-storage-backends/README.md index f37716f..4072676 100644 --- a/doc/04-extensions/03-storage-backends/README.md +++ b/doc/04-extensions/03-storage-backends/README.md @@ -3,14 +3,15 @@ The OCM specification describes an interpretation layer on-top of well-known storage backend technologies used to store OCM component versions. -Therefore, for every supported storage technology a dedicated mapping +Therefore, for every supported storage technology a dedicated mapping of OCM model elements to backend elements must be defined to ensure the interoperability of different OCM implementations. These mappings describe: + - the repository specification [type](../../01-model/07-extensions.md#repository-specification) and data stricture used to specify a dedicated repository instance -- the mapping of the [OCM elements](../../01-model/02-elements-toplevel.md) +- the mapping of the [OCM elements](../../01-model/02-elements-toplevel.md) to the elements provided by the storage technology. - the mapping of the abstract model operations to the appropriate backend operations @@ -19,10 +20,10 @@ Mappings for the following technologies are defined: | STORAGE BACKEND | DESCRIPTION | |-----------------|-------------| -| [OCIRegistry](oci.md) | OCM content in OCI registries -| [FileSystem (CTF)](ctf.md) | OCM content as filesystem structure -| [FileSystem (Component Archive)](component-archive.md) | Single component version as content as filesystem structure -| [AWS S3](s3.md) | OCM content in AWS S3 buckets +| [OCIRegistry](oci.md) | OCM content in OCI registries | +| [FileSystem (CTF)](ctf.md) | OCM content as filesystem structure | +| [FileSystem (Component Archive)](component-archive.md) | Single component version as content as filesystem structure | +| [AWS S3](s3.md) | OCM content in AWS S3 buckets | Depending on the used language binding for the OCM model (for example the [reference implementation in Go](https://github.com/open-component-model/ocm)) @@ -66,4 +67,4 @@ The storage backend extension specification is [here](../../01-model/07-extensio This sections describes the abstract model mapping for the storage backend extensions according to layer 3. Different implementations (for different language bindings) MUST implement this mapping -to achieve interoperability among different environments. \ No newline at end of file +to achieve interoperability among different environments. diff --git a/doc/04-extensions/03-storage-backends/component-archive.md b/doc/04-extensions/03-storage-backends/component-archive.md index fe7b1c8..5c95ebd 100644 --- a/doc/04-extensions/03-storage-backends/component-archive.md +++ b/doc/04-extensions/03-storage-backends/component-archive.md @@ -10,7 +10,7 @@ To describe a repository context for an OCM repository conforming to this specif ### Synopsis -``` +```text type: ComponentArchive/v1 ``` @@ -37,7 +37,6 @@ The type specific specification fields are: - `tar`: stored as directory structure in a tar file - `tgz`: stored as directory structure in a tar file compressed by GNU Zip - ## Element Mapping The component-descriptor is stored as top-level file and local blobs in the `blobs`folder. diff --git a/doc/04-extensions/03-storage-backends/ctf.md b/doc/04-extensions/03-storage-backends/ctf.md index edbf365..b8e561c 100644 --- a/doc/04-extensions/03-storage-backends/ctf.md +++ b/doc/04-extensions/03-storage-backends/ctf.md @@ -10,7 +10,7 @@ To describe a repository context for an OCM repository conforming to this specif ### Synopsis -``` +```text type: CommonTransportFormat[/VERSION] [ATTRIBUTES] ``` @@ -35,17 +35,16 @@ The type specific specification fields are: - **`fileFormat`** *string* The file format to use: - - `directory`: stored as file hierarchy in a directory - - `tar`: stored as file hierarchy in a TAR file - - `tgz`: stored as file hierarchy in a GNU-zipped TAR file (tgz) + - `directory`: stored as file hierarchy in a directory + - `tar`: stored as file hierarchy in a TAR file + - `tgz`: stored as file hierarchy in a GNU-zipped TAR file (tgz) - **`accessMode`** (optional) *byte* Access mode used to access the content: - - 0: write access - - 1: read-only - - 2: create id not existent, yet - + - 0: write access + - 1: read-only + - 2: create id not existent, yet ## Element Mapping diff --git a/doc/04-extensions/03-storage-backends/oci.md b/doc/04-extensions/03-storage-backends/oci.md index 4206402..10d31be 100644 --- a/doc/04-extensions/03-storage-backends/oci.md +++ b/doc/04-extensions/03-storage-backends/oci.md @@ -8,11 +8,12 @@ To describe a repository context for an OCM repository conforming to this specif ### Synopsis -``` +```text type: OCIRegistry[/VERSION] [ATTRIBUTES] ``` -``` + +```text type: ociRegistry[/VERSION] [ATTRIBUTES] ``` @@ -21,7 +22,6 @@ type: ociRegistry[/VERSION] Component descriptors and their artifacts will be mapped to an OCI registry according to the [OCI distribution specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md). - ### Specification Versions Supported specification version is `v1`. @@ -76,7 +76,6 @@ According to the [OCI image specification](https://github.com/opencontainers/ima always must be layer 0 of the manifest. It uses the media type `application/vnd.ocm.software.component-descriptor.v2+yaml+tar` - The descriptor layer contains a tar archive with at least a single file with the name `component-descriptor.yaml` containing the component descriptor of the component version. This file should always be the first file in the tar archive. @@ -93,9 +92,11 @@ The tags used to represent versions in the [OCI specification](https://github.co to OCI-compliant tag names. The followinmg mapping for version is used, here: + - the optional plus `+` character used to attach build information in semantic versions is mapped to the sequence (`.build-`) Mapping tags back to versions uses the following mappings: + - the last character sequence (`.build-`) is mapped to a plus (`+`) character. This way the formal parts of a pre-release of semantic version (separated by dots) are kept @@ -198,6 +199,7 @@ The OCI image manifest will then have three layers (one for the component-descri ``` The image configuration is: + ```yaml { "componentDescriptorLayer": { @@ -210,7 +212,7 @@ The image configuration is: If the repo-url is `ghcr.io/open-component-model/spec-example` individual blobs can be accessed using references like -``` +```text ghcr.io/open-component-model/spec-example/component-descriptors/github.com/open-component-model/spec-example@sha256:f5ba8322a580272bbaf93678c48881aa799795bafb9998600655fa669f6ea7bd ghcr.io/open-component-model/spec-example/component-descriptors/github.com/open-component-model/mymaspec-exampleriadb@sha256:0e75813f479e5486985747d6f741ee63d824097c8ee7e48b558bac608bded669 ghcr.io/open-component-model/spec-example/component-descriptors/github.com/open-component-model/spec-example@sha256:7acd701465611ed8a45d7889b4f3f6ed5e1450ca446f90fd6406cc59ea2baea8 diff --git a/doc/04-extensions/03-storage-backends/s3.md b/doc/04-extensions/03-storage-backends/s3.md index 2b672e1..14b60ad 100644 --- a/doc/04-extensions/03-storage-backends/s3.md +++ b/doc/04-extensions/03-storage-backends/s3.md @@ -8,7 +8,7 @@ To describe a repository context for an OCM repository conforming to this specif ### Synopsis -``` +```text type: S3[/VERSION] [ATTRIBIUTES] ``` @@ -47,7 +47,7 @@ The name should be derived from the digest of the blob. For example: -``` +```text └── bucket ├── │   └── __versions__ diff --git a/doc/04-extensions/04-algorithms/README.md b/doc/04-extensions/04-algorithms/README.md index 489ca58..9b14dc3 100644 --- a/doc/04-extensions/04-algorithms/README.md +++ b/doc/04-extensions/04-algorithms/README.md @@ -8,4 +8,4 @@ This chapter lists the different algorithms used within the component model. | [Digest Algorithms](digest-algorithms.md) | Kind of used digest | | [Label Merge Algorithms](label-merge-algorithms.md) | Algorithms to merge label values during delta transport | | [Component Descriptor Normalization Algorithms](component-descriptor-normalization-algorithms.md) | Algorithms used to normalize component descriptors for signing | -| [Signing Algorithms](signing-algorithms.md) | Algorithms used to sign a normalized component version | \ No newline at end of file +| [Signing Algorithms](signing-algorithms.md) | Algorithms used to sign a normalized component version | diff --git a/doc/04-extensions/04-algorithms/artifact-normalization-types.md b/doc/04-extensions/04-algorithms/artifact-normalization-types.md index 2902f30..1877a23 100644 --- a/doc/04-extensions/04-algorithms/artifact-normalization-types.md +++ b/doc/04-extensions/04-algorithms/artifact-normalization-types.md @@ -1,4 +1,5 @@ # Artifact Normalization Types + The following algorithms are defined: - `EXCLUDE-FROM-SIGNATURE`: Blob content is ignored for the signing process. diff --git a/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md b/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md index c8bf1d0..ca0dba6 100644 --- a/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md +++ b/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md @@ -27,7 +27,7 @@ The `JsonNormalisationV1` serialization format is based on the serialization for It uses an appropriate JSON object containing the relevant fields as contained in the component descriptors's serialization. The format version fields are included. Therefore, the normalized form is depending on the chosen serialization format. Changing this format version would result in different digests. -The resulting JSON object is serialized with the [OCM specific scheme](#generic-normalization-format) +The resulting JSON object is serialized with the [OCM specific scheme](../../02-processing/05-component-descriptor-normalization.md#generic-normalization-format) ## `jsonNormalisationV2` @@ -42,4 +42,4 @@ Relevant fields and their mapping to the normalized data structure for `JsonNorm - Component Provider: mapped to `component.provider` - Resources: mapped to `component.resources`, if no resource is present, an empty list is enforced - Sources: mapped to `component.sources`, if no source is present, an empty list is enforced -- References: mapped to `component.references`, if no reference is present, an empty list is enforced \ No newline at end of file +- References: mapped to `component.references`, if no reference is present, an empty list is enforced diff --git a/doc/04-extensions/04-algorithms/label-merge-algorithms.md b/doc/04-extensions/04-algorithms/label-merge-algorithms.md index f10ab13..6859f1a 100644 --- a/doc/04-extensions/04-algorithms/label-merge-algorithms.md +++ b/doc/04-extensions/04-algorithms/label-merge-algorithms.md @@ -1,16 +1,16 @@ # Label Merge Algorithms There is a set of globally defined standard algorithms: - + - `default` just decide for one side or reject the transfer. - + It used the following configuration fields: - `overwrite` *string* specify the behaviour in case of a conflict. The following configuration values are possible: - `none` reject changes - - `local` keep the local value found in the target + - `local` keep the local value found in the target - `inbound` overwrite the local value with the transferred values. THis is the default for this merge algorithm @@ -19,15 +19,15 @@ There is a set of globally defined standard algorithms: The resulting value will contain all the entries of the inbound and the local version. - + - `simpleMapMerge` just merge the elements of a map. The resulting value will contain all the entries of - the inbound and the local version. In case of a + the inbound and the local version. In case of a conflict the entry is merged according the selected overwrite mode ( default `none`) - + The following configuration values are possible: - `overwrite` *string*: conflict resolution hint (see `default`). @@ -38,24 +38,23 @@ There is a set of globally defined standard algorithms: If no overwrite mode is selected AND the `entries` field is given, conflicting entries will be merged with the specified merge specification. Otherwise, the default resolution is `none` - + - `simplemMapListNerge` merge maps used as list entries. - + If a list contains map entries which feature an identity, list entries with the same identity can be merged. This algorithm uses a key field in the maps to detect their identity. - + The following configuration values are possible: - `overwrite` *string*: conflict resolution hint (see `default`). - `entries` [*merge spec*](../../01-model/07-extensions.md#label-merge-algorithms) merge specification to be used for conflicting entries. - + If no overwrite mode is selected AND the `entries` field is given, conflicting entries will be merged with the specified merge specification. Otherwise, the default resolution is `none`. - + All algorithms supporting cascading of merge algorithms for their element (in the meaning defined by the algorithm) SHOULD offer such a merge specification field complying to the standard fields of a merge specification. It is a good practice to use an unset `overwrite` conflict resolution field to enable the cascading and support the other standard options, also. - \ No newline at end of file diff --git a/doc/04-extensions/README.md b/doc/04-extensions/README.md index 58a6b57..60d443a 100644 --- a/doc/04-extensions/README.md +++ b/doc/04-extensions/README.md @@ -5,31 +5,31 @@ However, the specification defines a set of known values for certain types listed in the following sections. These sets can be extended by new specification versions, addendums or for customer-specific environments. -# Table of Content +## Table of Content * 1 [Artifact Types](01-artifact-types/README.md) - * 1.1 [blob](01-artifact-types/blob.md) - * 1.2 [directoryTree, fileSystem](01-artifact-types/file-system.md) - * 1.3 [gitOpsTemplate](01-artifact-types/gitops.md) - * 1.4 [helmChart](01-artifact-types/helmchart.md) - * 1.5 [npmPackage](01-artifact-types/npm.md) - * 1.6 [ociArtifact](01-artifact-types/oci-artifact.md) - * 1.7 [ociImage](01-artifact-types/oci-image.md) - * 1.8 [executable](01-artifact-types/executable.md) - * 1.9 [sbom](01-artifact-types/sbom.md) + * 1.1 [blob](01-artifact-types/blob.md) + * 1.2 [directoryTree, fileSystem](01-artifact-types/file-system.md) + * 1.3 [gitOpsTemplate](01-artifact-types/gitops.md) + * 1.4 [helmChart](01-artifact-types/helmchart.md) + * 1.5 [npmPackage](01-artifact-types/npm.md) + * 1.6 [ociArtifact](01-artifact-types/oci-artifact.md) + * 1.7 [ociImage](01-artifact-types/oci-image.md) + * 1.8 [executable](01-artifact-types/executable.md) + * 1.9 [sbom](01-artifact-types/sbom.md) * 2 [Access Method Types](02-access-types/README.md) - * 2.1 [localBlob](02-access-typeslocalblob.md) - * 2.2 [ociArtifact](02-access-typesociartifact.md) - * 2.3 [ociBlob](02-access-typesociblob.md) - * 2.4 [helm](h02-access-typeselm.md) - * 2.5 [gitHub](02-access-typesgithub.md) - * 2.6 [s3](02-access-typess3.md) - * 2.7 [npm](02-access-typesnpm.md) + * 2.1 [localBlob](02-access-typeslocalblob.md) + * 2.2 [ociArtifact](02-access-typesociartifact.md) + * 2.3 [ociBlob](02-access-typesociblob.md) + * 2.4 [helm](h02-access-typeselm.md) + * 2.5 [gitHub](02-access-typesgithub.md) + * 2.6 [s3](02-access-typess3.md) + * 2.7 [npm](02-access-typesnpm.md) * 3 [Storage Backend Mappings](03-storage-backends/README.md) - * 3.1 [OCIRegistry](03-storage-backendsoci.md) - * 3.2 [FileSystem (CTF)](03-storage-backendsctf.md) - * 3.3 [FileSystem (Component Archive)](03-storage-backendscomponent-archive.md) - * 3.4 [AWS S3](03-storage-backendss3.md) + * 3.1 [OCIRegistry](03-storage-backendsoci.md) + * 3.2 [FileSystem (CTF)](03-storage-backendsctf.md) + * 3.3 [FileSystem (Component Archive)](03-storage-backendscomponent-archive.md) + * 3.4 [AWS S3](03-storage-backendss3.md) * 4 [Algorithms](04-algorithms/README.md) * 4.1 [Artifact Normalization](04-algorithms/artifact-normalization-types.md) * 4.2 [Digest Algorithms](04-algorithms/label-merge-algorithms.md) diff --git a/doc/04-extensions/common/formatspec.md b/doc/04-extensions/common/formatspec.md index a74f491..6017c6c 100644 --- a/doc/04-extensions/common/formatspec.md +++ b/doc/04-extensions/common/formatspec.md @@ -18,7 +18,7 @@ It is a directory containing - **`blobs`** *directory* The *blobs* directory contains the blobs described by the - _artifact index_ as a flat file list. These are layer blobs or artifact + *artifact index* as a flat file list. These are layer blobs or artifact blobs for the artifact descriptors. Every file has a filename according to its [digest](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). Hereby the algorithm separator character is replaced by a dot ("."). @@ -30,7 +30,6 @@ It is a directory containing manifests), which refer to further non-manifest blobs. Files not referenced by the artifacts described by the index are ignored. - This format might be used in various technical forms: as structure of an operating system file system, a virtual file system or as content of an archive file. The descriptor SHOULD be the first file if stored in an archive. @@ -53,7 +52,6 @@ It contains the following properties. - **`index`** *[artifact](#artifact-property-descriptions)* - ### *Artifact* Property Descriptions An artifact consists of a set of properties encapsulated in key-value fields. @@ -62,13 +60,13 @@ The following fields contain the properties that constitute an *Artifact*: - **`repository`** *string* - This REQUIRED property is the _repository_ name of the targeted artifact described by the + This REQUIRED property is the *repository* name of the targeted artifact described by the *Common Transport Format*, conforming to the requirements outlined in the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md). - **`digest`** *string* - This REQUIRED property is the _digest_ of the targeted artifact blob in the targeted + This REQUIRED property is the *digest* of the targeted artifact blob in the targeted artifact set, conforming to the requirements outlined in [Digests](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). Retrieved content SHOULD be verified against this digest when consumed via @@ -76,14 +74,13 @@ The following fields contain the properties that constitute an *Artifact*: - **`tag`** *string* - This optional property is the _tag_ of the targeted artifact, conforming to + This optional property is the *tag* of the targeted artifact, conforming to the requirements outlined in the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md). There might be multiple entries in the artifact list referring to the same artifact with different tags. But all used tags for a repository must be unique. - ## *Artifact Set Archive* Format The *Artifact Set Archive* Format describes a file system structure that can be @@ -146,7 +143,7 @@ For the annotations of the index itself the following keys are defined: This way the format can be used to attach elements according to various extension models for the OCI specification: - - *[cosign](https://github.com/sigstore/cosign)* +- *[cosign](https://github.com/sigstore/cosign)* For *cosign* additional signatures are represented as dedicated artifacts with special tags establishing the relation to the original artifact they @@ -155,7 +152,7 @@ models for the OCI specification: This is supported by this format by providing a possibility to describe additional tags by an annotation in the index - - [*ORAS*](https://github.com/oras-project/artifacts-spec) +- [*ORAS*](https://github.com/oras-project/artifacts-spec) Here a new third top-level manifest type is introduced, that can be stored via the manifest endpoint of the distribution spec. No additional @@ -180,7 +177,7 @@ It is a directory containing - **`blobs`** *directory* The *blobs* directory contains the local blobs described by the - _component descriptor_ as a flat file list. Typically, every + *component descriptor* as a flat file list. Typically, every file has a filename according to its [digest](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). Hereby the algorithm separator character is replaced by a dot ("."). Every file SHOULD be referenced, directly or indirectly, in the @@ -190,4 +187,4 @@ It is a directory containing This format might be used in various technical forms: as structure of an operating system file system, a virtual file system or as content of an archive file. The descriptor SHOULD be the first file if stored in an -archive. \ No newline at end of file +archive. diff --git a/doc/05-guidelines/01-transport.md b/doc/05-guidelines/01-transport.md index f3fee30..6ba705e 100644 --- a/doc/05-guidelines/01-transport.md +++ b/doc/05-guidelines/01-transport.md @@ -17,11 +17,11 @@ The transport target might even be an archive or filesystem. This enables the tr A transport might be done with various options: -- *recursive or non-recursive* +* *recursive or non-recursive* If a component version should be transferred into a local environment all referenced component versions have to be transferred too. This is called a recursive transport. -- *by-value or by-reference* +* *by-value or by-reference* It is possible to transfer component version as they are. This means, only the component version meta information including the component descriptor and the local blobs are transferred, but externally referenced artifacts are kept at their current location. If a transport is done by-value the content of the external artifacts is transferred too. @@ -31,18 +31,17 @@ A transport might be done with various options: A transport of a component version from one component repository into another one can be done in several ways: -- directly from an OCM repository to another one: To support transport by value requires the availability of a blob state in the target environment. -- indirectly using an intermediate file based format: This format must be capable to store blobs that have to be transported side-by-side with the component descriptors. In this format the component descriptor must be capable to describe the access to those locally stored blobs. +* directly from an OCM repository to another one: To support transport by value requires the availability of a blob state in the target environment. +* indirectly using an intermediate file based format: This format must be capable to store blobs that have to be transported side-by-side with the component descriptors. In this format the component descriptor must be capable to describe the access to those locally stored blobs. To simplify and unify the handling of those two scenarios, and generally the handling of blobs in various environments, a component repository must also include support for storing blobs under the identity of the component descriptor. A repository implementation may forward this task to a predefinied other blob store or handle this part of the API in its own way. This enables: -- a simple usage of a component repository to store any content without the need of always requiring other external stores for (possibly specific types of) resources, e.g. for storing simple configuration data along with the component descriptor. -- providing a respository implementation for file system formats that can be used transparently by component tools. -- the usage of a minimal repository environment on the target side of a transport by just using a dedicated component repository. +* a simple usage of a component repository to store any content without the need of always requiring other external stores for (possibly specific types of) resources, e.g. for storing simple configuration data along with the component descriptor. +* providing a respository implementation for file system formats that can be used transparently by component tools. +* the usage of a minimal repository environment on the target side of a transport by just using a dedicated component repository. Therefore, *Component Repositories* MUST provide the possibility to store technical artifacts together with the component descriptors in the component repository itself (as *local blobs*). The general access method type `localBlob` MUST be supported by all repository implementations. This allows packing all component versions with their technical artifacts in a *Component Repository* as a completely self-contained package. As example, assume some component needs additional configuration data stored in some YAML file. If in any landscape of your transport chain there is only an OCI registry available to store content, you need to define a format how to store such a YAML file in the OCI registry. With *local blobs* you could just upload the file into the *Component Repository*. - diff --git a/doc/05-guidelines/02-contract.md b/doc/05-guidelines/02-contract.md index d656a9c..431ae09 100644 --- a/doc/05-guidelines/02-contract.md +++ b/doc/05-guidelines/02-contract.md @@ -29,11 +29,13 @@ A helm chart describes Kubernetes resources, which are templated using values pr Typically, a helm chart contains container image references (often provided as a default value for a template variable). Using such a default value violates the above contract: the location of resources must be taken from the component version describing the deployment (the helm chart). This step is also called *image localization*: All images in a chart must be templated to be able to specify the concrete values by a deployment configuration. An OCM conformant deployment tool must provide the values from the resources of a component version. A tool used to deploy a component version with helm therefore requires several resources: + - all the images required for the helm chart - the helm chart - a helm specific description containig a mapping of value names to image locations of the component version. The OCM-compliant deploy tool (ocm-helm-adapter) must: + - take the helm chart as a resource from the component version - know the format of the mapping description and generate the values for helm. @@ -49,4 +51,4 @@ A deployed image may contain code to deploy pods to a Kubernetes cluster (for ex
OCM and Helm Deployments with indirect Deployments -
\ No newline at end of file + diff --git a/doc/05-guidelines/03-references.md b/doc/05-guidelines/03-references.md index 8eaca5f..1ae9137 100644 --- a/doc/05-guidelines/03-references.md +++ b/doc/05-guidelines/03-references.md @@ -8,7 +8,7 @@ A composite, consisting of an artifact identity and a sequence of reference iden Component Version: `A:1.0.0`: -``` +```yaml apiVersion: ocm.software/v3alpha1 kind: ComponentVersion metadata: @@ -33,7 +33,7 @@ Here we define a component version `A` with a resource having a custom type. Fur Then we have a second component `B:1.0.0` with on OCI image resource: -``` +```yaml apiVersion: ocm.software/v3alpha1 kind: ComponentVersion metadata: diff --git a/doc/05-guidelines/README.md b/doc/05-guidelines/README.md index be3195d..beb11e6 100644 --- a/doc/05-guidelines/README.md +++ b/doc/05-guidelines/README.md @@ -12,4 +12,3 @@ The specification itself does not rely on the information of this chapter. For i * 3 [References](03-references.md#references) * 3.1 [Relative Artifact References](03-references.md#relative-artifact-references) * 3.2 [Absolute Artifact References](03-references.md#absolute-artifact-references) - diff --git a/doc/glossary.md b/doc/glossary.md index 2bd6fb1..3ca030f 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -4,40 +4,49 @@ ## A +#### [Access Method](01-model/07-extensions.md#access-methods) -#### [Access Method](01-model/02-elements.md#access-specification) defines how to access the content of an [artifact](#artifact) #### [Access Method Operations](03-operations/01-operations.md#access-method-operations) + the operations an implementation of an [access method](#accmeth) has to support. #### [Access Method Type](01-model/02-elements.md/#access-types) + the type of an [access specification](#accspec) determining the formal procedure to use to access the blob content of an [artifact](#artifact). -#### [Access Specification](01-model/02-elements.md#access-specification) +#### [Access Specification](01-model/07-extensions.md#access-specification) + the specification of the technical access path to the physical blob content of an [artifact](#artifact. #### [Aggregation](02-processing/01-references.md) + the ability of the Open Component Model to compose component versions based on other component versions. -#### [Artifact](01-model/02-elements.md#artifacts) +#### [Artifact](01-model/02-elements-toplevel.md#artifacts-resources-and-sources) + some blob content described by a [component version](#component-version). -#### [Artifact Digest](02-processing/04-digest.md#artifact-digest) +#### [Artifact Digest](02-processing/03-signing-process.md#determing-the-artifact-digests) + the (logical) digest of an [artifact](#artifact). -#### [Artifact Normalization](02-processing/04-digest.md#normalization) +#### [Artifact Normalization](02-processing/06-artifact-normalization.md) + the transformation of a technical blob content of an [artifact](#artifact) depending on its type into a serialization-agnostic digest. #### [Artifact Reference](02-processing/01-references#referencing) + a relative or absolute reference to an [artifact](#artifact) described by a [component version](#compvers). -#### [Artifact Type](01-model/02-elements.md#artifact-types) +#### [Artifact Type](01-model/02-elements-toplevel.md#artifact-types) + the formal type of an [artifact](#artifact) described by a [component version](#compvers). The type implies the logical interpretation of the artifact blob. @@ -45,63 +54,78 @@ the artifact blob. ## C #### [Component](01-model/01-model.md#components-and-component-versions) + an abstract entity describing a dedicated usage context or meaning for a provided piece of software. #### [Component Descriptor](01-model/01-model.md#components-and-component-versions) + the formal description of a [component version](#compvers). -#### [Component Descriptor Normalization](02-processing/04-digest.md#normalization) +#### [Component Descriptor Normalization](02-processing/05-component-descriptor-normalization.md) + the mapping of the elements of a [component descriptor](#compdesc) into an immutable format containg only signature relevant information used to calculate a digest. #### [Component Identity](01-model/03-elements-sub.md#identifiers) + the globally unique identity of a [component](#component). #### [Component Repository](01-model/01-model.md#component-repositories) + an entity able to store and retrieve [component versions](#compvers). See also [Normalization](#norm) #### [Component Version](01-model/01-model.md#components-and-component-versions) + a dedicated version of a [component](#component) described by the Open Component Model described by a [component descriptor](#compdesc) and retrievable from a [component repository](#comprep). -#### [Component Version Digest](02-processing/04-digest.md#artifact-digest) +#### [Component Version Digest](02-processing/05-component-descriptor-normalization.md#component-descriptor-normalization) + the digest of a [component version](#compvers). #### [Component Version Identity](01-model/01-model.md#components-and-component-versions) + the globally unique identity of a [component version](#compvers). #### [Component Version Reference](02-processing/01-references.md#referencing) + a reference to a [component versions](#compvers) in a component version to describe an aggregation relationship.. ## D #### Digest + see [artifact digest](#artdigest) or [component version digest](#compdigest). ## E #### [Extension Point](./03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) + parts of the [OCM](#ocm) specification, which may be extended by arbitrary variations. The specification just defines the meaning, syntax and or functional behaviour of such elements. #### [Extra Identity](./01-model/03-elements-sub.md#identifiers) + additional parts of the identity of an [element](#elemid) of a [component version](#compvers). ## G #### [`gitHub`](./04-extensions/02-access-types/github.md) + [access method](#accmeth) used to access Git commits in a GitHub repository. ## H #### [`helm`](./04-extensions/02-access-types/helm.md) + [access method](#accmeth) used to access [Helm Charts](#helmchart) in a Helm repository. #### Helm Chart + A set of files describing the deplyoment of a Kubernetes application using the [Helm](https://helm.sh/) deployment mechanism. @@ -110,110 +134,134 @@ see [element identity](#elemid), [component identity](#compid), [component versi ## I #### Identity + see [element identity](#elemid), [component identity](#compid), [component version identity](#compversid) ## L #### [Labels](01-model/03-elements-sub.md#labels) + arbitrary typed information snippets attached to [component versions](#compvers), [artifacts](#artifacts) and [references](#compref). #### [`localBlob`](./04-extensions/02-access-types/localblob.md) + [access method](#accmeth) used to access blobs stored along with a component version. #### [Localization](./05-guidelines/02-contract.md#example-helm-deployment) + the process of adapting content delivered as [artifacts](#artifacts) in a [component versions](#compvers) to a local repository landscape in a target environment. ## M #### [Mapping](./03-persistence/02-mappings.md#mappings-for-ocm-persistence) + the mapping of the [elements](01-model/02-elements.md) of the Open Component Model onto a storage technology described by a [repository type](#repotype). #### [Model-Tool Contract](./05-guidelines/02-contract.md) + The agreement between the Open Component Model and tools working with content provided by [component versions](#compvers), which regulates the cooperation between both. ## N -#### [Normalization](02-processing/04-digest.md#normalization) +#### [Normalization](02-processing/03-signing-process.md#signing-process-and-normalization) + the transformation which can be used to calculate an immutable digest for signing purposes along a transportation path. There are two normalization procedures, [artifact normalization](#artnorm) and [component descriptor normalization](#compdescnorm). #### [`npm`](./04-extensions/02-access-types/npm.md) + [access method](#accmeth) used to access NodeJS packages in an NPM repository. ## O #### [`ociArtifact`](./04-extensions/02-access-types/ociartifact.md) + [access method](#accmeth) used to access OCI artifacts stored in an OCI registry. #### [`ociBlob`](./04-extensions/02-access-types/ociblob.md) + [access method](#accmeth) used to access blobs stored in an OCI registry. #### [Open Component Model](../README.md) + a technology- and location-agnostic description model for software delivery artifacts with attached meta-data, providing environment-specific access path to described [artifacts](#artifact). #### Operations + see [repository operations](#repops), [access methods](#accmeth) and [access method operations](#accmethops). ## P -### [Platform Convention](01-model/06-conventions.md#operating-system-and-cpu-architecture)) +#### [Platform Convention](01-model/06-conventions.md#operating-system-and-cpu-architecture)) + Using extra identities to express the assignment of an [artifact](#artifact) to a dedicated execution platform. ## R #### Reference + a reference to an element of the component model, see [artifact reference](#artref) or [component version reference](#compref) #### [Relative Resource Refererences](02-processing/01-references.md#relative-artifact-references) + a reference to an [artifact](#artifact) described by a [component version](#compvers) relative to a given component version exploiting the [aggregation feature](#aggregation) of the Open Component Model. It is part of the [model-tool contract](#contract). #### [Repository Operations](03-persistence/0-operations.md) + abstract operations that have to be provided by a language binding for a [mapping](#mapping) of the [Open Component Model](#ocm) to a dedicated storage technology. #### [Repository Type](./04-persistence/01-mappings.md#mappings-for-ocm-persistence) + the type of a [mapping](#mapping) of the [Open Component Model](#ocm) specification to a storage technology. #### [Resource](01-model/02-elements-toplevel.md#resources) + a delivery artifact described by a [component version](#compvers). ## S #### [Signature](02-processing/03-signing.md#signing) + a [component version](#compvers) may be signed by an authority, the signature as result of such a signing process is stored along with the component version. #### [Source](01-model/02-elements-toplevel.md#sources) + an artifact described by a [component version](#compvers) containing sources used to generate one or more of the described [resources](#resource). #### Specification Format + a format definition for the specification of attributes for dedicated variants of some [extension points](#ext). See [access methods](#accmeth), [repository types](#repotype), and [labels](#label). #### [`s3`](./04-extensions/02-access-types/s3.md) + [access method](#accmeth) used to access blobs in an S3 repository, a [mapping](#mapping) to store content in an S3 repository ## T #### [Transport](02-guidelines/01-transport.md) + the operation on [component versions](#compvers) transferring content from one OCM repository into another one. #### Type + a formal representation of the kind of an [extension point](#ext) of the [Open Component Model](#ocm). See [repository type](#repotype), [access method type](#acctype), [artifact type](#arttype) [label](#label). diff --git a/doc/markdownlint.json b/doc/markdownlint.json new file mode 100644 index 0000000..8a8197e --- /dev/null +++ b/doc/markdownlint.json @@ -0,0 +1,5 @@ +{ + "default": true, + "MD001": false, + "MD051": false +} \ No newline at end of file From ae14c202f769dea142b58af590e1f087887ad960 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 10:39:39 +0100 Subject: [PATCH 03/14] correct header size --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 58836d2..0e2d669 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ OCM provides a common language usable by tools to talk about software artifacts, The following chapters provide a formal description of the format to describe software artifacts and a storage layer to persist those and make them available from remote. -# Specification +## Specification -## Core Parts +### Core Parts * 1. [Model](doc/01-model/README.md) * 1.1. [OCM Model](doc/01-model/01-model.md#ocm-model) @@ -74,7 +74,7 @@ The following chapters provide a formal description of the format to describe so * 3.3. [Mappings for OCM Persistence](doc/03-persistence/02-mappings.md#mappings-for-ocm-persistence) * 3.3.1. [Storage Backend Mappings for the Open Component Model](doc/03-persistence/02-mappings.md#storage-backend-mappings-for-the-open-component-model) -## Extensible Parts +### Extensible Parts * 4 [Extensions](doc/04-extensions/README.md) * 4.1 [Artifact Types](doc/04-extensions/01-artifact-types/README.md) @@ -107,7 +107,7 @@ The following chapters provide a formal description of the format to describe so * 4.4.4 [Component Descriptor Normalization Algorithms](doc/04-algorithms/04-algorithms/component-descriptor-normalization-algorithms.md) * 4.4.5 [Signing Algorithms](doc/04-algorithms/04-algorithms/signing-algorithms.md) -## Guidelines and Conventions +### Guidelines and Conventions * 5. [Guidelines](doc/05-guidelines/README.md) * 5.1. [Transport](doc/05-guidelines/01-transport.md#transport) @@ -118,7 +118,7 @@ The following chapters provide a formal description of the format to describe so * 5.3.1. [Relative Artifact References](doc/05-guidelines/03-references.md#relative-artifact-references) * 5.3.2. [Absolute Artifact References](doc/05-guidelines/03-references.md#absolute-artifact-references) -## Glossary +### Glossary * 6. [Glossary](doc/glossary.md) From 8ed15b0e75508434dc32cfdef2ca6dc7a55b32e8 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 12:17:24 +0100 Subject: [PATCH 04/14] correct more --- doc/01-model/07-extensions.md | 2 +- doc/04-extensions/01-artifact-types/toipackage.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/01-model/07-extensions.md b/doc/01-model/07-extensions.md index 8b490f1..9818ba0 100644 --- a/doc/01-model/07-extensions.md +++ b/doc/01-model/07-extensions.md @@ -625,7 +625,7 @@ Example: labels: - name: mylabel value: ... - merge: + merge: algorithm: mapListMerge config: keyField: name diff --git a/doc/04-extensions/01-artifact-types/toipackage.md b/doc/04-extensions/01-artifact-types/toipackage.md index 9b4bec6..f6a33f9 100644 --- a/doc/04-extensions/01-artifact-types/toipackage.md +++ b/doc/04-extensions/01-artifact-types/toipackage.md @@ -9,4 +9,4 @@ steps based on content described by the Open Component Model A TOI package is YAML resource describing the installation handling for a dedicated software package based on one or more -[`toiExecutor`](toiexecutor.md)s. \ No newline at end of file +[`toiExecutor`](toiexecutor.md)s. From 3a0b5f264d280e363fb617335d4eb97d68c67b98 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 13:28:33 +0100 Subject: [PATCH 05/14] add back additional checks --- doc/markdownlint.json | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 doc/markdownlint.json diff --git a/doc/markdownlint.json b/doc/markdownlint.json deleted file mode 100644 index 8a8197e..0000000 --- a/doc/markdownlint.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "default": true, - "MD001": false, - "MD051": false -} \ No newline at end of file From 9e29ad90bfbad5d9f870ea93f21c679c97ad6f1c Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 13:56:51 +0100 Subject: [PATCH 06/14] correct link --- doc/04-extensions/01-artifact-types/toipackage.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/04-extensions/01-artifact-types/toipackage.md b/doc/04-extensions/01-artifact-types/toipackage.md index f6a33f9..c7fb9e3 100644 --- a/doc/04-extensions/01-artifact-types/toipackage.md +++ b/doc/04-extensions/01-artifact-types/toipackage.md @@ -4,8 +4,7 @@ TOI is a small toolset on top of the [Open Component Model](../../01-model/01-mo It provides a possibility to run images taken from a component version with user configuration and feed them with the content of this component version. It is some basic mechanism which can be used to execute simple installation -steps based on content described by the Open Component Model -(see https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi-bootstrapping.md). +steps based on content described by the Open Component Model (see the [TOI documenation](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi-bootstrapping.md).) A TOI package is YAML resource describing the installation handling for a dedicated software package based on one or more From ac5a68c9906e220fd1ed4b8fe354704d871ff4d0 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 14:18:45 +0100 Subject: [PATCH 07/14] check if it works now --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0e2d669..679f15d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The _Open Component Model (OCM)_ is an open standard to describe software-bill-of-deliveries (SBOD). OCM is a technology-agnostic and machine-readable format focused on the software artifacts that must be delivered for software products. OCM provides a globally unique identity scheme which can be used to identify components and artifacts throughout the entire software lifecycle management process,... -Its focus is to describe versioned sets of artifacts and to assign globally unique identities. OCM makes those artifacts queryable: what is inside, where is it from, is it authentic, etc. But it does not deal with building those artifacts or how to deploy them. Such tasks are left to tools on top of the model. In this way, they are able to access the artifact by its identity. Different tools may keep their own metadata bound together by the identities provided by the model. +Its focus is describing versioned sets of artifacts and to assign globally unique identities. OCM makes those artifacts queryable: what is inside, where is it from, is it authentic, etc. But it does not deal with building those artifacts or how to deploy them. Such tasks are left to tools on top of the model. In this way, they are able to access the artifact by its identity. Different tools may keep their own metadata bound together by the identities provided by the model. OCM provides a common language usable by tools to talk about software artifacts, regardless of the technologies and the processes working on them. Tool specific metadata, like deployment descriptions, are handled as own, typed artifacts. This enables the provisioning of content-agnostic tools: for example, transporting software between environments, signing and verification, providing compliance data, etc. From adfab5ce2dda8aaa7e749894b708baa964ad95c8 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 14:23:42 +0100 Subject: [PATCH 08/14] remove additional check from markdownlinter --- .github/.markdownlint.yml | 1 + doc/glossary.md | 98 +++++++++++++++++++-------------------- 2 files changed, 50 insertions(+), 49 deletions(-) diff --git a/.github/.markdownlint.yml b/.github/.markdownlint.yml index 531db89..8f3b3a5 100644 --- a/.github/.markdownlint.yml +++ b/.github/.markdownlint.yml @@ -1,4 +1,5 @@ default: true MD013: false #https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md013 +MD029: false #https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md033 MD033: false #https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md033 diff --git a/doc/glossary.md b/doc/glossary.md index 3ca030f..952ecdb 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -4,48 +4,48 @@ ## A -#### [Access Method](01-model/07-extensions.md#access-methods) +### [Access Method](01-model/07-extensions.md#access-methods) defines how to access the content of an [artifact](#artifact) -#### [Access Method Operations](03-operations/01-operations.md#access-method-operations) +### [Access Method Operations](03-operations/01-operations.md#access-method-operations) the operations an implementation of an [access method](#accmeth) has to support. -#### [Access Method Type](01-model/02-elements.md/#access-types) +### [Access Method Type](01-model/02-elements.md/#access-types) the type of an [access specification](#accspec) determining the formal procedure to use to access the blob content of an [artifact](#artifact). -#### [Access Specification](01-model/07-extensions.md#access-specification) +### [Access Specification](01-model/07-extensions.md#access-specification) the specification of the technical access path to the physical blob content of an [artifact](#artifact. -#### [Aggregation](02-processing/01-references.md) +### [Aggregation](02-processing/01-references.md) the ability of the Open Component Model to compose component versions based on other component versions. -#### [Artifact](01-model/02-elements-toplevel.md#artifacts-resources-and-sources) +### [Artifact](01-model/02-elements-toplevel.md#artifacts-resources-and-sources) some blob content described by a [component version](#component-version). -#### [Artifact Digest](02-processing/03-signing-process.md#determing-the-artifact-digests) +### [Artifact Digest](02-processing/03-signing-process.md#determing-the-artifact-digests) the (logical) digest of an [artifact](#artifact). -#### [Artifact Normalization](02-processing/06-artifact-normalization.md) +### [Artifact Normalization](02-processing/06-artifact-normalization.md) the transformation of a technical blob content of an [artifact](#artifact) depending on its type into a serialization-agnostic digest. -#### [Artifact Reference](02-processing/01-references#referencing) +### [Artifact Reference](02-processing/01-references#referencing) a relative or absolute reference to an [artifact](#artifact) described by a [component version](#compvers). -#### [Artifact Type](01-model/02-elements-toplevel.md#artifact-types) +### [Artifact Type](01-model/02-elements-toplevel.md#artifact-types) the formal type of an [artifact](#artifact) described by a [component version](#compvers). The type implies the logical interpretation of @@ -53,78 +53,78 @@ the artifact blob. ## C -#### [Component](01-model/01-model.md#components-and-component-versions) +### [Component](01-model/01-model.md#components-and-component-versions) an abstract entity describing a dedicated usage context or meaning for a provided piece of software. -#### [Component Descriptor](01-model/01-model.md#components-and-component-versions) +### [Component Descriptor](01-model/01-model.md#components-and-component-versions) the formal description of a [component version](#compvers). -#### [Component Descriptor Normalization](02-processing/05-component-descriptor-normalization.md) +### [Component Descriptor Normalization](02-processing/05-component-descriptor-normalization.md) the mapping of the elements of a [component descriptor](#compdesc) into an immutable format containg only signature relevant information used to calculate a digest. -#### [Component Identity](01-model/03-elements-sub.md#identifiers) +### [Component Identity](01-model/03-elements-sub.md#identifiers) the globally unique identity of a [component](#component). -#### [Component Repository](01-model/01-model.md#component-repositories) +### [Component Repository](01-model/01-model.md#component-repositories) an entity able to store and retrieve [component versions](#compvers). See also [Normalization](#norm) -#### [Component Version](01-model/01-model.md#components-and-component-versions) +### [Component Version](01-model/01-model.md#components-and-component-versions) a dedicated version of a [component](#component) described by the Open Component Model described by a [component descriptor](#compdesc) and retrievable from a [component repository](#comprep). -#### [Component Version Digest](02-processing/05-component-descriptor-normalization.md#component-descriptor-normalization) +### [Component Version Digest](02-processing/05-component-descriptor-normalization.md#component-descriptor-normalization) the digest of a [component version](#compvers). -#### [Component Version Identity](01-model/01-model.md#components-and-component-versions) +### [Component Version Identity](01-model/01-model.md#components-and-component-versions) the globally unique identity of a [component version](#compvers). -#### [Component Version Reference](02-processing/01-references.md#referencing) +### [Component Version Reference](02-processing/01-references.md#referencing) a reference to a [component versions](#compvers) in a component version to describe an aggregation relationship.. ## D -#### Digest +### Digest see [artifact digest](#artdigest) or [component version digest](#compdigest). ## E -#### [Extension Point](./03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) +### [Extension Point](./03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) parts of the [OCM](#ocm) specification, which may be extended by arbitrary variations. The specification just defines the meaning, syntax and or functional behaviour of such elements. -#### [Extra Identity](./01-model/03-elements-sub.md#identifiers) +### [Extra Identity](./01-model/03-elements-sub.md#identifiers) additional parts of the identity of an [element](#elemid) of a [component version](#compvers). ## G -#### [`gitHub`](./04-extensions/02-access-types/github.md) +### [`gitHub`](./04-extensions/02-access-types/github.md) [access method](#accmeth) used to access Git commits in a GitHub repository. ## H -#### [`helm`](./04-extensions/02-access-types/helm.md) +### [`helm`](./04-extensions/02-access-types/helm.md) [access method](#accmeth) used to access [Helm Charts](#helmchart) in a Helm repository. -#### Helm Chart +### Helm Chart A set of files describing the deplyoment of a Kubernetes application using the [Helm](https://helm.sh/) deployment mechanism. @@ -133,32 +133,32 @@ see [element identity](#elemid), [component identity](#compid), [component versi ## I -#### Identity +### Identity see [element identity](#elemid), [component identity](#compid), [component version identity](#compversid) ## L -#### [Labels](01-model/03-elements-sub.md#labels) +### [Labels](01-model/03-elements-sub.md#labels) arbitrary typed information snippets attached to [component versions](#compvers), [artifacts](#artifacts) and [references](#compref). -#### [`localBlob`](./04-extensions/02-access-types/localblob.md) +### [`localBlob`](./04-extensions/02-access-types/localblob.md) [access method](#accmeth) used to access blobs stored along with a component version. -#### [Localization](./05-guidelines/02-contract.md#example-helm-deployment) +### [Localization](./05-guidelines/02-contract.md#example-helm-deployment) the process of adapting content delivered as [artifacts](#artifacts) in a [component versions](#compvers) to a local repository landscape in a target environment. ## M -#### [Mapping](./03-persistence/02-mappings.md#mappings-for-ocm-persistence) +### [Mapping](./03-persistence/02-mappings.md#mappings-for-ocm-persistence) the mapping of the [elements](01-model/02-elements.md) of the Open Component Model onto a storage technology described by a [repository type](#repotype). -#### [Model-Tool Contract](./05-guidelines/02-contract.md) +### [Model-Tool Contract](./05-guidelines/02-contract.md) The agreement between the Open Component Model and tools working with content provided by [component versions](#compvers), which regulates the cooperation @@ -166,101 +166,101 @@ between both. ## N -#### [Normalization](02-processing/03-signing-process.md#signing-process-and-normalization) +### [Normalization](02-processing/03-signing-process.md#signing-process-and-normalization) the transformation which can be used to calculate an immutable digest for signing purposes along a transportation path. There are two normalization procedures, [artifact normalization](#artnorm) and [component descriptor normalization](#compdescnorm). -#### [`npm`](./04-extensions/02-access-types/npm.md) +### [`npm`](./04-extensions/02-access-types/npm.md) [access method](#accmeth) used to access NodeJS packages in an NPM repository. ## O -#### [`ociArtifact`](./04-extensions/02-access-types/ociartifact.md) +### [`ociArtifact`](./04-extensions/02-access-types/ociartifact.md) [access method](#accmeth) used to access OCI artifacts stored in an OCI registry. -#### [`ociBlob`](./04-extensions/02-access-types/ociblob.md) +### [`ociBlob`](./04-extensions/02-access-types/ociblob.md) [access method](#accmeth) used to access blobs stored in an OCI registry. -#### [Open Component Model](../README.md) +### [Open Component Model](../README.md) a technology- and location-agnostic description model for software delivery artifacts with attached meta-data, providing environment-specific access path to described [artifacts](#artifact). -#### Operations +### Operations see [repository operations](#repops), [access methods](#accmeth) and [access method operations](#accmethops). ## P -#### [Platform Convention](01-model/06-conventions.md#operating-system-and-cpu-architecture)) +### [Platform Convention](01-model/06-conventions.md#operating-system-and-cpu-architecture)) Using extra identities to express the assignment of an [artifact](#artifact) to a dedicated execution platform. ## R -#### Reference +### Reference a reference to an element of the component model, see [artifact reference](#artref) or [component version reference](#compref) -#### [Relative Resource Refererences](02-processing/01-references.md#relative-artifact-references) +### [Relative Resource Refererences](02-processing/01-references.md#relative-artifact-references) a reference to an [artifact](#artifact) described by a [component version](#compvers) relative to a given component version exploiting the [aggregation feature](#aggregation) of the Open Component Model. It is part of the [model-tool contract](#contract). -#### [Repository Operations](03-persistence/0-operations.md) +### [Repository Operations](03-persistence/0-operations.md) abstract operations that have to be provided by a language binding for a [mapping](#mapping) of the [Open Component Model](#ocm) to a dedicated storage technology. -#### [Repository Type](./04-persistence/01-mappings.md#mappings-for-ocm-persistence) +### [Repository Type](./04-persistence/01-mappings.md#mappings-for-ocm-persistence) the type of a [mapping](#mapping) of the [Open Component Model](#ocm) specification to a storage technology. -#### [Resource](01-model/02-elements-toplevel.md#resources) +### [Resource](01-model/02-elements-toplevel.md#resources) a delivery artifact described by a [component version](#compvers). ## S -#### [Signature](02-processing/03-signing.md#signing) +### [Signature](02-processing/03-signing.md#signing) a [component version](#compvers) may be signed by an authority, the signature as result of such a signing process is stored along with the component version. -#### [Source](01-model/02-elements-toplevel.md#sources) +### [Source](01-model/02-elements-toplevel.md#sources) an artifact described by a [component version](#compvers) containing sources used to generate one or more of the described [resources](#resource). -#### Specification Format +### Specification Format a format definition for the specification of attributes for dedicated variants of some [extension points](#ext). See [access methods](#accmeth), [repository types](#repotype), and [labels](#label). -#### [`s3`](./04-extensions/02-access-types/s3.md) +### [`s3`](./04-extensions/02-access-types/s3.md) [access method](#accmeth) used to access blobs in an S3 repository, a [mapping](#mapping) to store content in an S3 repository ## T -#### [Transport](02-guidelines/01-transport.md) +### [Transport](02-guidelines/01-transport.md) the operation on [component versions](#compvers) transferring content from one OCM repository into another one. -#### Type +### Type a formal representation of the kind of an [extension point](#ext) of the [Open Component Model](#ocm). See [repository type](#repotype), From 4d350107cedeb2fa8e00c8ac85a16663d16cf5bc Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 14:45:27 +0100 Subject: [PATCH 09/14] correct line starts --- README.md | 115 ++++++++++++++++++------------------ doc/02-processing/README.md | 18 +++--- 2 files changed, 66 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 679f15d..88848bf 100644 --- a/README.md +++ b/README.md @@ -17,62 +17,61 @@ The following chapters provide a formal description of the format to describe so ### Core Parts * 1. [Model](doc/01-model/README.md) - * 1.1. [OCM Model](doc/01-model/01-model.md#ocm-model) - * 1.1.1. [Introduction](doc/01-model/01-model.md#introduction) - * 1.1.2. [Components and Component Versions](doc/01-model/01-model.md#components-and-component-versions) - * 1.1.3. [Component Repositories](doc/01-model/01-model.md#component-repositories) - * 1.1.4. [Summary](doc/01-model/01-model.md#summary) + * 1.1 [OCM Model](doc/01-model/01-model.md#ocm-model) + * 1.1.1 [Introduction](doc/01-model/01-model.md#introduction) + * 1.1.2 [Components and Component Versions](doc/01-model/01-model.md#components-and-component-versions) + * 1.1.3 [Component Repositories](doc/01-model/01-model.md#component-repositories) + * 1.1.4 [Summary](doc/01-model/01-model.md#summary) * 1.2. [Model Elements](doc/01-model/02-elements-toplevel.md#model-elements) - * 1.2.1. [Components and Component Versions](doc/01-model/02-elements-toplevel.md#components-and-component-versions) - * 1.2.2. [Artifacts (Resources and Sources)](doc/01-model/02-elements-toplevel.md#artifacts-resources-and-sources) - * 1.2.3. [Sources](doc/01-model/02-elements-toplevel.md#sources) - * 1.2.4. [Resources](doc/01-model/02-elements-toplevel.md#resources) - * 1.2.5. [References](doc/01-model/02-elements-toplevel.md#references) - * 1.2.6. [Summary](doc/01-model/02-elements-toplevel.md#summary) + * 1.2.1 [Components and Component Versions](doc/01-model/02-elements-toplevel.md#components-and-component-versions) + * 1.2.2 [Artifacts (Resources and Sources)](doc/01-model/02-elements-toplevel.md#artifacts-resources-and-sources) + * 1.2.3 [Sources](doc/01-model/02-elements-toplevel.md#sources) + * 1.2.4 [Resources](doc/01-model/02-elements-toplevel.md#resources) + * 1.2.5 [References](doc/01-model/02-elements-toplevel.md#references) + * 1.2.6 [Summary](doc/01-model/02-elements-toplevel.md#summary) * 1.3. [Model Elements - Fundamentals](doc/01-model/03-elements-sub.md) - * 1.3.1. [Identifiers](doc/01-model/03-elements-sub.md#identifiers) - * 1.3.2. [Access Specification](doc/01-model/03-elements-sub.md#access-specification) - * 1.3.3. [Access Types](doc/01-model/03-elements-sub.md#access-types) - * 1.3.4. [Labels](doc/01-model/03-elements-sub.md#labels) - * 1.3.5. [Repository Contexts](doc/01-model/03-elements-sub.md#repository-contexts) - * 1.3.6. [Signatures](doc/01-model/03-elements-sub.md#signatures) - * 1.3.7. [Digest Info](doc/01-model/03-elements-sub.md#digest-info) - * 1.3.8. [Signature Info](doc/01-model/03-elements-sub.md#signature-info) - * 1.4. [Example of a complete Component Version](doc/01-model/04-example.md#example-of-a-complete-component-version) - * 1.5. [Conventions](doc/01-model/06-conventions.md#conventions) - * 1.5.1. [Intended Environments](doc/01-model/06-conventions.md#intended-environments) - * 1.5.2. [Selection of Usage Scenarios](doc/01-model/06-conventions.md#selection-of-usage-scenarios) - * 1.6. [Extending the Open Component Model](doc/01-model/07-extensions.md#extending-the-open-component-model) - * 1.6.1. [Functional extensions](doc/01-model/07-extensions.md#functional-extensions) - * 1.6.2. [Semantic extensions](doc/01-model/07-extensions.md#semantic-extensions) + * 1.3.1 [Identifiers](doc/01-model/03-elements-sub.md#identifiers) + * 1.3.2 [Access Specification](doc/01-model/03-elements-sub.md#access-specification) + * 1.3.3 [Access Types](doc/01-model/03-elements-sub.md#access-types) + * 1.3.4 [Labels](doc/01-model/03-elements-sub.md#labels) + * 1.3.5 [Repository Contexts](doc/01-model/03-elements-sub.md#repository-contexts) + * 1.3.6 [Signatures](doc/01-model/03-elements-sub.md#signatures) + * 1.3.7 [Digest Info](doc/01-model/03-elements-sub.md#digest-info) + * 1.3.8 [Signature Info](doc/01-model/03-elements-sub.md#signature-info) + * 1.4 [Example of a complete Component Version](doc/01-model/04-example.md#example-of-a-complete-component-version) + * 1.5 [Conventions](doc/01-model/06-conventions.md#conventions) + * 1.5.1 [Intended Environments](doc/01-model/06-conventions.md#intended-environments) + * 1.5.2 [Selection of Usage Scenarios](doc/01-model/06-conventions.md#selection-of-usage-scenarios) + * 1.6 [Extending the Open Component Model](doc/01-model/07-extensions.md#extending-the-open-component-model) + * 1.6.1 [Functional extensions](doc/01-model/07-extensions.md#functional-extensions) + * 1.6.2 [Semantic extensions](doc/01-model/07-extensions.md#semantic-extensions) * 2. [Processing](doc/02-processing/README.md) - * 2.1. [Referencing](doc/02-processing/01-references.md#referencing) - * 2.1.1. [Example](doc/02-processing/01-references.md#example) - * 2.2. [Signing](doc/02-processing/03-signing.md#signing) - * 2.2.1. [Verification Procedure](doc/02-processing/03-signing.md#verification-procedure) - * 2.3. [Normalization](doc/02-processing/04-digest.md#normalization) - * 2.3.1. [Artifact Digest](doc/02-processing/04-digest.md#artifact-digest) - * 2.3.2. [Normalization Types](doc/02-processing/04-digest.md#normalization-types) - * 2.3.3. [Serialization Format](doc/02-processing/04-digest.md#serialization-format) - * 2.3.4. [Recursive Digest Calculation](doc/02-processing/04-digest.md#recursive-digest-calculation) - * 2.4. [Example](doc/02-processing/04-digest.md#example) - * 2.4.1. [Simple Component-Version](doc/02-processing/04-digest.md#simple-component-version) - * 2.4.2. [Component-Version With Reference](doc/02-processing/04-digest.md#component-version-with-reference) - * 2.5. [Component Descriptor Normalization](doc/02-processing/04-digest.md#component-descriptor-normalization) - * 2.5.1. [Relevant information in Component Descriptors](doc/02-processing/04-digest.md#relevant-information-in-component-descriptors) - * 2.5.2. [Labels](doc/02-processing/04-digest.md#labels) - * 2.5.3. [Exclude Resources from Normalization/Signing](doc/02-processing/04-digest.md#exclude-resources-from-normalizationsigning) - * 2.5.4. [Generic Normalization Format](doc/02-processing/04-digest.md#generic-normalization-format) - * 2.6. [Artifact Normalization](doc/02-processing/04-digest.md#artifact-normalization) - * 2.6.1. [Blob Representation Format for Resource Types](doc/02-processing/04-digest.md#blob-representation-format-for-resource-types) - * 2.6.2. [Interaction of Local Blobs, Access Methods, Uploaders and Media Types](doc/02-processing/04-digest.md#interaction-of-local-blobs-access-methods-uploaders-and-media-types) + * 2.1 [Referencing](doc/02-processing/01-references.md#referencing) + * 2.1.1 [Example](doc/02-processing/01-references.md#example) + * 2.2 [Signing](doc/02-processing/03-signing.md#signing) + * 2.2.1 [Verification Procedure](doc/02-processing/03-signing.md#verification-procedure) + * 2.3 [Normalization](doc/02-processing/03-signing-process.md#signing-process-and-normalization) + * 2.3.1 [Artifact Digest](doc/02-processing/03-signing-process.md#determing-the-artifact-digests) + * 2.3.2 [Normalization Types](doc/02-processing/03-signing-process.md#normalization-types) + * 2.3.3 [Serialization Format](doc/02-processing/03-signing-process.md#serialization-format) + * 2.3.4 [Recursive Digest Calculation](doc/02-processing/03-signing-process.md#recursive-digest-calculation) + * 2.4 [Example](doc/02-processing/04-signing-examples.md#examples-for-signing-of-component-version) + * 2.4.1 [Simple Component-Version](doc/02-processing/04-signing-examples.md#simple-component-version) + * 2.4.2 [Component-Version With Reference](doc/02-processing/04-signing-examples.md#component-version-with-reference) + * 2.5 [Component Descriptor Normalization](doc/02-processing/04-signing-examples.md#component-descriptor-normalization) + * 2.5.1 [Signing-relevant information in Component Descriptors](doc/02-processing/04-signing-examples.md#relevant-information-in-component-descriptors) + * 2.5.2 [Exclude Resources from Normalization/Signing](doc/02-processing/05-component-descriptor-normalization.md#exclude-resources-from-normalizationsigning) + * 2.5.3 [Generic Normalization Format](doc/02-processing/05-component-descriptor-normalization.md#generic-normalization-format) + * 2.6 [Artifact Normalization](doc/02-processing/06-artifact-normalization.md#artifact-normalization) + * 2.6.1 [Blob Representation Format for Resource Types](doc/02-processing/06-artifact-normalization.md#blob-representation-format-for-resource-types) + * 2.6.2 [Interaction of Local Blobs, Access Methods, Uploaders and Media Types](doc/02-processing/06-artifact-normalization.md#interaction-of-local-blobs-access-methods-uploaders-and-media-types) * 3. [Persistence](doc/03-persistence/README.md) - * 3.1. [Model Operations](doc/03-persistence/01-operations.md#model-operations) - * 3.2. [Abstract Operations defined by the Open Component Model](doc/03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) - * 3.2.1. [Repository Operations](doc/03-persistence/01-operations.md#repository-operations) - * 3.2.2. [Access Method Operations](doc/03-persistence/01-operations.md#access-method-operations) + * 3.1 [Model Operations](doc/03-persistence/01-operations.md#model-operations) + * 3.2 [Abstract Operations defined by the Open Component Model](doc/03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) + * 3.2.1 [Repository Operations](doc/03-persistence/01-operations.md#repository-operations) + * 3.2.2 [Access Method Operations](doc/03-persistence/01-operations.md#access-method-operations) * 3.3. [Mappings for OCM Persistence](doc/03-persistence/02-mappings.md#mappings-for-ocm-persistence) - * 3.3.1. [Storage Backend Mappings for the Open Component Model](doc/03-persistence/02-mappings.md#storage-backend-mappings-for-the-open-component-model) + * 3.3.1 [Storage Backend Mappings for the Open Component Model](doc/03-persistence/02-mappings.md#storage-backend-mappings-for-the-open-component-model) ### Extensible Parts @@ -110,13 +109,13 @@ The following chapters provide a formal description of the format to describe so ### Guidelines and Conventions * 5. [Guidelines](doc/05-guidelines/README.md) - * 5.1. [Transport](doc/05-guidelines/01-transport.md#transport) - * 5.1.1. [Kinds of Transports](doc/05-guidelines/01-transport.md#kinds-of-transports) - * 5.2. [Model Contract](doc/05-guidelines/02-contract.md#model-contract) - * 5.2.1. [Example: Helm deployment](doc/05-guidelines/02-contract.md#example-helm-deployment) - * 5.3. [References](doc/05-guidelines/03-references.md#references) - * 5.3.1. [Relative Artifact References](doc/05-guidelines/03-references.md#relative-artifact-references) - * 5.3.2. [Absolute Artifact References](doc/05-guidelines/03-references.md#absolute-artifact-references) + * 5.1 [Transport](doc/05-guidelines/01-transport.md#transport) + * 5.1.1 [Kinds of Transports](doc/05-guidelines/01-transport.md#kinds-of-transports) + * 5.2 [Model Contract](doc/05-guidelines/02-contract.md#model-contract) + * 5.2.1 [Example: Helm deployment](doc/05-guidelines/02-contract.md#example-helm-deployment) + * 5.3 [References](doc/05-guidelines/03-references.md#references) + * 5.3.1 [Relative Artifact References](doc/05-guidelines/03-references.md#relative-artifact-references) + * 5.3.2 [Absolute Artifact References](doc/05-guidelines/03-references.md#absolute-artifact-references) ### Glossary diff --git a/doc/02-processing/README.md b/doc/02-processing/README.md index 7215376..fa6ec66 100644 --- a/doc/02-processing/README.md +++ b/doc/02-processing/README.md @@ -17,16 +17,16 @@ This chapter explains how to create and use components. * 4.1.[Simple Component-Version](04-signing-examples.md#simple-component-version) * 4.2.[Component-Version With Reference](04-signing-examples.md#component-version-with-reference) * 5.[Component Descriptor Normalization](04-signing-examples.md#component-descriptor-normalization) - * 5.1.[Relevant information in Component Descriptors](04-signing-examples.md#relevant-information-in-component-descriptors) + * 5.1.[Signing-relevant information in Component Descriptors](04-signing-examples.md#relevant-information-in-component-descriptors) * 5.1.1.[Access Methods](05-component-descriptor-normalization.md#access-methods) - * 5.2.[Labels](05-component-descriptor-normalization.md#labels) - * 5.3.[Exclude Resources from Normalization/Signing](05-component-descriptor-normalization.md#exclude-resources-from-normalizationsigning) - * 5.4.[Generic Normalization Format](05-component-descriptor-normalization.md#generic-normalization-format) - * 5.4.1.[Simple Values](05-component-descriptor-normalization.md#simple-values) - * 5.4.2.[Dictionary](05-component-descriptor-normalization.md#dictionary) - * 5.4.3.[Lists](05-component-descriptor-normalization.md#lists) - * 5.4.4.[Combined example](05-component-descriptor-normalization.md#combined-example) - * 5.4.5.[Empty values](05-component-descriptor-normalization.md#empty-values) + * 5.1.2.[Labels](05-component-descriptor-normalization.md#labels) + * 5.2.[Exclude Resources from Normalization/Signing](05-component-descriptor-normalization.md#exclude-resources-from-normalizationsigning) + * 5.3.[Generic Normalization Format](05-component-descriptor-normalization.md#generic-normalization-format) + * 5.3.1.[Simple Values](05-component-descriptor-normalization.md#simple-values) + * 5.3.2.[Dictionary](05-component-descriptor-normalization.md#dictionary) + * 5.3.3.[Lists](05-component-descriptor-normalization.md#lists) + * 5.3.4.[Combined example](05-component-descriptor-normalization.md#combined-example) + * 5.3.5.[Empty values](05-component-descriptor-normalization.md#empty-values) * 6.[Artifact Normalization](06-artifact-normalization.md#artifact-normalization) * 6.1.[Blob Representation Format for Resource Types](06-artifact-normalization.md#blob-representation-format-for-resource-types) * 6.2.[Interaction of Local Blobs, Access Methods, Uploaders and Media Types](06-artifact-normalization.md#interaction-of-local-blobs-access-methods-uploaders-and-media-types) From ed77a68ad434a9f74008d2cf9bc016beab9d5b03 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 17:52:49 +0100 Subject: [PATCH 10/14] correct some minor things --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 88848bf..7fa3669 100644 --- a/README.md +++ b/README.md @@ -48,8 +48,8 @@ The following chapters provide a formal description of the format to describe so * 2. [Processing](doc/02-processing/README.md) * 2.1 [Referencing](doc/02-processing/01-references.md#referencing) * 2.1.1 [Example](doc/02-processing/01-references.md#example) - * 2.2 [Signing](doc/02-processing/03-signing.md#signing) - * 2.2.1 [Verification Procedure](doc/02-processing/03-signing.md#verification-procedure) + * 2.2 [Signing](doc/02-processing/02-signing.md#signing) + * 2.2.1 [Verification Procedure](doc/02-processing/02-signing.md#verification-procedure) * 2.3 [Normalization](doc/02-processing/03-signing-process.md#signing-process-and-normalization) * 2.3.1 [Artifact Digest](doc/02-processing/03-signing-process.md#determing-the-artifact-digests) * 2.3.2 [Normalization Types](doc/02-processing/03-signing-process.md#normalization-types) @@ -95,15 +95,15 @@ The following chapters provide a formal description of the format to describe so * 4.2.6 [s3](doc/04-extensions/02-access-types/s3.md) * 4.2.7 [npm](doc/04-extensions/02-access-types/npm.md) * 4.3 [Storage Backend Mappings](doc/04-extensions/03-storage-backends/README.md) - * 4.3.1 [OCIRegistry](doc/04-extensions/03-storage-backend/soci.md) + * 4.3.1 [OCIRegistry](doc/04-extensions/03-storage-backends/oci.md) * 4.3.2 [FileSystem (CTF)](doc/04-extensions/03-storage-backends/ctf.md) * 4.3.3 [FileSystem (Component Archive)](doc/04-extensions/03-storage-backends/component-archive.md) * 4.3.4 [AWS S3](doc/04-extensions/03-storage-backends/s3.md) * 4.4 [Algorithms](doc/04-extensions/04-algorithms/README.md) - * 4.4.1 [Artifact Normalization](doc/04-algorithms/04-algorithms/artifact-normalization-types.md) - * 4.4.2 [Digest Algorithms](doc/04-algorithms/04-algorithms/label-merge-algorithms.md) - * 4.4.3 [Label Merge Algorithm](doc/04-algorithms/04-algorithms/digest-algorithms.md) - * 4.4.4 [Component Descriptor Normalization Algorithms](doc/04-algorithms/04-algorithms/component-descriptor-normalization-algorithms.md) + * 4.4.1 [Artifact Normalization](doc/04-extensions/04-algorithms/artifact-normalization-types.md) + * 4.4.2 [Digest Algorithms](doc/04-extensions/04-algorithms/label-merge-algorithms.md) + * 4.4.3 [Label Merge Algorithm](doc/04-extensions/04-algorithms/digest-algorithms.md) + * 4.4.4 [Component Descriptor Normalization Algorithms](doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md) * 4.4.5 [Signing Algorithms](doc/04-algorithms/04-algorithms/signing-algorithms.md) ### Guidelines and Conventions @@ -123,7 +123,7 @@ The following chapters provide a formal description of the format to describe so ## Central OCM project web page -Check out the main project [web page](https://ocm.software) to find out more about OCM. It is your central entry point to all kinds of ocm related [docs and guides](https://ocm.software/docoverview/context), this [spec](https://ocm.software/spec/) and all project-related [github repositories](https://github.com/open-component-model). It also offers a [Getting Started](https://ocm.software/docs/guides/getting-started-with-ocm) to quickly make your hands dirty with ocm, its toolset and concepts :-) +Check out the main project [web page](https://ocm.software) to find out more about OCM. It is your central entry point to all kinds of ocm related [docs and guides](https://ocm.software/docs/overview/context/), this [spec](https://ocm.software/spec/) and all project-related [github repositories](https://github.com/open-component-model). It also offers a [Getting Started](https://ocm.software/docs/guides/getting-started-with-ocm) to quickly make your hands dirty with ocm, its toolset and concepts :-) ## Contributing From 2800826d54699db907f6a65f65a758d87aa6d533 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 18:39:22 +0100 Subject: [PATCH 11/14] correct last wrong links...hopefully :-) --- README.md | 2 +- doc/01-model/06-conventions.md | 2 +- doc/02-processing/03-signing-process.md | 2 +- .../05-component-descriptor-normalization.md | 2 +- doc/03-persistence/02-mappings.md | 2 +- doc/04-extensions/01-artifact-types/README.md | 4 ++-- .../01-artifact-types/helmchart.md | 2 +- .../01-artifact-types/toiexecutor.md | 2 +- doc/04-extensions/README.md | 22 +++++++++---------- doc/04-extensions/common/formatspec.md | 4 ++-- doc/glossary.md | 16 +++++++------- 11 files changed, 30 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 7fa3669..25c41c4 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ The following chapters provide a formal description of the format to describe so * 4.4.2 [Digest Algorithms](doc/04-extensions/04-algorithms/label-merge-algorithms.md) * 4.4.3 [Label Merge Algorithm](doc/04-extensions/04-algorithms/digest-algorithms.md) * 4.4.4 [Component Descriptor Normalization Algorithms](doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md) - * 4.4.5 [Signing Algorithms](doc/04-algorithms/04-algorithms/signing-algorithms.md) + * 4.4.5 [Signing Algorithms](doc/04-extensions/04-algorithms/signing-algorithms.md) ### Guidelines and Conventions diff --git a/doc/01-model/06-conventions.md b/doc/01-model/06-conventions.md index df3cfc4..46d761c 100644 --- a/doc/01-model/06-conventions.md +++ b/doc/01-model/06-conventions.md @@ -26,6 +26,6 @@ If platform specific images are described as separate resources instead of using ## Selection of Usage Scenarios -Usage scenarios for sets of described artifacts are best described by a dedicated [description artifacts](../../specification/contract/README.md#how-does-it-look-like-in-the-open-component-model) with a dedicated tool-specific artifact type. Here, there is the complete freedom to describe the conditions and environments artifacts are to be used. The artifacts are described by [relative resource references](../05-guidelines/03-references.md#relative-artifact-references) in relation to the component version containing the description artifact. +Usage scenarios for sets of described artifacts are best described by a dedicated description artifact with a dedicated tool-specific artifact type. Here, there is the complete freedom to describe the conditions and environments artifacts are to be used. The artifacts are described by [relative resource references](../05-guidelines/03-references.md#relative-artifact-references) in relation to the component version containing the description artifact. Another possibility is to use dedicated [labels](./03-elements-sub.md#labels) to describe the usage scenario for dedicated artifacts. Here, the tool working on a component versions does not read a description artifact, but has to analyse the label settings of all the provided artifacts. In both cases there is a dedicated OCM specific interpretation of content provided by the component model. But while the first solution allows to describe a closed scenario in a dedicated resource, where resources from dependent component version can be described by relative resource references and multiple scenarios can be separated by multiple flavors of this resource, the label-based approach is restricted to a local component version and a single scenario. Instead of an artifact type for the description, labels with a defined [name structure](./03-elements-sub.md#labels) are required. diff --git a/doc/02-processing/03-signing-process.md b/doc/02-processing/03-signing-process.md index 5a837e0..a750719 100644 --- a/doc/02-processing/03-signing-process.md +++ b/doc/02-processing/03-signing-process.md @@ -76,7 +76,7 @@ Normalization algorithm types may be versioned and SHOULD match the following re For example: `ociArtifactDigest/v1` or `jsonNormalisationV2` -The normalization algorithms are listed in the [extensible parts](../04-extensions/01-extensions.md#normalization-algorithms) of the specification +The normalization algorithms are listed in the [extensible parts](../04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md) of the specification ## Serialization Format diff --git a/doc/02-processing/05-component-descriptor-normalization.md b/doc/02-processing/05-component-descriptor-normalization.md index 2b8c551..10a7db4 100644 --- a/doc/02-processing/05-component-descriptor-normalization.md +++ b/doc/02-processing/05-component-descriptor-normalization.md @@ -20,7 +20,7 @@ A normalized component descriptor is a subset of its elements containing only th Like for signature algorithms, the model offers the possibility to work with different normalization algorithms and formats. -The algorithms used for normalization are listed in the [extensible parts](../04-extensions/01-extensions.md#normalization-algorithms) of the specification. +The algorithms used for normalization are listed in the [extensible parts](../04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md) of the specification. ## Signing-relevant Information in Component Descriptors diff --git a/doc/03-persistence/02-mappings.md b/doc/03-persistence/02-mappings.md index a21bee9..f1a23c5 100644 --- a/doc/03-persistence/02-mappings.md +++ b/doc/03-persistence/02-mappings.md @@ -4,7 +4,7 @@ This chapter describes how OCM model elements are mapped to elements of a persis OCM model elements are mapped to various storage technologies. The interoperability layer for a client tool is typically the API of the storage backend. This avoids the need for providing an OCM server infrastructure. -An implementation of this layer MUST implement this mapping by supporting the [mandatory abstract model operations](./01-operations#mandatory-operations). It SHOULD implement the [optional operations](./01-operations#optional-operations) too. +An implementation of this layer MUST implement this mapping by supporting the [mandatory abstract model operations](./01-operations.md#mandatory-operations). It SHOULD implement the [optional operations](./01-operations#optional-operations) too. ## Storage Backend Mappings for the Open Component Model diff --git a/doc/04-extensions/01-artifact-types/README.md b/doc/04-extensions/01-artifact-types/README.md index e8fd144..b435b97 100644 --- a/doc/04-extensions/01-artifact-types/README.md +++ b/doc/04-extensions/01-artifact-types/README.md @@ -31,5 +31,5 @@ Some additional types are defined, but not part of the core specification. Suppo | TYPE NAME |DESCRIPTION | |--------------------|-------------------------------------| | [`blueprint`](blueprint.md) | An installation description for the [landscaper](https://github.com/gardener/landscaper) installation | -| [`toiExecutor`](toiExecutor.md) | A toolset for simple installation in the [OCM CLI](https://github.com/open-component-model/ocm/blob/cm_toi.md) installation environment. | -| [`toiPackage`](toiPackackage.md) | A YAML resource describing the installation for the [OCM CLI](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi.md) TOI installation. | +| [`toiExecutor`](toiexecutor.md) | A toolset for simple installation in the [OCM CLI](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi.md) installation environment. | +| [`toiPackage`](toipackage.md) | A YAML resource describing the installation for the [OCM CLI](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi.md) TOI installation. | diff --git a/doc/04-extensions/01-artifact-types/helmchart.md b/doc/04-extensions/01-artifact-types/helmchart.md index 4c0fbf7..7ddd41e 100644 --- a/doc/04-extensions/01-artifact-types/helmchart.md +++ b/doc/04-extensions/01-artifact-types/helmchart.md @@ -12,7 +12,7 @@ A Kubernetes installation resource representing a Helm chart, either stored as O - **OCI Artifact** - A Helm chart might be stored as OCI artifact following the [Artifact Set Archive Format](../common/formatspec.md#artifact-set-archive-format). This format is for example provided by the access method type [`ociArtifact`](../02-access-types/oci-artifact.md) + A Helm chart might be stored as OCI artifact following the [Artifact Set Archive Format](../common/formatspec.md#artifact-set-archive-format). This format is for example provided by the access method type [`ociArtifact`](../02-access-types/ociartifact.md) Media types: - `application/vnd.oci.image.manifest.v1+tar` diff --git a/doc/04-extensions/01-artifact-types/toiexecutor.md b/doc/04-extensions/01-artifact-types/toiexecutor.md index a848329..ec74d17 100644 --- a/doc/04-extensions/01-artifact-types/toiexecutor.md +++ b/doc/04-extensions/01-artifact-types/toiexecutor.md @@ -11,5 +11,5 @@ steps based on content described by the Open Component Model A TOI executor is YAML resource describing the features of an TOI executor image. -It is used by a [`toiPackage` resource](toiPackage.md), which +It is used by a [`toiPackage` resource](./toipackage.md), which describes its instantiation for a dedicated installation object. diff --git a/doc/04-extensions/README.md b/doc/04-extensions/README.md index 60d443a..9fbf309 100644 --- a/doc/04-extensions/README.md +++ b/doc/04-extensions/README.md @@ -18,18 +18,18 @@ addendums or for customer-specific environments. * 1.8 [executable](01-artifact-types/executable.md) * 1.9 [sbom](01-artifact-types/sbom.md) * 2 [Access Method Types](02-access-types/README.md) - * 2.1 [localBlob](02-access-typeslocalblob.md) - * 2.2 [ociArtifact](02-access-typesociartifact.md) - * 2.3 [ociBlob](02-access-typesociblob.md) - * 2.4 [helm](h02-access-typeselm.md) - * 2.5 [gitHub](02-access-typesgithub.md) - * 2.6 [s3](02-access-typess3.md) - * 2.7 [npm](02-access-typesnpm.md) + * 2.1 [localBlob](02-access-types/localblob.md) + * 2.2 [ociArtifact](02-access-types/ociartifact.md) + * 2.3 [ociBlob](02-access-types/ociblob.md) + * 2.4 [helm](h02-access-types/elm.md) + * 2.5 [gitHub](02-access-types/github.md) + * 2.6 [s3](02-access-types/s3.md) + * 2.7 [npm](02-access-types/npm.md) * 3 [Storage Backend Mappings](03-storage-backends/README.md) - * 3.1 [OCIRegistry](03-storage-backendsoci.md) - * 3.2 [FileSystem (CTF)](03-storage-backendsctf.md) - * 3.3 [FileSystem (Component Archive)](03-storage-backendscomponent-archive.md) - * 3.4 [AWS S3](03-storage-backendss3.md) + * 3.1 [OCIRegistry](03-storage-backends/oci.md) + * 3.2 [FileSystem (CTF)](03-storage-backends/ctf.md) + * 3.3 [FileSystem (Component Archive)](03-storage-backends/component-archive.md) + * 3.4 [AWS S3](03-storage-backends/s3.md) * 4 [Algorithms](04-algorithms/README.md) * 4.1 [Artifact Normalization](04-algorithms/artifact-normalization-types.md) * 4.2 [Digest Algorithms](04-algorithms/label-merge-algorithms.md) diff --git a/doc/04-extensions/common/formatspec.md b/doc/04-extensions/common/formatspec.md index 6017c6c..ce0fb36 100644 --- a/doc/04-extensions/common/formatspec.md +++ b/doc/04-extensions/common/formatspec.md @@ -172,7 +172,7 @@ It is a directory containing - **`component-descriptor.yaml`** *YAML file* - This yaml is the serialized form of a [component descriptor](../../specification/elements#component-descriptor). + This yaml is the serialized form of a [component descriptor](../../01-model/01-model.md#components-and-component-versions). - **`blobs`** *directory* @@ -182,7 +182,7 @@ It is a directory containing Hereby the algorithm separator character is replaced by a dot ("."). Every file SHOULD be referenced, directly or indirectly, in the component descriptor by a - [`localBlob` access specification](../../appendix/B/localBlob.md). The `localReference` value is the file name of the blob file in the `blobs` directory. + [`localBlob` access specification](../../04-extensions/01-artifact-types/blob.md). The `localReference` value is the file name of the blob file in the `blobs` directory. This format might be used in various technical forms: as structure of an operating system file system, a virtual file system or as content of diff --git a/doc/glossary.md b/doc/glossary.md index 952ecdb..83071dd 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -8,11 +8,11 @@ defines how to access the content of an [artifact](#artifact) -### [Access Method Operations](03-operations/01-operations.md#access-method-operations) +### [Access Method Operations](01-model/07-extensions.md#access-method-operations) the operations an implementation of an [access method](#accmeth) has to support. -### [Access Method Type](01-model/02-elements.md/#access-types) +### [Access Method Type](04-extensions/02-access-types/README.md) the type of an [access specification](#accspec) determining the formal procedure to use to access the blob content of an [artifact](#artifact). @@ -40,7 +40,7 @@ the (logical) digest of an [artifact](#artifact). the transformation of a technical blob content of an [artifact](#artifact) depending on its type into a serialization-agnostic digest. -### [Artifact Reference](02-processing/01-references#referencing) +### [Artifact Reference](02-processing/01-references.md#referencing) a relative or absolute reference to an [artifact](#artifact) described by a [component version](#compvers). @@ -156,7 +156,7 @@ the process of adapting content delivered as [artifacts](#artifacts) in a [compo ### [Mapping](./03-persistence/02-mappings.md#mappings-for-ocm-persistence) -the mapping of the [elements](01-model/02-elements.md) of the Open Component Model onto a storage technology described by a [repository type](#repotype). +the mapping of the [elements](01-model/02-elements-toplevel.md) of the Open Component Model onto a storage technology described by a [repository type](#repotype). ### [Model-Tool Contract](./05-guidelines/02-contract.md) @@ -216,13 +216,13 @@ a reference to an [artifact](#artifact) described by a [component version](#comp a given component version exploiting the [aggregation feature](#aggregation) of the Open Component Model. It is part of the [model-tool contract](#contract). -### [Repository Operations](03-persistence/0-operations.md) +### [Repository Operations](03-persistence/01-operations.md#repository-operations) abstract operations that have to be provided by a language binding for a [mapping](#mapping) of the [Open Component Model](#ocm) to a dedicated storage technology. -### [Repository Type](./04-persistence/01-mappings.md#mappings-for-ocm-persistence) +### [Repository Type](./03-persistence/02-mappings.md#mappings-for-ocm-persistence) the type of a [mapping](#mapping) of the [Open Component Model](#ocm) specification to a storage technology. @@ -233,7 +233,7 @@ a delivery artifact described by a [component version](#compvers). ## S -### [Signature](02-processing/03-signing.md#signing) +### [Signature](02-processing/02-signing.md#signing) a [component version](#compvers) may be signed by an authority, the signature as result of such a signing process is stored along with the component version. @@ -255,7 +255,7 @@ dedicated variants of some [extension points](#ext). See [access methods](#accme ## T -### [Transport](02-guidelines/01-transport.md) +### [Transport](05-guidelines/01-transport.md) the operation on [component versions](#compvers) transferring content from one OCM repository into another one. From ddfc03e33958a33e20594bb4dba45f199624de25 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 18:42:58 +0100 Subject: [PATCH 12/14] typo --- doc/04-extensions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/04-extensions/README.md b/doc/04-extensions/README.md index 9fbf309..cad9ab6 100644 --- a/doc/04-extensions/README.md +++ b/doc/04-extensions/README.md @@ -21,7 +21,7 @@ addendums or for customer-specific environments. * 2.1 [localBlob](02-access-types/localblob.md) * 2.2 [ociArtifact](02-access-types/ociartifact.md) * 2.3 [ociBlob](02-access-types/ociblob.md) - * 2.4 [helm](h02-access-types/elm.md) + * 2.4 [helm](02-access-types/elm.md) * 2.5 [gitHub](02-access-types/github.md) * 2.6 [s3](02-access-types/s3.md) * 2.7 [npm](02-access-types/npm.md) From c82f9be189cd91e02b0e965a58761ae6e7840510 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 18:45:39 +0100 Subject: [PATCH 13/14] typo --- doc/03-persistence/02-mappings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/03-persistence/02-mappings.md b/doc/03-persistence/02-mappings.md index f1a23c5..259c442 100644 --- a/doc/03-persistence/02-mappings.md +++ b/doc/03-persistence/02-mappings.md @@ -4,7 +4,7 @@ This chapter describes how OCM model elements are mapped to elements of a persis OCM model elements are mapped to various storage technologies. The interoperability layer for a client tool is typically the API of the storage backend. This avoids the need for providing an OCM server infrastructure. -An implementation of this layer MUST implement this mapping by supporting the [mandatory abstract model operations](./01-operations.md#mandatory-operations). It SHOULD implement the [optional operations](./01-operations#optional-operations) too. +An implementation of this layer MUST implement this mapping by supporting the [mandatory abstract model operations](./01-operations.md#mandatory-operations). It SHOULD implement the [optional operations](./01-operations.md#optional-operations) too. ## Storage Backend Mappings for the Open Component Model From 0eeab32d12a076efac3d9b188f702a7e13f119e5 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 18:49:51 +0100 Subject: [PATCH 14/14] last one --- doc/04-extensions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/04-extensions/README.md b/doc/04-extensions/README.md index cad9ab6..1935a7d 100644 --- a/doc/04-extensions/README.md +++ b/doc/04-extensions/README.md @@ -21,7 +21,7 @@ addendums or for customer-specific environments. * 2.1 [localBlob](02-access-types/localblob.md) * 2.2 [ociArtifact](02-access-types/ociartifact.md) * 2.3 [ociBlob](02-access-types/ociblob.md) - * 2.4 [helm](02-access-types/elm.md) + * 2.4 [helm](02-access-types/helm.md) * 2.5 [gitHub](02-access-types/github.md) * 2.6 [s3](02-access-types/s3.md) * 2.7 [npm](02-access-types/npm.md)