Update APIKey CRD schema for RBAC design

[eguzki]

Description

Update the APIKey CRD schema to support the RBAC design requirements, including cross-namespace references, consumer-provided secrets, and conditions pattern.

New version

apiVersion: devportal.kuadrant.io/v1alpha1
kind: APIKey
metadata:
  name: mobile-app-payment-key
  namespace: consumer-team-mobile  # Consumer's own namespace
spec:
  # Cross-namespace reference to APIProduct
  apiProductRef:
    name: payment-api-v1
    namespace: payment-services  # Owner's namespace

  # Reference to secret containing API key (namespace-local reference)
  # Consumer creates this secret in their own namespace before creating APIKey
  # Controller reads API key from this secret on approval
  secretRef:
    name: mobile-app-payment-key-secret

  # Rate limiting plan tier
  planTier: "basic"  # e.g., "free", "basic", "premium", "enterprise"

  # Who requested this API key
  requestedBy:
    userId: "alice"
    email: "alice@mobile-team.example.com"

  # Use case justification
  useCase: "Mobile app integration for payment processing in our iOS/Android apps"

status:
  # Approval conditions (following CertificateSigningRequest pattern)
  # Lifecycle states:
  #   - Pending: No conditions (initial state after creation)
  #   - Approved: Approved condition with status "True"
  #   - Denied: Denied condition with status "True"
  #   - Failed: Failed condition with status "True"

  # Example: Approved state
  conditions:
    - type: Approved
      status: "True"
      reason: "ApprovedByOwner"
      message: "Approved for mobile team's payment integration project"
      lastTransitionTime: "2026-03-30T14:00:00Z"

    # OR for Denied state:
    # - type: Denied
    #   status: "True"
    #   reason: "RejectedByOwner"
    #   message: "API product not available for external use"
    #   lastTransitionTime: "2026-03-30T14:00:00Z"

    # OR for Pending state (initial):
    # conditions: []  # Empty array = Pending state

  # Rate limits from selected plan
  limits:
    daily: 10000
    monthly: 300000
    custom:
      - limit: 100
        window: 1m

  # Authentication scheme
  authScheme:
    credentials:
      authorizationHeader:
        prefix: "Bearer"
    authenticationSpec:
      selector:
        matchLabels:
          kuadrant.io/apikey: mobile-app-payment-key

  # API hostname from HTTPRoute
  apiHostname: "api.payment.example.com"

Acceptance Criteria

• Add spec.apiProductRef.namespace field (string, required) for cross-namespace references
• Add spec.secretRef field (LocalObjectReference, required) for namespace-local reference to consumer's secret containing API key
• Replace status.phase with status.conditions array following Kubernetes conditions pattern
• Define condition types: Approved, Denied, Failed with type, status, reason, message, lastTransitionTime
• Remove deprecated status fields: status.secretRef, status.canReadSecret, status.reviewedBy, status.reviewedAt, status.apiKeyValue
• Keep status.limits
• Consider bumping API version to v1alpha2 to signal breaking changes (being in dev preview support mode we will ask users to delete existing CRs and recreate)
• Update CRD manifests
• Update OpenAPI schema
• Document migration notes in README

Related

• Epic: RBAC system for developer portal capabilities kuadrant-console-plugin#353
• Design doc: docs/designs/2026-03-26-api-management-rbac-design.md

Notes

Breaking changes: The current v1alpha1 API is in dev preview support mode, so breaking changes are acceptable.

Consumer-provided secrets: Consumer creates secret with API key in their own namespace and references it via spec.secretRef. Consumer has secret read permissions in their own namespace to access the API key anytime. Controller creates enforcement secret in kuadrant namespace on approval (see separate issue for controller implementation).