Migrate annotations to Kubernetes-recommended naming conventions #9537

saschagrunert · 2025-10-29T11:26:17Z

What type of PR is this?

/kind feature

What this PR does / why we need it:

This commit implements the annotation migration described in issue #7781,
migrating CRI-O annotations from the legacy format (io.kubernetes.cri-o.)
to the Kubernetes-recommended format (.crio.io).

Migrated Annotations (15 total):

io.kubernetes.cri-o.userns-mode -> userns-mode.crio.io
io.kubernetes.cri-o.cgroup2-mount-hierarchy-rw -> cgroup2-mount-hierarchy-rw.crio.io
io.kubernetes.cri-o.UnifiedCgroup -> unified-cgroup.crio.io
io.kubernetes.cri-o.Spoofed -> spoofed.crio.io
io.kubernetes.cri-o.ShmSize -> shm-size.crio.io
io.kubernetes.cri-o.Devices -> devices.crio.io
io.kubernetes.cri-o.TrySkipVolumeSELinuxLabel -> try-skip-volume-selinux-label.crio.io
io.kubernetes.cri-o.seccompNotifierAction -> seccomp-notifier-action.crio.io
io.kubernetes.cri-o.umask -> umask.crio.io
io.kubernetes.cri-o.PodLinuxOverhead -> pod-linux-overhead.crio.io
io.kubernetes.cri-o.PodLinuxResources -> pod-linux-resources.crio.io
io.kubernetes.cri-o.LinkLogs -> link-logs.crio.io
io.kubernetes.cri-o.PlatformRuntimePath -> platform-runtime-path.crio.io
seccomp-profile.kubernetes.cri-o.io -> seccomp-profile.crio.io
io.kubernetes.cri-o.DisableFIPS -> disable-fips.crio.io

Implementation Changes:

Create pkg/annotations/v2 package with all V2 annotation constants
Add reverseAnnotationMigrationMap for efficient V1↔V2 lookup
Implement GetAnnotationValue() helper function that:
- Checks V2 annotation first (preferred)
- Falls back to V1 annotation if V2 not present
- Supports both base and container-specific annotations
- Handles dot-separated (.containerName) and slash-separated (/containerName) patterns
Implement findV1KeyForContainerSpecific() for container-specific fallback
Mark all V1 annotations as deprecated with clear migration path
Update AllAllowedAnnotations to include both V1 and V2 formats
Update all annotation usage across codebase:
- server/container_create*.go
- server/sandbox_run*.go
- server/sandbox_stop_linux.go
- internal/lib/container_server.go
- internal/factory/container/container.go
- internal/config/seccomp/*.go
- pkg/config/config.go

Testing:

Add comprehensive unit tests (pkg/annotations/annotations_test.go):
- Test V2 annotations work correctly
- Test V1 fallback for backwards compatibility
- Test V2 precedence when both present
- Test container-specific annotations (both separators)
- Test reverse migration map completeness
- Test AllAllowedAnnotations includes both versions
Add integration tests (test/annotation_migration.bats):
- 50+ test cases covering real-world usage
- Test V2 annotations: userns-mode, umask, shm-size, devices, etc.
- Test V1 backwards compatibility for all annotations
- Test precedence behavior with actual CRI-O runtime

Documentation:

Create ANNOTATION_MIGRATION.md with:
- Migration overview and format comparison
- Complete mapping table of all 15 annotations
- Backwards compatibility guarantees
- Migration timeline (Deprecation → Adoption → Removal)
- Usage examples for common scenarios
- Developer guidance for using helper functions
Link migration guide from README.md
Add inline deprecation comments to all V1 constants

The implementation maintains full backwards compatibility: both V1 and V2
annotations are accepted, with V2 taking precedence when both are present.
This allows gradual migration without breaking existing deployments.

Which issue(s) this PR fixes:

Fixes #7781

Special notes for your reviewer:

None

Does this PR introduce a user-facing change?

CRI-O now supports Kubernetes-recommended annotation naming conventions. 
Annotations have been migrated from the legacy `io.kubernetes.cri-o.*` format to the `*.crio.io` format
(e.g., `io.kubernetes.cri-o.userns-mode` → `userns-mode.crio.io`). All 15 affected annotations now support both
formats with full backwards compatibility - the new V2 format takes precedence when both are present.
Legacy V1 annotations are deprecated but will continue to work.
See ANNOTATION_MIGRATION.md for the complete migration guide and mapping table.

openshift-ci · 2025-10-29T11:26:40Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: saschagrunert

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [saschagrunert]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

bitoku · 2025-10-29T12:10:43Z

Creating a new package, something like annotations/v2, may be better, I guess.
We don't have to put V2 suffix on each annotations, and there will be no inconsistency between "*V2" metrics and already canonicalized annotations.

Also this may be out of scope, some variables has "Annotation" suffix, which is not necessary. We can remove that now.

saschagrunert · 2025-10-29T14:01:20Z

@cri-o/cri-o-maintainers PTAL

codecov · 2025-10-29T14:05:14Z

Codecov Report

❌ Patch coverage is 83.15789% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.17%. Comparing base (301eb72) to head (1ddb4a3).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9537      +/-   ##
==========================================
+ Coverage   64.10%   64.17%   +0.06%     
==========================================
  Files         202      204       +2     
  Lines       28196    28227      +31     
==========================================
+ Hits        18075    18114      +39     
+ Misses       8528     8525       -3     
+ Partials     1593     1588       -5

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

saschagrunert · 2025-10-29T14:14:33Z

/retest

saschagrunert · 2025-10-29T15:34:41Z

/retest

pkg/annotations/annotations.go

bitoku

This will have a huge impact, so it should be reviewed by other active maintainers.
@haircommander @sohankunkerkar

This commit implements the annotation migration described in issue cri-o#7781, migrating CRI-O annotations from the legacy format (io.kubernetes.cri-o.*) to the Kubernetes-recommended format (*.crio.io). Migrated Annotations (15 total): - io.kubernetes.cri-o.userns-mode -> userns-mode.crio.io - io.kubernetes.cri-o.cgroup2-mount-hierarchy-rw -> cgroup2-mount-hierarchy-rw.crio.io - io.kubernetes.cri-o.UnifiedCgroup -> unified-cgroup.crio.io - io.kubernetes.cri-o.Spoofed -> spoofed.crio.io - io.kubernetes.cri-o.ShmSize -> shm-size.crio.io - io.kubernetes.cri-o.Devices -> devices.crio.io - io.kubernetes.cri-o.TrySkipVolumeSELinuxLabel -> try-skip-volume-selinux-label.crio.io - io.kubernetes.cri-o.seccompNotifierAction -> seccomp-notifier-action.crio.io - io.kubernetes.cri-o.umask -> umask.crio.io - io.kubernetes.cri-o.PodLinuxOverhead -> pod-linux-overhead.crio.io - io.kubernetes.cri-o.PodLinuxResources -> pod-linux-resources.crio.io - io.kubernetes.cri-o.LinkLogs -> link-logs.crio.io - io.kubernetes.cri-o.PlatformRuntimePath -> platform-runtime-path.crio.io - seccomp-profile.kubernetes.cri-o.io -> seccomp-profile.crio.io - io.kubernetes.cri-o.DisableFIPS -> disable-fips.crio.io Implementation Changes: - Create pkg/annotations/v2 package with all V2 annotation constants - Add reverseAnnotationMigrationMap for efficient V1↔V2 lookup - Implement GetAnnotationValue() helper function that: * Checks V2 annotation first (preferred) * Falls back to V1 annotation if V2 not present * Supports both base and container-specific annotations * Handles dot-separated (.containerName) and slash-separated (/containerName) patterns - Implement findV1KeyForContainerSpecific() for container-specific fallback - Mark all V1 annotations as deprecated with clear migration path - Update AllAllowedAnnotations to include both V1 and V2 formats - Update all annotation usage across codebase: * server/container_create*.go * server/sandbox_run*.go * server/sandbox_stop_linux.go * internal/lib/container_server.go * internal/factory/container/container.go * internal/config/seccomp/*.go * pkg/config/config.go Testing: - Add comprehensive unit tests (pkg/annotations/annotations_test.go): * Test V2 annotations work correctly * Test V1 fallback for backwards compatibility * Test V2 precedence when both present * Test container-specific annotations (both separators) * Test reverse migration map completeness * Test AllAllowedAnnotations includes both versions - Add integration tests (test/annotation_migration.bats): * 50+ test cases covering real-world usage * Test V2 annotations: userns-mode, umask, shm-size, devices, etc. * Test V1 backwards compatibility for all annotations * Test precedence behavior with actual CRI-O runtime Documentation: - Create ANNOTATION_MIGRATION.md with: * Migration overview and format comparison * Complete mapping table of all 15 annotations * Backwards compatibility guarantees * Migration timeline (Deprecation → Adoption → Removal) * Usage examples for common scenarios * Developer guidance for using helper functions - Link migration guide from README.md - Add inline deprecation comments to all V1 constants The implementation maintains full backwards compatibility: both V1 and V2 annotations are accepted, with V2 taking precedence when both are present. This allows gradual migration without breaking existing deployments. Fixes cri-o#7781 Signed-off-by: Sascha Grunert <sgrunert@redhat.com>

saschagrunert · 2025-10-30T15:10:56Z

@cri-o/cri-o-maintainers PTAL

saschagrunert requested a review from mrunalp as a code owner October 29, 2025 11:26

openshift-ci bot added release-note Denotes a PR that will be considered when it comes time to generate release notes. kind/feature Categorizes issue or PR as related to a new feature. dco-signoff: yes Indicates the PR's author has DCO signed all their commits. labels Oct 29, 2025

openshift-ci bot requested review from klihub and littlejawa October 29, 2025 11:26

openshift-ci bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Oct 29, 2025

saschagrunert changed the title ~~Migrate annotations to Kubernetes-recommended naming conventions~~ WIP: Migrate annotations to Kubernetes-recommended naming conventions Oct 29, 2025

openshift-ci bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 29, 2025

saschagrunert force-pushed the fix-7781-annotation-migration branch 4 times, most recently from 416cad0 to 0a77686 Compare October 29, 2025 12:07

saschagrunert force-pushed the fix-7781-annotation-migration branch 9 times, most recently from b997ddf to 6c5dcda Compare October 29, 2025 13:32

saschagrunert changed the title ~~WIP: Migrate annotations to Kubernetes-recommended naming conventions~~ Migrate annotations to Kubernetes-recommended naming conventions Oct 29, 2025

openshift-ci bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 29, 2025

bitoku reviewed Oct 29, 2025

View reviewed changes

pkg/annotations/annotations.go Show resolved Hide resolved

bitoku reviewed Oct 29, 2025

View reviewed changes

saschagrunert force-pushed the fix-7781-annotation-migration branch 4 times, most recently from 1fbd192 to 5d89822 Compare October 30, 2025 08:18

cri-o deleted a comment from openshift-ci bot Oct 30, 2025

saschagrunert force-pushed the fix-7781-annotation-migration branch 2 times, most recently from c52a859 to 3ef6a3f Compare October 30, 2025 09:56

cri-o deleted a comment from openshift-ci bot Oct 30, 2025

saschagrunert force-pushed the fix-7781-annotation-migration branch from 3ef6a3f to 84a4360 Compare October 30, 2025 10:17

saschagrunert force-pushed the fix-7781-annotation-migration branch from 84a4360 to 1ddb4a3 Compare October 30, 2025 12:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Migrate annotations to Kubernetes-recommended naming conventions #9537

Migrate annotations to Kubernetes-recommended naming conventions #9537

Uh oh!

saschagrunert commented Oct 29, 2025 •

edited

Loading

Uh oh!

openshift-ci bot commented Oct 29, 2025

Uh oh!

bitoku commented Oct 29, 2025

Uh oh!

saschagrunert commented Oct 29, 2025

Uh oh!

codecov bot commented Oct 29, 2025 •

edited

Loading

Uh oh!

saschagrunert commented Oct 29, 2025

Uh oh!

saschagrunert commented Oct 29, 2025

Uh oh!

Uh oh!

bitoku left a comment

Uh oh!

saschagrunert commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Migrate annotations to Kubernetes-recommended naming conventions #9537

Are you sure you want to change the base?

Migrate annotations to Kubernetes-recommended naming conventions #9537

Uh oh!

Conversation

saschagrunert commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for your reviewer:

Does this PR introduce a user-facing change?

Uh oh!

openshift-ci bot commented Oct 29, 2025

Uh oh!

bitoku commented Oct 29, 2025

Uh oh!

saschagrunert commented Oct 29, 2025

Uh oh!

codecov bot commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

saschagrunert commented Oct 29, 2025

Uh oh!

saschagrunert commented Oct 29, 2025

Uh oh!

Uh oh!

bitoku left a comment

Choose a reason for hiding this comment

Uh oh!

saschagrunert commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

saschagrunert commented Oct 29, 2025 •

edited

Loading

codecov bot commented Oct 29, 2025 •

edited

Loading