---
layout: blog
title: "OCI Image Annotations and Kubernetes"
slug: OCI-Image-Annotations-and-Kubernetes
---

**Author:** Erikas Bykovskis

# OCI Image Annotations

We are able to add more metadata to container images using OCI (Open Container Initiative) image annotations. Images in the OCI image format are delivered and saved along with a manifest file that contains vital details about the image and any associated layers. By giving a mechanism to incorporate unique key-value pairs, image annotations expand this metadata.

Version numbers, build information, licensing details, maintainer information, release notes, and other pertinent information about the image can all be stored in annotations. Annotations allow us to add context and information that improves image management and comprehension.

Tools and platforms that support OCI images can access and interpret OCI image annotations because they are saved as part of the image manifest. As a result, we are able to communicate information during all phases of the container image lifecycle.

## Example

Imagine you have a container image for a web application. To provide more information about the image, you can include OCI image annotations in the image manifest. Here's an example:

{
  "annotations": {
    "version": "1.0.0",
    "maintainer": "John Doe <[e-mail]>",
    "license": "MIT",
    "release-notes": "We added an exciting new feature X",
    "build-date": "June 19, 2023",
    "custom-key": "custom-value"
  }
}

In this example, we've added various annotations to the image manifest:

- version: It shows the version of the image.
- maintainer: This annotation provides the contact information for the person responsible for maintaining the image.
- license: It indicates the software license associated with the image.
- release-notes: This annotation offers details about the latest changes or additions made to the image.
- build-date: It specifies the date when the image was built.
- custom-key: This annotation allows for the inclusion of any additional custom information you want.

These annotations provide important metadata that helps with managing and understanding the image.

# OCI Image Annotations in Kubernetes

OCI image annotations significantly improve container image management and security inside the Kubernetes ecosystem. Annotations are used by Kubernetes to hold the metadata related to the container images used in pods.

With Kubernetes annotations, we may share important details like an image's origin, the outcomes of vulnerability scans, its compliance status, or any other particular custom data that is pertinent to our deployment.

## Example

When working with Kubernetes, you can make use of OCI image annotations in the pod specification to provide valuable insights about the container images used. Here's an example:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - name: my-container
    image: my-image:latest
    imagePullPolicy: IfNotPresent
    annotations:
      vulnerability-scan: "Passed"
      compliance-status: "Approved"

In this Kubernetes example, we've included two annotations specific to our needs:

- vulnerability-scan: This annotation shows the result of a vulnerability scan performed on the image, indicating that it has passed the scan.
- compliance-status: It specifies the compliance status of the image, indicating that it has been approved.

By including these annotations, we can ensure that our Kubernetes cluster enforces policies and only deploys secure and compliant images.

# Limitations of OCI Image Annotations

It's essential to be aware of their limitations to ensure you make the most informed decisions when utilizing them. Let's dive into some key limitations:

- The lack of a standardized schema means annotations can vary across tools and platforms, compromising interoperability.
- Validation relies on external tools, and there is no built-in enforcement mechanism, potentially leading to errors.
- Caution is needed when storing sensitive data as annotations may risk unauthorized access.
- Excessive annotations impact storage and network performance.
- Not all container runtime environments fully support OCI annotations, so compatibility should be verified.

Understanding these limitations enables informed decisions for effective and secure usage.

## Example

Let's imagine you have two container registry platforms with different formats for OCI image annotations. Transferring images between these platforms could result in inconsistencies due to the lack of standardization.

Without a built-in enforcement mechanism, relying on external validation tools becomes crucial. However, if these tools are not properly implemented, errors or inconsistencies in annotations may go unnoticed.

Including sensitive information as annotations can pose security risks. Unauthorized access to such data could lead to system breaches or data exposure.

These examples highlight the need to address standardization, validation, and data security when working with OCI image annotations.

# Conclusion

Despite some drawbacks, OCI image annotations continue to be an effective technique for enhancing metadata and adding more context to container images. These annotations are essential for improving image management, security, and compliance in the Kubernetes environment. By providing context, enforcing rules, and ensuring the deployment of safe and legal container images within our Kubernetes cluster, OCI image annotations offer valuable benefits. To maximize these advantages while minimizing any potential negatives, it is essential to be aware of these restrictions and use annotations wisely.