[Proposal] Move project-id from bare label to domain-prefixed K8s annotation

[renuka-fernando]

Summary

• Replace the bare Kubernetes label project-id on API custom resources (RestApi, WebSubAPI) with a domain-prefixed annotation gateway.api-platform.wso2.com/project-id
• Deprecate project-id label: fall back to the old label if the annotation is absent, and log a warning

Motivation

• Kubernetes convention violation: project-id is non-identifying metadata used solely for analytics. Per Kubernetes conventions, non-selector metadata belongs in annotations, not labels. Labels are for identifying and selecting objects.
• Bare key collision risk: The generic key project-id can collide with labels set by other tools, operators, or CI/CD systems. Domain-prefixed keys (gateway.api-platform.wso2.com/...) are the Kubernetes best practice for vendor-specific metadata.
• Consistency with existing HTTPRoute annotations: The gateway operator will read gateway.api-platform.wso2.com/ prefixed annotations from HTTPRoute resources. Alongside existing fields (api-version, context, display-name), the operator will need to support project-id (and future fields like artifact-id) via the same annotation convention when converting HTTPRoute to RestApi CRs.
• HTTPRoute compatibility: The gateway operator converts standard Kubernetes Gateway API HTTPRoute resources into internal RestApi CRs. Users need to attach project-id to HTTPRoute resources too. On HTTPRoute (a shared, multi-controller resource), a bare non-selector label is misleading and collision-prone -- labels on HTTPRoute are used for Gateway route attachment and selection.

Proposal

• Move project-id from .metadata.labels to .metadata.annotations with the fully qualified key gateway.api-platform.wso2.com/project-id
• When the old label is detected (and the new annotation is absent), log a deprecation warning advising users to migrate

Examples

Before:

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: petstore-api-v1.0
  labels:
    project-id: 019d953f-d386-7a64-aa92-1869a28292e0
spec:
  displayName: PetStore API
  version: v1.0

After:

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: petstore-api-v1.0
  annotations:
    gateway.api-platform.wso2.com/project-id: 019d953f-d386-7a64-aa92-1869a28292e0
    gateway.api-platform.wso2.com/artifact-id: 12ab34cd-0000-0000-0000-000000000000  # New
spec:
  displayName: PetStore API
  version: v1.0

HTTPRoute usage (new):

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: petstore-route
  annotations:
    gateway.api-platform.wso2.com/api-version: "v1.0" # New
    gateway.api-platform.wso2.com/context: "/petstore" # New
    gateway.api-platform.wso2.com/display-name: "PetStore API" # New
    gateway.api-platform.wso2.com/project-id: 019d953f-d386-7a64-aa92-1869a28292e0
    gateway.api-platform.wso2.com/artifact-id: 12ab34cd-0000-0000-0000-000000000000  # New
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            value: /petstore
      backendRefs:
        - name: petstore-svc
          port: 8080

Drawbacks

• Migration effort for existing users: Anyone currently setting project-id as a label (via platform-api, CI/CD, or manually) must update their resource manifests.
• Verbosity: gateway.api-platform.wso2.com/project-id is longer than project-id. This is an accepted tradeoff for correctness and collision avoidance.

Compatibility

• Backwards compatible?: Yes - deprecated fallback reads the old label.
• Requires migration?: Yes - users must update manifests before the fallback is removed

References

• Kubernetes Labels and Selectors
• Kubernetes Annotations
• Gateway API HTTPRoute specification
• Kubernetes recommended label conventions