From 9b7193aa199cb0abe3a20b453ec19200d91da4b1 Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Fri, 27 Oct 2023 09:20:13 +0100 Subject: [PATCH] Moved container attributes to the registry (#417) Signed-off-by: ChrsMark Co-authored-by: Alexander Wert --- docs/attributes-registry/README.md | 2 + docs/attributes-registry/container.md | 30 +++++++++ docs/attributes-registry/oci.md | 14 +++++ docs/resource/container.md | 46 ++++---------- model/registry/container.yaml | 86 +++++++++++++++++++++++++ model/{resource => registry}/oci.yaml | 4 +- model/resource/container.yaml | 91 ++++----------------------- 7 files changed, 159 insertions(+), 114 deletions(-) create mode 100644 docs/attributes-registry/container.md create mode 100644 docs/attributes-registry/oci.md create mode 100644 model/registry/container.yaml rename model/{resource => registry}/oci.yaml (93%) diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 81002bd95..a4995ec5f 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -27,8 +27,10 @@ All registered attributes are listed by namespace in this registry. Currently, the following namespaces exist: +* [Container](container.md) * [HTTP](http.md) * [Network](network.md) +* [OCI](oci.md) * [RPC](rpc.md) * [URL](url.md) * [User agent](user-agent.md) diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md new file mode 100644 index 000000000..7cc959620 --- /dev/null +++ b/docs/attributes-registry/container.md @@ -0,0 +1,30 @@ + + +# Container + +## Container Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | +| `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | +| `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | +| `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | +| `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | +| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | +| `container.image.repo_digests` | string[] | Repo digests of the container image as provided by the container runtime. [3] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | +| `container.image.tags` | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `[v1.27.1, 3.5.7-0]` | +| `container.labels.` | string | Container labels, `` being the label name, the value being the label value. | `container.labels.app=nginx` | +| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | +| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | + +**[1]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. + +**[2]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint. +K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. +The ID is assinged by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. + +**[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. + diff --git a/docs/attributes-registry/oci.md b/docs/attributes-registry/oci.md new file mode 100644 index 000000000..abfc4f747 --- /dev/null +++ b/docs/attributes-registry/oci.md @@ -0,0 +1,14 @@ +# Open Container Initiative (OCI) + +The [Open Container Initiative](https://opencontainers.org/) defines open industry standards around container formats and runtimes. + +## OCI Image Manifest + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `oci.manifest.digest` | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [1] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | + +**[1]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). +An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). + \ No newline at end of file diff --git a/docs/resource/container.md b/docs/resource/container.md index 827e20b77..1abdd5c27 100644 --- a/docs/resource/container.md +++ b/docs/resource/container.md @@ -9,17 +9,18 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | Opt-In | -| `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | Opt-In | -| `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | Opt-In | -| `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | Recommended | -| `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | Recommended | -| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended | -| `container.image.repo_digests` | string[] | Repo digests of the container image as provided by the container runtime. [3] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | Recommended | -| `container.image.tags` | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `[v1.27.1, 3.5.7-0]` | Recommended | -| `container.labels.` | string | Container labels, `` being the label name, the value being the label value. | `container.labels.app=nginx` | Recommended | -| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended | -| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | +| [`container.command`](../attributes-registry/container.md) | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | Opt-In | +| [`container.command_args`](../attributes-registry/container.md) | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | Opt-In | +| [`container.command_line`](../attributes-registry/container.md) | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | Opt-In | +| [`container.id`](../attributes-registry/container.md) | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | Recommended | +| [`container.image.id`](../attributes-registry/container.md) | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | Recommended | +| [`container.image.name`](../attributes-registry/container.md) | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended | +| [`container.image.repo_digests`](../attributes-registry/container.md) | string[] | Repo digests of the container image as provided by the container runtime. [3] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | Recommended | +| [`container.image.tags`](../attributes-registry/container.md) | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `[v1.27.1, 3.5.7-0]` | Recommended | +| [`container.labels.`](../attributes-registry/container.md) | string | Container labels, `` being the label name, the value being the label value. | `container.labels.app=nginx` | Recommended | +| [`container.name`](../attributes-registry/container.md) | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended | +| [`container.runtime`](../attributes-registry/container.md) | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | +| [`oci.manifest.digest`](../attributes-registry/oci.md) | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [4] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | Recommended | **[1]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. @@ -28,29 +29,8 @@ K8s defines a link to the container registry repository with digest `"imageID": The ID is assinged by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. **[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. - -## Open Container Initiative (OCI) - -The [Open Container Initiative](https://opencontainers.org/) defines open industry standards around container formats and runtimes. - -### OCI Image Manifest - -This section refers to the [specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md) -that defines an OCI Image manifest. - -**Status**: [Experimental][DocumentStatus] - -**type:** `oci` - -**Description:** Attributes of an OCI image manifest. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `oci.manifest.digest` | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [1] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | Recommended | - -**[1]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). +**[4]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). diff --git a/model/registry/container.yaml b/model/registry/container.yaml new file mode 100644 index 000000000..6909fe4ec --- /dev/null +++ b/model/registry/container.yaml @@ -0,0 +1,86 @@ +groups: + - id: registry.container + prefix: container + type: attribute_group + brief: > + A container instance. + attributes: + - id: name + type: string + brief: > + Container name used by container runtime. + examples: ['opentelemetry-autoconf'] + - id: id + type: string + brief: > + Container ID. Usually a UUID, as for example used to + [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). + The UUID might be abbreviated. + examples: ['a3bf90e006b2'] + - id: runtime + type: string + brief: > + The container runtime managing this container. + examples: ['docker', 'containerd', 'rkt'] + - id: image.name + type: string + brief: > + Name of the image the container was built on. + examples: ['gcr.io/opentelemetry/operator'] + - id: image.tags + type: string[] + brief: > + Container image tags. An example can be found in + [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). + Should be only the `` section of the full name for example + from `registry.example.com/my-org/my-image:`. + examples: ['v1.27.1', '3.5.7-0'] + - id: image.id + type: string + brief: > + Runtime specific image identifier. Usually a hash algorithm followed by a UUID. + note: > + Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker + container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) + endpoint. + + K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io + /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. + + The ID is assinged by the container runtime and can vary in different environments. + Consider using `oci.manifest.digest` if it is important to identify the same + image in different environments/runtimes. + examples: ['sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f'] + - id: image.repo_digests + type: string[] + brief: > + Repo digests of the container image as provided by the container runtime. + note: > + [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and + [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) + report those under the `RepoDigests` field. + examples: + - 'example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb' + - 'internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578' + - id: command + type: string + note: > + If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. + brief: > + The command used to run the container (i.e. the command name). + examples: [ 'otelcontribcol' ] + - id: command_line + type: string + brief: > + The full command run by the container as a single string representing the full command. [2] + examples: [ 'otelcontribcol --config config.yaml' ] + - id: command_args + type: string[] + brief: > + All the command arguments (including the command/executable itself) run by the container. [2] + examples: [ 'otelcontribcol, --config, config.yaml' ] + - id: labels + type: template[string] + brief: > + Container labels, `` being the label name, the value being the label value. + examples: [ 'container.labels.app=nginx' ] diff --git a/model/resource/oci.yaml b/model/registry/oci.yaml similarity index 93% rename from model/resource/oci.yaml rename to model/registry/oci.yaml index fc1ff2ebb..24e0cb93f 100644 --- a/model/resource/oci.yaml +++ b/model/registry/oci.yaml @@ -1,7 +1,7 @@ groups: - - id: oci.manifest + - id: registry.oci.manifest prefix: oci.manifest - type: resource + type: attribute_group brief: > An OCI image manifest. attributes: diff --git a/model/resource/container.yaml b/model/resource/container.yaml index 2080b7b9c..97923e440 100644 --- a/model/resource/container.yaml +++ b/model/resource/container.yaml @@ -5,85 +5,18 @@ groups: brief: > A container instance. attributes: - - id: name - type: string - brief: > - Container name used by container runtime. - examples: ['opentelemetry-autoconf'] - - id: id - type: string - brief: > - Container ID. Usually a UUID, as for example used to - [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). - The UUID might be abbreviated. - examples: ['a3bf90e006b2'] - - id: runtime - type: string - brief: > - The container runtime managing this container. - examples: ['docker', 'containerd', 'rkt'] - - id: image.name - type: string - brief: > - Name of the image the container was built on. - examples: ['gcr.io/opentelemetry/operator'] - - id: image.tags - type: string[] - brief: > - Container image tags. An example can be found in - [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). - Should be only the `` section of the full name for example - from `registry.example.com/my-org/my-image:`. - examples: ['v1.27.1', '3.5.7-0'] - - id: image.id - type: string - brief: > - Runtime specific image identifier. Usually a hash algorithm followed by a UUID. - note: > - Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker - container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) - endpoint. - - K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io - /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. - - The ID is assinged by the container runtime and can vary in different environments. - Consider using `oci.manifest.digest` if it is important to identify the same - image in different environments/runtimes. - examples: ['sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f'] - - id: image.repo_digests - type: string[] - brief: > - Repo digests of the container image as provided by the container runtime. - note: > - [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and - [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) - report those under the `RepoDigests` field. - examples: - - 'example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb' - - 'internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578' - - id: command - type: string + - ref: container.name + - ref: container.id + - ref: container.runtime + - ref: container.image.name + - ref: container.image.tags + - ref: container.image.id + - ref: container.image.repo_digests + - ref: container.command requirement_level: opt_in - note: > - If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. - brief: > - The command used to run the container (i.e. the command name). - examples: [ 'otelcontribcol' ] - - id: command_line - type: string + - ref: container.command_line requirement_level: opt_in - brief: > - The full command run by the container as a single string representing the full command. [2] - examples: [ 'otelcontribcol --config config.yaml' ] - - id: command_args - type: string[] + - ref: container.command_args requirement_level: opt_in - brief: > - All the command arguments (including the command/executable itself) run by the container. [2] - examples: [ 'otelcontribcol, --config, config.yaml' ] - - id: labels - type: template[string] - brief: > - Container labels, `` being the label name, the value being the label value. - examples: [ 'container.labels.app=nginx' ] + - ref: container.labels + - ref: oci.manifest.digest