Metadata · XB Field Notes

Extended attributes belong to the inode and to a namespace

Tue, 14 Dec 2027 00:00:00 +0000

Extended attributes attach named byte values to filesystem objects outside the ordinary file-content stream. Applications can use the user namespace for small metadata, while other namespaces have kernel, security-module, or privileged semantics. Their usefulness depends on the filesystem, access rules, and transfer tools. A metadata tag is reliable only when the workflow preserves and interprets it according to an explicit contract.

When it breaks

An attribute value is not necessarily text. It can contain NUL bytes or arbitrary binary data, so treating it as a terminated string or assuming a particular encoding can corrupt the value. An empty attribute and a missing attribute are also different states. Returning an empty string for both can hide whether the metadata was deliberately set or lost during transfer.

Same-filesystem rename retains the object and its attributes, but copying content usually creates another inode. The copy tool decides which metadata it attempts to preserve. Equal file hashes therefore do not prove equal extended attributes. A pipeline can successfully deliver every content byte while omitting a classification, origin, or application version tag that downstream processing expects.

Namespace names do not create application authorization rules. Setting user.classification=private does not make a readable file confidential. User attributes follow applicable file-access permissions; security attributes have their own documented semantics and policy. Confusing an application label with enforced access control can expose content while the label appears reassuringly intact.

Check it quickly

Save this as xattrs.py and run python3 xattrs.py as root in a disposable Linux container whose temporary directory supports user extended attributes. The recorded run used Linux 6.12.76, Python 3.11.2, and an ext4 volume. Root prepares the fixture and starts one child under an unprivileged numeric identity; no account is created:

from pathlib import Path
from tempfile import TemporaryDirectory
import errno,os,shutil,subprocess,sys

def fails(code,operation):
 try:operation()
 except OSError as error:assert error.errno==code,error
 else:raise AssertionError('expected attribute error')
with TemporaryDirectory(prefix='xbcatm-xattr-') as directory:
 root=Path(directory);root.chmod(0o755);path=root/'data';path.write_bytes(b'public fixture');path.chmod(0o644)
 os.setxattr(path,'user.review',b'binary\0value\xff',os.XATTR_CREATE)
 assert os.getxattr(path,'user.review')==b'binary\0value\xff'
 fails(errno.EEXIST,lambda:os.setxattr(path,'user.review',b'other',os.XATTR_CREATE))
 fails(errno.ENODATA,lambda:os.setxattr(path,'user.missing',b'value',os.XATTR_REPLACE))
 os.setxattr(path,'user.empty',b'');assert os.getxattr(path,'user.empty')==b''
 os.removexattr(path,'user.empty');fails(errno.ENODATA,lambda:os.getxattr(path,'user.empty'))
 print('attribute values are bytes; empty differs from missing; CREATE and REPLACE enforce their preconditions')
 alias=root/'alias';os.link(path,alias)
 os.setxattr(alias,'user.review',b'shared',os.XATTR_REPLACE)
 assert os.getxattr(path,'user.review')==b'shared'
 moved=root/'moved';path.rename(moved);assert os.getxattr(moved,'user.review')==b'shared'
 plain=root/'plain';preserved=root/'preserved';shutil.copyfile(moved,plain);shutil.copy2(moved,preserved)
 fails(errno.ENODATA,lambda:os.getxattr(plain,'user.review'))
 assert os.getxattr(preserved,'user.review')==b'shared'
 assert plain.read_bytes()==preserved.read_bytes()==moved.read_bytes()
 print('hard links and same-filesystem rename retain inode attributes; copyfile omits them, copy2 preserves this supported user attribute')
 os.setxattr(moved,'user.classification',b'private')
 probe=r'''
from pathlib import Path
import errno,os,sys
path=Path(sys.argv[1]);assert path.read_bytes()==b'public fixture'
assert os.getxattr(path,'user.classification')==b'private'
try:os.setxattr(path,'user.classification',b'changed')
except OSError as error:assert error.errno==errno.EACCES
else:raise AssertionError('another identity changed a read-only user attribute')
'''
 result=subprocess.run([sys.executable,'-c',probe,str(moved)],user=61001,group=61001,extra_groups=[],capture_output=True,text=True,timeout=5)
 assert result.returncode==0,result.stderr
 fails(errno.E2BIG,lambda:os.setxattr(moved,'user.too_large',b'x'*65537))
 print('a user.classification label does not enforce confidentiality; file permissions block the other identity from changing it; oversized value returns E2BIG')

The fixture stores a value containing both NUL and a non-UTF-8 byte and retrieves the exact bytes. Creating the same key again with XATTR_CREATE fails with EEXIST, while replacing a missing key with XATTR_REPLACE fails with ENODATA. These flags express preconditions instead of silently turning every write into an unconditional update.

An explicitly empty value reads back as empty bytes. After removal, reading that key returns ENODATA. This provides a direct distinction between absence and an intentionally empty attribute. A caller using metadata to drive behavior needs to decide how each state affects the operation rather than collapsing both into one convenient default.

A hard link shares the same inode, so updating the attribute through that name changes the value seen through the original name. Renaming the original within the filesystem preserves the attribute. The experiment then copies the file twice: copyfile preserves the content but omits the user attribute, while copy2 preserves this supported attribute in the tested environment.

All three content streams compare equal despite the metadata difference. Python documents metadata copying as dependent on platform support and permissions, so this successful copy2 result is not a universal guarantee for every attribute namespace or destination. Verification should inspect the attributes actually needed after the specific transfer, not merely the copy command’s exit status.

The file remains mode 0644 when tagged private. Another ordinary identity reads both its content and the tag, proving that the label did not enforce confidentiality. That identity cannot change the attribute because it lacks the relevant write permission. Finally, a value larger than 65536 bytes is rejected with E2BIG, demonstrating a real size boundary.

Preserve meaning across the workflow

Choose application-specific key names to avoid collisions within the shared user namespace, and define the value encoding and version. Keep values small enough for the target filesystems; their practical limits can be tighter than the Linux interface maximum and can depend on other metadata already attached to the inode.

Test backup, archive, restore, and cross-filesystem copy paths using both content and attribute assertions. Some destinations do not support the required namespaces, and some tools preserve them only with explicit options. Decide whether loss should fail the workflow or be represented through a documented alternative, based on the actual metadata contract.

Updating file bytes and updating a separate attribute are not automatically one application transaction. A checksum tag can become stale after a later write, and a writer able to change both data and metadata is not an independent integrity authority. Validate the relationship when consuming it, and use a stronger storage or signing contract when that relationship must survive concurrent changes or untrusted writers.

Sources

xattr(7), attribute namespaces, permission rules, and storage limits, checked 2026-09-12.
setxattr(2), CREATE/REPLACE behavior and attribute error conditions, checked 2026-09-12.
getxattr(2), binary values and missing-attribute errors, checked 2026-09-12.
Python 3.11 shutil documentation, copyfile and best-effort metadata preservation by copy2, checked 2026-09-12.

Annotations carry metadata that consumers can interpret

Wed, 10 Mar 2027 00:00:00 +0000

Annotations attach non-identifying metadata to Kubernetes objects. They can record provenance, ownership notes, or information consumed by a tool. Standard label selectors do not select objects by annotation values, but that does not make annotations inert. A controller, admission component, or deployment tool can interpret a documented annotation and change behavior accordingly. Know the consumer before deciding that a metadata edit is harmless.

A different field is not an unvalidated field

Annotation keys and values must be strings. Keys follow a qualified-name format, with an optional DNS-style prefix and a name segment; the combined annotation key and value size on an object is limited to 256 KiB. This is not unrestricted storage for arbitrary typed JSON. A tool may store serialized JSON inside a string, but that tool then owns its additional schema and interpretation.

Use a prefix controlled by the responsible organization for automated annotations. A generic owner note and a controller-specific setting have different meanings even though both live in the same map. Document which component writes and reads each operational key. Avoid treating a familiar-looking annotation from another controller as portable configuration without checking its contract.

Labels and annotations also have different selection roles. A standard selector can match label expressions, while descriptive annotation content is retrieved and interpreted separately. This distinction does not imply that every arbitrary label has a dedicated storage index or that annotations cannot affect reconciliation. Choose the field from the consumer’s API rather than from a rule that machines only read labels.

When it breaks

Location within the object changes the effect. Editing a Deployment’s top-level metadata is different from editing metadata inside spec.template. A Pod-template change can trigger a rollout even when container images and selector labels remain unchanged. Conversely, an annotation written only on the Deployment does not automatically become a Pod-template change.

Generation is not a rollout counter. Kubernetes 1.34.11’s Deployment strategy increments generation for annotation changes because Deployment annotations can be copied to ReplicaSets. A changed generation can therefore describe reconciliation without a new Pod template or replacement Pod. Inspect the template, ReplicaSet identity, and actual Pod UIDs before reporting a rollout.

A pipeline that writes the current time into the Pod template on every render can trigger replacement despite unchanged code and configuration. Derive a version signal from the inputs it represents. Put audit-only timestamps at an appropriate level and check that level’s consumers, so a provenance field does not accidentally become a continuous rollout trigger.

Annotations are also not a secrecy boundary. Readers with access to an object’s metadata can inspect them, and tools may copy them to other objects or logs. Keep sensitive values out of descriptive metadata. Large serialized records can hit the aggregate size limit, while a numeric value that was not encoded as a string can be rejected before a controller ever sees it.

Check it quickly

Use a disposable Kubernetes cluster with kubectl access and python:3.11-slim-bookworm available on its nodes. Save this as annotations.py and run python3 annotations.py KUBECONFIG_PATH CONTEXT, replacing the last two arguments with the dedicated test configuration and context. The fixture needs permission to create and delete its temporary namespace. The recorded server was Kubernetes 1.34.11.

import json
import subprocess
import sys
import time
from uuid import uuid4

assert len(sys.argv) == 3, 'usage: python3 example.py DISPOSABLE_KUBECONFIG CONTEXT'
base = ['kubectl', '--kubeconfig', sys.argv[1], '--context', sys.argv[2], '--request-timeout=30s']
image = 'python:3.11-slim-bookworm'


def k(*args, payload=None, expected=0):
 result = subprocess.run(base + list(args), input=json.dumps(payload) if payload is not None else None,
 capture_output=True, text=True, timeout=150)
 if expected is not None:
 assert result.returncode == expected, result.stderr
 return result


def obj(namespace, kind, name=None, selector=None):
 args = ['get', kind, '-n', namespace, '-o', 'json']
 if name:
 args.append(name)
 if selector:
 args += ['-l', selector]
 return json.loads(k(*args).stdout)


def apply(namespace, data):
 return k('apply', '-n', namespace, '-f', '-', payload=data)


def wait_for(read, ready, seconds=120):
 until = time.monotonic() + seconds
 while time.monotonic() < until:
 value = read()
 if ready(value):
 return value
 time.sleep(0.5)
 raise AssertionError('expected Kubernetes condition did not arrive')


def pod_ready(pod):
 return any(c['type'] == 'Ready' and c['status'] == 'True'
 for c in pod.get('status', {}).get('conditions', []))


def spec(script='import time; time.sleep(600)'):
 return {'automountServiceAccountToken': False, 'terminationGracePeriodSeconds': 1,
 'containers': [{'name': 'app', 'image': image, 'imagePullPolicy': 'IfNotPresent',
 'command': ['python3', '-c', script],
 'resources': {'requests': {'cpu': '10m', 'memory': '24Mi'},
 'limits': {'cpu': '200m', 'memory': '96Mi'}}}]}


def deployment(namespace, name, podspec):
 return apply(namespace, {'apiVersion': 'apps/v1', 'kind': 'Deployment', 'metadata': {'name': name},
 'spec': {'replicas': 1, 'selector': {'matchLabels': {'app': name}},
 'template': {'metadata': {'labels': {'app': name}}, 'spec': podspec}}})


def deployment_pod(namespace, name):
 wait_for(lambda: obj(namespace, 'deployment', name), lambda d:
 d.get('status', {}).get('observedGeneration', 0) >= d['metadata']['generation']
 and d.get('status', {}).get('updatedReplicas') == 1
 and d.get('status', {}).get('availableReplicas') == 1
 and d.get('status', {}).get('replicas') == 1)
 def pods():
 return [p for p in obj(namespace, 'pods', selector='app=' + name)['items']
 if not p['metadata'].get('deletionTimestamp')]
 return wait_for(pods, lambda p: len(p) == 1 and pod_ready(p[0]))[0]

namespace = 'notes-annotations-' + uuid4().hex[:8]
k('create', 'namespace', namespace)
try:
 deployment(namespace, 'web', spec())
 first = deployment_pod(namespace, 'web')
 initial = obj(namespace, 'deployment', 'web')
 replicasets_before = {r['metadata']['uid'] for r in obj(namespace, 'replicasets')['items']}
 k('annotate', 'deployment', 'web', '-n', namespace, 'notes.example/release=two')
 annotated = obj(namespace, 'deployment', 'web')
 assert annotated['metadata']['generation'] > initial['metadata']['generation']
 assert annotated['metadata']['annotations']['notes.example/release'] == 'two'
 assert deployment_pod(namespace, 'web')['metadata']['uid'] == first['metadata']['uid']
 assert {r['metadata']['uid'] for r in obj(namespace, 'replicasets')['items']} == replicasets_before
 wait_for(lambda: obj(namespace, 'replicasets')['items'],
 lambda records: len(records) == 1 and records[0]['metadata'].get('annotations', {}).get('notes.example/release') == 'two')
 invalid = k('patch', 'deployment', 'web', '-n', namespace, '--type=merge',
 '-p', json.dumps({'metadata': {'annotations': {'notes.example/count': 3}}}), expected=None)
 assert invalid.returncode != 0
 assert 'notes.example/count' not in obj(namespace, 'deployment', 'web')['metadata']['annotations']
 k('patch', 'deployment', 'web', '-n', namespace, '--type=merge', '-p', json.dumps({
 'spec': {'template': {'metadata': {'annotations': {'notes.example/config': 'two'}}}}}))
 second = deployment_pod(namespace, 'web')
 final = obj(namespace, 'deployment', 'web')
 assert second['metadata']['uid'] != first['metadata']['uid']
 assert final['metadata']['generation'] > annotated['metadata']['generation']
 assert final['spec']['selector'] == initial['spec']['selector']
 assert len(obj(namespace, 'replicasets')['items']) == 2
 assert second['metadata']['annotations']['notes.example/config'] == 'two'
 selected = obj(namespace, 'pods', selector='app=web')['items']
 assert any(p['metadata']['uid'] == second['metadata']['uid'] for p in selected)
 print(json.dumps({'top_level_annotation_preserved_pod': True,
 'generation_sequence': [d['metadata']['generation'] for d in (initial, annotated, final)],
 'top_level_annotation_copied_to_replicaset': True,
 'non_string_annotation_rejected': True,
 'template_annotation_created_new_pod': True,
 'replicasets_after_template_change': 2, 'selector_unchanged': True}))
finally:
 k('delete', 'namespace', namespace, '--wait=true', '--timeout=90s')

The first stage creates a Deployment and records its Pod UID, generation, and ReplicaSet UID. Adding notes.example/release at the Deployment’s top level increases generation from one to two. The annotation appears on the existing ReplicaSet, while the original Pod and ReplicaSet identities stay the same. This observes real reconciliation rather than assuming an unchanged generation.

The next check attempts to patch an annotation with a numeric value. The API rejects it and leaves that key absent. Finally, adding notes.example/config to the Pod template increases generation to three, creates a second ReplicaSet, and replaces the Pod. Selector labels remain unchanged, and the new Pod carries the template annotation.

All assertions passed and the namespace was removed. The experiment verifies these Deployment behaviors and one type-validation failure; it does not exercise arbitrary third-party annotations, admission policies, or scheduler plugins. Treat metadata edits according to the specific object path and documented consumer, and report observed lifecycle changes instead of inferring them from the word annotation alone.

Sources

Kubernetes: Annotations, non-identifying metadata, string values and size limits, checked 2026-09-13.
Kubernetes: Deployments, Pod-template changes trigger a rollout, checked 2026-09-13.
Kubernetes 1.34.11: Deployment strategy source, annotation changes increment generation because they propagate to ReplicaSets, checked 2026-09-13.