Before we talk about annotations, we need to understand the bigger idea they belong to: metadata.

Data about data

Metadata simply means “information about something”. A photo on your phone is the main data. The date it was taken, the place, and the camera used are the metadata. You do not look at metadata to enjoy the photo, but it helps you find, sort and understand the photo later.

Kubernetes objects work the same way. A Deployment has its main content, which is what you want to run. Around it sits metadata: its name, the namespace it lives in, its labels and its annotations. Metadata is the description that wraps the object.

Two very different jobs for metadata

Metadata in Kubernetes does two different jobs. The first job is to identify and group objects, so that the system can select them. The second job is to attach extra information that helps people and tools, but which the system never uses to select anything. Labels do the first job. Annotations do the second.

A quick tour of the building blocks that annotations get attached to.

Kubernetes is a system that runs and manages applications packed into small, portable boxes called containers. You describe what you want, and Kubernetes keeps making it true. If a program crashes, it is restarted. If demand grows, more copies can be started.

Every one of these objects carries the same standard metadata section, and every one of them can carry annotations. That uniformity is one of the reasons annotations became so widely used: whatever you are working with, the same simple mechanism is available.

A plain definition, followed by what makes annotations special.

The core idea

An annotation is a key and value pair of text attached to a Kubernetes object, used to store extra, non-identifying information. The key is a name, such as a note’s title. The value is the text of the note. Both are written as plain strings.

Annotations do not change how the object behaves on their own. Kubernetes does not use them to decide which pods belong to which service. Instead, they are a place to leave information for tools, for automation, and for humans who inspect the object later.

What makes annotations special

The most common beginner question is when to use which. This chapter settles it.

Labels and annotations sit side by side in the metadata section, and at first glance they look almost identical: both are key and value pairs. The difference is in purpose and in rules.

A simple test

Ask yourself: “Do I need Kubernetes to find or group objects using this piece of information?” If the answer is yes, it belongs in a label. If the answer is no, and it is just information for someone or something to read, it belongs in an annotation.

flowchart TD
    Q["I have a piece of extra information"] --> D{"Should Kubernetes use it to select or group objects?"}
    D -- "Yes" --> L["Use a label"]
    D -- "No" --> A["Use an annotation"]
    L --> R1["Short, simple, identifying value"]
    A --> R2["Descriptive value for tools and people"]
        

Every annotation has the same simple parts. Knowing them helps you avoid rejected requests and confusing clashes.

The key

The key has two possible parts separated by a slash. The first part is an optional prefix, and the second part is the name. When a prefix is present, it must look like a normal internet domain name, such as one belonging to a company. The name part is required and is limited to a short length, using letters, digits, dashes, underscores and dots.

The prefix exists to prevent collisions. If two different tools both want to use a key called “config”, they would trample each other. With prefixes, each tool uses its own domain as a namespace for its keys, so a monitoring tool and an ingress tool can both have their own “config” without confusion.

The value

The value is a text string. Kubernetes does not care what is inside it. If a tool wants to store structured information, it will usually write it as text in a format the tool understands and read it back later.

The size limit

There is a limit on the combined size of all annotations on a single object. The limit is roughly a quarter of a megabyte in total. This is generous, but not infinite. Every annotation is stored with the object, sent over the network and held in memory by controllers, so oversized notes make the whole cluster heavier.

Reserved prefixes

Prefixes ending in kubernetes.io and k8s.io are reserved for the core Kubernetes system. Ordinary users should not invent keys under those domains. Use your own company domain instead, so that your keys clearly show who owns them.

Let us follow an annotation from the moment it is written to the moment a tool acts on it.

Step one: the note is written

Someone creates or changes an object, and includes annotations in its metadata. The request goes to the API server, the front desk of the cluster. The API server checks who is asking, checks permissions, validates the format of the keys and the total size, and then stores the object in etcd, the cluster’s database.

Step two: watchers notice

Controllers and tools do not constantly ask “has anything changed?”. Instead, they subscribe to a stream of changes from the API server, known as a watch. When an object with annotations is created or updated, every interested watcher receives the news almost instantly.

Step three: the reader acts

Each watcher looks at the annotations it cares about and ignores the rest. An ingress controller reads its own prefixed annotations to decide how to configure a web server. A monitoring tool reads its own to decide whether to collect metrics. Nothing in Kubernetes itself forces these tools to obey; the agreement is a convention between whoever writes the note and whoever reads it.

sequenceDiagram
    participant User as Engineer or Automation
    participant API as API Server
    participant DB as etcd
    participant Tool as Controller or Tool
    User->>API: Create or update object with annotations
    API->>API: Check identity, permissions and format
    API->>DB: Store object and annotations
    API-->>Tool: Send change notification through watch
    Tool->>Tool: Read only the annotations it understands
    Tool->>API: Act, for example update status or related objects
        

Annotations added by the system itself

Not all annotations are written by people. Kubernetes and its tools add many of their own. For example, when you apply a description with the standard command line tool, it stores a copy of what you last applied in an annotation, so that it can work out the difference next time. Deployments record their revision numbers in annotations too. If you inspect a real object, you will often find several notes you never wrote.

A tour of the annotations that appear again and again in real clusters.

One of the most surprising behaviours for beginners: where you put an annotation changes what happens.

A Deployment has two places where annotations can live. The first is on the Deployment itself, in its own metadata section. The second is inside the pod template, which is the blueprint used to stamp out each pod. These two places look similar, but they behave very differently.

flowchart LR
    A["Edit annotation on Deployment metadata"] --> B["Deployment record changes"]
    B --> C["No new pods created"]
    D["Edit annotation in pod template"] --> E["Pod template changes"]
    E --> F["New replica set created"]
    F --> G["Rolling update replaces pods"]
        

A helpful trick built on this behaviour

The standard rolling restart command relies on exactly this. It adds a timestamp annotation to the pod template. Since the template is now different, Kubernetes replaces the pods one by one, giving you a graceful restart without changing any real setting.

Annotations are born, read, changed and eventually retired. Thinking about each stage keeps clusters tidy.

Many teams manage the first three stages well and forget the last two. Over years, objects gather notes that nobody understands, and people become afraid to delete them.

Real-life use cases, grouped by purpose.

A few simple conventions keep annotations understandable across teams and years.

Always use your own prefix

Choose a domain your organisation owns and use it as the prefix for every custom annotation. This shows at a glance who wrote the note, prevents clashes with tools, and makes it easy to find and clean up your own notes later.

Keep names meaningful

Pick names that say what the value is, such as the owning team or the runbook link, rather than vague names like “info” or “data”. A future reader should understand the purpose without asking the author.

Keep one fact per annotation

Resist the temptation to pack several facts into a single note. A single value holding a team name, phone number and chat channel is harder to read, harder to update and harder for tools to parse than three separate notes.

Write a small shared catalogue

Keep a short internal document listing every custom annotation key your organisation uses, what it means, who reads it and who owns it. Without such a list, annotations slowly turn into a mystery.

Annotations look harmless, but they can carry real risk if treated carelessly.

Never store secrets in annotations

Annotations are stored in plain text and are shown to anyone who can read the object, including in many dashboards, command outputs and logs. Passwords, keys and tokens must never be placed in them. Use proper Secret objects or an external secret manager instead.

Annotations can change tool behaviour

Because tools read annotations as instructions, whoever can edit annotations can influence those tools. Some ingress controllers allow annotations that inject raw configuration snippets into the web server. If a low-trust user can set those, they may be able to reach far beyond their own application. Clusters that host many teams often disable such powerful annotations or block them with policy.

Control who can edit metadata

Role-based access control decides who may update objects. Anyone with permission to update a Deployment or a Service can change its annotations. Grant edit rights carefully, and separate the right to view objects from the right to change them.

Use admission policies as guard rails

Policy engines can check every new or changed object and reject those that break your rules. They can require certain annotations, such as an owner, forbid dangerous ones, and check that values follow the expected format. This turns conventions into enforced rules.

flowchart TD
    W["Someone writes an annotation"] --> R["Access control: is this person allowed to edit?"]
    R --> P["Admission policy: is this key and value allowed?"]
    P --> S["Object stored in the cluster"]
    S --> T["Tool reads the annotation"]
    T --> B["Tool behaviour changes"]
    P -. "Rejected" .-> X["Request refused with an explanation"]
        

Annotations help you observe your cluster, and your cluster needs observing to keep annotations healthy.

Using annotations to support observability

Well-chosen annotations make troubleshooting faster. An object that names its owner, links to its runbook and states its release version saves many minutes during an incident. Some teams also add annotations describing the last automated change and who or what made it.

Auditing changes

The cluster’s audit log records who changed which object and when. Since annotations can alter tool behaviour, changes to sensitive annotations should be watched. An unexpected edit to a security-related annotation on an ingress is worth an alert.

Troubleshooting annotation problems

Patterns are proven habits. Anti-patterns are popular mistakes that keep hurting teams.

Patterns worth adopting

Anti-patterns to avoid

An honest look at what annotations give you, and what they cost.

The lesson is that annotations are best thought of as a lightweight extension point. They let the ecosystem grow quickly, at the price of discipline. Teams that add simple conventions, enforcement and clean-up enjoy the flexibility without the mess.

A checklist of habits that separate tidy clusters from cluttered ones.

Best practices

• Use labels to select, annotations to describe — apply the simple test every time you add metadata.
• Prefix custom keys with your own domain — it prevents clashes and shows who owns each note.
• Keep values short and single-purpose — one fact per annotation is easier for humans and tools.
• Never store secrets — reference Secret objects or an external manager instead.
• Know where you place it — remember that annotations in a pod template can trigger a rollout, while those on the Deployment do not.
• Enforce with policy — require ownership annotations and block dangerous ones with admission rules.
• Document your vocabulary — keep a short catalogue of approved keys and their meanings.
• Clean up regularly — remove notes for tools or teams that no longer exist.

Common mistakes

How the ideas in this guide show up in everyday engineering.

Labels identify and group objects, and Kubernetes can select objects using them. Annotations carry extra descriptive information for tools and humans, and Kubernetes never uses them for selection.

Yes, values can be any text, within a total size limit of roughly a quarter of a megabyte for all annotations on one object. Keys must follow the naming rules, including an optional domain-style prefix.

Only when they are inside a pod template and change. That counts as a new pod definition and triggers a rollout. Annotations on the object’s own metadata do not restart pods, though a tool watching them may react in its own way.

You may, but so do Kubernetes itself, command line tools, delivery systems, controllers and service meshes. It is normal to find annotations on live objects that you never wrote.

The most common reasons are a misspelled key, the wrong object type, or the reading tool not being installed. Annotations work only when something is listening for them.

Kubernetes selectors do not support annotations. You can still list objects and filter the results with scripts or tools, but this is slower and is not how grouping should be done. Use labels for anything you need to select.

No. Annotations are plain text and visible to anyone who can read the object. Use Secret objects or an external secret manager for sensitive values.

Use a domain your organisation owns. Avoid the reserved prefixes belonging to the core Kubernetes project, since those are meant for the system itself.

No. They live in the metadata section, separate from the specification that describes the desired state. The exception is when they sit inside a pod template, where they become part of the pod’s blueprint.

Write a short catalogue of the keys your teams use, add a policy requiring an owner annotation, and remove notes that belong to tools you no longer run.

Annotations are the flexible sticky notes of Kubernetes. They attach extra, non-identifying information to any object, in the form of simple text keys and values. Kubernetes does not use them to select or group objects, but a rich ecosystem of tools reads them to configure ingress, load balancers, monitoring, autoscaling, delivery and more. Their freedom is their strength and their weakness: without conventions, security awareness and clean-up, they become clutter or even a hidden route to change tool behaviour.

Treat every annotation as a promise between a writer and a reader. Name it clearly, keep it small, know who reads it, protect who can write it, and retire it when its purpose ends. Do that, and annotations become one of the most useful quiet features of your cluster.