Architecture Of Konflux

71. Replace Appstudio Labels, Annotations, and Finalizers with Konflux equivalents

Date: 2026-06-11

# Status

Accepted

Builds upon ADR 68. Standardize on konflux-ci.dev as Official API Group.

# Context

Following the decision in ADR 68 to standardize on konflux-ci.dev as the official API group for all Konflux CRDs, a similar branding misalignment exists in Kubernetes labels, annotations, and finalizers currently used throughout the platform.

Konflux currently uses various prefixes for labels, annotations, and finalizers that reflect the project’s original identity as “App Studio” and its Red Hat-branded origins:

# Issues with Current Naming

The current label, annotation, and finalizer naming presents the same fundamental issues as the API group naming:

# Scope

This ADR covers all Kubernetes metadata fields that are user-visible or persisted in etcd:

  1. Labels — Used for resource selection, filtering, and organization
  2. Annotations — Used for non-identifying metadata, configuration hints, and cross-service communication
  3. Finalizers — Used to control resource deletion and cleanup logic

This ADR does NOT cover:

# Current Usage Inventory

A comprehensive audit of the codebase reveals the following high-level categories of labels, annotations, and finalizers that need migration:

Common Label Patterns:

Common Annotation Patterns:

Common Finalizer Patterns:

The exact inventory of labels, annotations, and finalizers will be maintained in a tracking document separate from this ADR, as the list is large and changes frequently during active development.

# Decision

# Migration Plan

For the cross team or cross component functionality, the migration will be executed in four phases to minimize user disruption and ensure backward compatibility.

If the items to migrate are scoped to internal resources of only one service (e.g. a finalizer rename) OR the migration could be fully automated on cross services internal resources, then the migration plan could be simplified.

# Phase 1: Dual Write (Controllers Updated)

Actions:

  1. Update all controllers, operators, and webhooks to write BOTH old and new metadata when creating or updating resources.
  2. Update all controllers to read from new metadata first, falling back to old metadata if new is absent.
  3. Update tests.
  4. Update internal documentation and developer guides.

Validation:

User Impact:

# Phase 2: Backfill Existing Resources

Actions:

  1. Develop and test a migration script/controller that backfills new metadata onto existing resources.
  2. Run the migration script in non-production environments first (dev, staging).
  3. Announce the migration plan to users with a clear timeline and instructions.
  4. Execute the migration script in production environments (gitops and clusters) or via a dedicated controller.
  5. Validate that all resources in all namespaces have both old and new metadata.

Validation:

User Impact:

# Phase 3: Deprecation Period (Documentation and Warnings)

Actions:

  1. Update all official documentation, examples, tutorials, and guides to use only konflux-ci.dev metadata.
  2. Add deprecation notices to the old metadata in documentation.
  3. Provide migration tooling to update GitOps repositories.
  4. Communicate the deprecation timeline through announcements, community calls, and documentation.

Validation:

User Impact:

# Phase 4: Removal of Old Metadata Support

Actions:

  1. Update all controllers to stop writing old metadata.
  2. Update all controllers to stop reading from old metadata (remove fallback logic).
  3. Run a cleanup to remove old metadata from existing resources.
  4. Remove old metadata from all documentation and examples.
  5. Announce the completion of the migration.

Validation:

User Impact:

# Migration Plan and the New Component Model

The resources in New Component model can support only new konflux-ci.dev naming from start. In such case the migration should be done during migration from the old to the new model.

# Consequences

# Positive

# Negative

# Alternatives Considered

# Retain appstudio Naming Indefinitely

This alternative would leave the current label, annotation, and finalizer naming unchanged, avoiding all migration costs.

This approach is rejected because:

# Introduce konflux-ci.dev Only for New Services

This alternative would introduce konflux-ci.dev metadata only for new services or features, leaving existing services on appstudio permanently.

This approach is rejected because:

# Use a Shorter Prefix (e.g., konflux.dev or konflux)

Alternative domain options include konflux.dev or even omitting the domain entirely (e.g., konflux).

These are rejected because:

# Immediate Hard Cutover (No Dual-Support Period)

This alternative would skip the dual-support phases and immediately replace all old metadata with new metadata in a single release.

This approach is rejected because:

# References