GlossaryAnnotation

Annotation

An annotation is a key-value pair of non-identifying metadata attached to a Kubernetes object, such as a Pod or Deployment, for use by tools and automation.

Table of Contents

Table of Contents

What Does Annotation Mean?

In Kubernetes, an annotation is key-value metadata attached to an object like a Pod or Service. Annotations store descriptive information for tools and people.

They do not change how an object behaves. Instead, they give automation systems a place to attach context, such as build details, owners, or execution IDs.

Annotations vs. Labels

Both are key-value metadata, but they serve different purposes.

Aspect Labels Annotations
Purpose Identify, group, and select objects Store descriptive, non-identifying details
Used by selectors Yes, for Services, Deployments, and queries No, cannot be used to select objects
Typical values Short identifiers like app or environment Longer text, URLs, IDs, or structured data
Example app: checkout build-url or execution-id

Why Annotations Matter

DevOps and QA teams working in large clusters face challenges such as:

  • Organizing test configurations across many namespaces and clusters
  • Tracking metadata for thousands of test runs
  • Connecting results to CI/CD tools and dashboards
  • Keeping debugging context without bloating logs

Annotations solve these by attaching metadata directly to the Kubernetes objects that run tests. Test runs become traceable, debuggable, and easier to manage at scale.

Real-World Example

A QA engineer at a B2B SaaS company runs checkout API tests inside Kubernetes. The Pod running the tests includes annotations like these:

metadata:
  annotations:
    example.com/test-name: "checkout-api"
    example.com/execution-id: "exec-20481"
    example.com/triggered-by: "github-actions"
    example.com/environment: "staging"

With this metadata, the team can:

  • Identify which test ran
  • Trace logs and results to the correct run
  • Connect the run to its CI/CD pipeline using the execution ID

Another developer debugging a flaky test can read the annotations to see exactly which configuration and environment were used.

How Annotations Work with Testkube

Testkube runs tests as Kubernetes workloads, so standard metadata like annotations applies. Workflows let you set annotations on the Jobs and Pods that run tests. Teams use them for:

  • Storing configuration context: test parameters, runtime options, or workflow settings
  • Tracking executions: mapping execution IDs and metadata to specific Pods
  • Enabling integrations: passing context to CI/CD tools or external dashboards
  • Supporting debugging: keeping environment details next to the resources that ran

Test runs stay traceable across cloud-native workflows. See also how to test applications in Kubernetes.

Best Practices for Annotations

  • Use prefixed keys: a domain prefix like example.com/ avoids collisions with other tools.
  • Keep secrets out: annotations are readable by anyone with access to the object.
  • Use labels for selection: anything you need to filter by belongs in a label.
  • Standardize keys: agree on names for owner, build, and execution ID across teams.
  • Keep values small: large blobs belong in ConfigMaps or artifact storage.

Frequently Asked Questions (FAQs)

What is an annotation in Kubernetes?

An annotation is metadata attached to a Kubernetes object. It stores descriptive or configuration details for tools and automation.

How are annotations different from labels?

Labels organize and select Kubernetes objects. Annotations are purely descriptive and cannot be used in selectors.

Can I filter objects based on annotations?

No. Unlike labels, annotations cannot be used for selection. You can still read and manage them with kubectl or the Kubernetes API.

How does Testkube use annotations?

Testkube runs tests as Kubernetes workloads, and workflows can set annotations on test Jobs and Pods. Teams use them for execution IDs, configuration context, and CI/CD links.

What are common use cases for annotations in testing?

Common uses include storing configuration values, tracking execution history, linking runs to CI/CD pipelines, and attaching debugging context.

Related Terms and Concepts

Label

A Kubernetes label is a key-value pair attached to a resource, such as a pod, service, or Job, so tools and controllers can group, filter, and select related resources.
Read more

Test Workflow

A test workflow defines how tests are triggered, executed, and reported, including the environments, tools, setup steps, and result handling around each test.
Read more

Configuration

Configuration is the set of parameters and settings that control how software behaves in a given environment, kept separate from the application code itself.
Read more