Add OLM v1 Support (ClusterExtension and Bundle Annotations)

[sebrandon1]

Add OLM v1 Support (ClusterExtension and Bundle Annotations)

Background

The current linter validates OLM v0 annotations (olm.* and operatorframework.io/*) used on traditional OLM resources:

• ClusterServiceVersion
• Subscription
• OperatorGroup
• CatalogSource

OLM v1 introduces a new architecture with different resources and annotation patterns that are not currently validated.

What is OLM v1?

OLM v1 is the next-generation Operator Lifecycle Manager announced in November 2025 with:

• Simpler API and mental model
• Greater flexibility beyond just Operators
• Security by default (user-provided ServiceAccount with explicit RBAC)
• Support for Helm Charts and GitOps workflows

Key differences from OLM v0:

• Uses ClusterExtension API instead of CSV/Subscription/OperatorGroup
• Requires explicit ServiceAccount and RBAC configuration
• Supports registry+v1 bundle format
• Different annotation patterns and validation rules

OLM v1 Resources to Support

1. ClusterExtension Resources

API Version: olm.operatorframework.io/v1 or olm.operatorframework.io/v1alpha1

Example:

apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: argocd
  annotations:
    # Are there ClusterExtension-specific annotations to validate?
spec:
  namespace: argocd
  serviceAccount:
    name: argocd-installer
  source:
    sourceType: Catalog
    catalog:
      packageName: argocd-operator
      version: 0.6.0

Research needed:

• What annotations are valid on ClusterExtension metadata?
• Are there controller-managed annotations similar to OLM v0's olm.operatorGroup?
• Are there user-settable annotations for configuration?

2. Bundle Metadata Annotations

OLM bundles contain a metadata/annotations.yaml file with operator metadata. Example from operator-controller testdata:

annotations:
  operators.operatorframework.io.bundle.channel.default.v1: ""
  operators.operatorframework.io.bundle.channels.v1: alpha
  operators.operatorframework.io.bundle.manifests.v1: manifests/
  operators.operatorframework.io.bundle.mediatype.v1: registry+v1
  operators.operatorframework.io.bundle.metadata.v1: metadata/
  operators.operatorframework.io.bundle.package.v1: webhook-operator
  operators.operatorframework.io.metrics.builder: operator-sdk-v1.0.0
  operators.operatorframework.io.metrics.mediatype.v1: metrics+v1
  operators.operatorframework.io.metrics.project_layout: go
  operators.operatorframework.io.test.config.v1: tests/scorecard/
  operators.operatorframework.io.test.mediatype.v1: scorecard+v1

Known bundle annotations (from Operator SDK docs):

• operators.operatorframework.io.bundle.mediatype.v1 - Bundle format (e.g., registry+v1)
• operators.operatorframework.io.bundle.manifests.v1 - Manifests directory path
• operators.operatorframework.io.bundle.metadata.v1 - Metadata directory path
• operators.operatorframework.io.bundle.package.v1 - Package name
• operators.operatorframework.io.bundle.channels.v1 - Comma-separated channel list
• operators.operatorframework.io.bundle.channel.default.v1 - Default channel name
• operators.operatorframework.io.metrics.mediatype.v1 - Metrics format
• operators.operatorframework.io.metrics.builder - Builder tool and version
• operators.operatorframework.io.metrics.project_layout - Project layout type
• operators.operatorframework.io.test.config.v1 - Test config directory
• operators.operatorframework.io.test.mediatype.v1 - Test format

These annotations appear in:

1. bundle/metadata/annotations.yaml files
2. As LABEL directives in bundle.Dockerfile

Proposed Implementation

Phase 1: Research (this issue)

• Document all valid ClusterExtension metadata annotations
• Document all valid bundle metadata annotations
• Identify controller-managed vs user-settable annotations
• Determine validation rules for each annotation type
• Check for deprecations or migration paths from OLM v0 to v1

Phase 2: Implementation

• Add ClusterExtension to recognized resource kinds
• Add bundle annotation rules to pkg/rules/rules.go
• Support validating metadata/annotations.yaml files in bundle directories
• Add validation for bundle-specific format requirements (e.g., valid mediatype values)
• Maintain backward compatibility with OLM v0 validation

Phase 3: Testing

• Add test fixtures for ClusterExtension resources
• Add test fixtures for bundle metadata/annotations.yaml files
• Test validation of valid and invalid bundle annotations
• Test mixed OLM v0 and v1 resources

Open Questions

1. ClusterExtension annotations: What annotations are actually used on ClusterExtension metadata? The examples show minimal metadata.

2. Bundle format detection: How should the linter detect bundle metadata files? Options:

   • Auto-detect metadata/annotations.yaml paths
   • Add a --bundle mode flag
   • Treat any YAML file matching the bundle annotation schema

3. Validation strictness: Should bundle annotations be required, or just validated when present?

4. OLM v0 vs v1 coexistence: How should the linter handle repos with both OLM v0 and v1 resources?

5. Catalog annotations: Are there catalog-level annotations beyond bundle and ClusterExtension?

References

• OLM v1 Announcement (Nov 2025)
• Manage operators as ClusterExtensions with OLM v1 (Jun 2025)
• operator-controller GitHub
• Operator SDK - Bundle Generation
• Operator Bundle Design
• ClusterExtension API Reference

Labels

enhancement, research needed, olm-v1