diff --git a/definitions-terms.md b/definitions-terms.md new file mode 100644 index 00000000..4959f6af --- /dev/null +++ b/definitions-terms.md @@ -0,0 +1,104 @@ +# Definitions and Terms + +A collection of definitions and terms used within this repository. + +## TOC + +* [Fingerprint](#fingerprint) +* [Fully Qualified Artifact Reference](#registry-fully-qualified-reference) +* [OCI Annotations](#oci-annotations) +* [OCI Descriptor](#oci-descriptor) +* [OCI Index](#oci-index) +* [OCI Manifest](#oci-manifest) +* [Registry](#registry) +* [Repo/Repository](#repo/repository) +* [Repository Path](#repository-path) +* [SBoM](#sbom) +* [Subject](#subject) +* [Tag](#tag) + +## Artifact / Image + +Artifacts are a generalization of how images are stored in an instance of the [OCI Distribution Spec][oci-distribution-spec]. An [OCI Image][oci-image] is a type of [OCI Artifact][oci-artifact]. When referencing artifacts, within a [fully qualified reference](#registry-fully-qualified-reference), the artifact is right most element of the namespace, combined with the `:tag`. +Reference: [OCI Artifacts][oci-artifact] +![](./media/artifact-ref.png) + + +## Fingerprint + +A short identifier of a given public key. +Reference: [Fingerprint][fingerprint] + + +## OCI Annotations + +A key-value map that can be associated with [OCI Descriptors][oci-descriptor] and [OCI Image manifests][oci-manifest]. +OCI spec reference: [OCI Annotations][oci-annotations] + +## OCI Descriptor + +A structure describing content, including the media type, a content-addressable digest, the size, and other properties. Descriptors are used to describe layers and configuration in a manifest. +OCI spec reference: [OCI Descriptor][oci-descriptor] + +## OCI Index + +A higher-level collection of [image manifests][oci-manifest], or other [oci indexes][oci-index], typically used to describe platform-specific (architecture and operating-system) images that can be identified collectively and referred to together. The specific image manifests are identified by modified [descriptors][oci-descriptor] with additional properties and restrictions. [OCI Artifacts][oci-artifact] are another use-case for indexes where an OCI Index can reference a collection of artifacts, such as an image, a deployment chart, its SBoM and deployment configuration references. +OCI spec reference: [OCI Image Index][oci-index] + +## OCI Manifest + +A description of an [artifact][oci-artifact]. The manifest references optional configuration and blobs (layers) as content-addressable references ([descriptors][oci-descriptor]). Artifacts may be container images, helm charts or other artifact types that may be signed and stored in a registry. +OCI spec reference: [OCI Image Manifest][oci-manifest] + +## Registry + +A registry is a collection of [OCI Indexes][oci-index] and [OCI Manifests][oci-manifest] for a specific org or entity. +A unique registry may be uniquely identified with a domain or a root namespace: +![](./media/unique-registry-domain-ref.png) +![](./media/unique-registry-namespace-ref.png) + +## Repo/Repository + +A repo/repository refers to the unique location, within a registry. When referring to a repo, the registry is assumed, based on the context. +![](./media/registry-repo-ref.png) + +## Repository Path + +A path, within the [unique registry org](#multi-tenant-registry), up to, but not including the repository (repo) name. +![](./media/registry-namespace-ref.png) + +## Registry: Fully Qualified Reference + +In order to deploy an artifact, a fully qualified reference is required. This includes the unique registry, namespace, repo and tag. +![](./media/fully-qualified-artifact-ref.png) + +## SBoM + +Represents a generic, non-project specific, reference to a Software Bill of Materials. Similar to the automotive industry which tracks the components that make up a vehicle, the SBoM may contain the list of packages used within the artifact, the compiler and version used to build the artifact and other relevant information. +Additional reference: [Software bill of materials][sbom] + +## Subject + +The data that is signed. + +## Tag + +Information that represents a version, or platform specific version of the artifact. +eg: +- `example.com/org/namespace/artifact:tag` +- `org.example.com/namespace/artifact:tag` +- `org.example.com/databases/somedb:v1` (multi-arch tag) +- `org.example.com/databases/somedb:v1-alpine` (platform specific tag) +- `org.example.com/databases/somedb:v1-windows` (platform specific tag) +- `org.example.com/databases/somedb:v1-helm` (helm chart to deploy a platform specific image) + + +[fingerprint]: https://en.wikipedia.org/wiki/Public_key_fingerprint +[oci-annotations]: https://github.com/opencontainers/image-spec/blob/master/annotations.md +[oci-artifact]: https://github.com/opencontainers/artifacts +[oci-descriptor]: https://github.com/opencontainers/image-spec/blob/master/descriptor.md +[oci-distribution-spec]: https://github.com/opencontainers/distribution-spec +[oci-image]: https://github.com/opencontainers/image-spec +[oci-index]: https://github.com/opencontainers/image-spec/blob/master/image-index.md +[oci-manifest]: https://github.com/opencontainers/image-spec/blob/master/manifest.md +[sbom]: https://en.wikipedia.org/wiki/Software_bill_of_materials \ No newline at end of file diff --git a/media/artifact-ref.png b/media/artifact-ref.png new file mode 100644 index 00000000..80f5b71b Binary files /dev/null and b/media/artifact-ref.png differ diff --git a/media/fully-qualified-artifact-ref.png b/media/fully-qualified-artifact-ref.png new file mode 100644 index 00000000..2f4cd1c3 Binary files /dev/null and b/media/fully-qualified-artifact-ref.png differ diff --git a/media/registry-namespace-ref.png b/media/registry-namespace-ref.png new file mode 100644 index 00000000..ff867c57 Binary files /dev/null and b/media/registry-namespace-ref.png differ diff --git a/media/registry-repo-ref.png b/media/registry-repo-ref.png new file mode 100644 index 00000000..7cad77d3 Binary files /dev/null and b/media/registry-repo-ref.png differ diff --git a/media/registry-repo-tag-ref.png b/media/registry-repo-tag-ref.png new file mode 100644 index 00000000..4d32347a Binary files /dev/null and b/media/registry-repo-tag-ref.png differ diff --git a/media/unique-registry-domain-ref.png b/media/unique-registry-domain-ref.png new file mode 100644 index 00000000..dbf3d6a9 Binary files /dev/null and b/media/unique-registry-domain-ref.png differ diff --git a/media/unique-registry-namespace-ref.png b/media/unique-registry-namespace-ref.png new file mode 100644 index 00000000..173fcbd5 Binary files /dev/null and b/media/unique-registry-namespace-ref.png differ