[thivindu]

Purpose

The gateway management API now supports caller-set subscription IDs and in-place plan and token updates (#3804), and the ap CLI supports them too (#3820). This PR brings the same support to the gateway operator's Subscription CR on the 1.2.x operator Helm chart branch.

It backports #3918. The subscription changes are identical; only the generated zz_generated.deepcopy.go files differ, because main has API types this branch doesn't.

Until now, a deployed Subscription CR could only change spec.status:

• Changing spec.subscriptionPlanId or spec.subscriptionToken was rejected as immutable.
• Rotating the token's valueFrom Secret failed with "the gateway management API cannot update an existing subscription token".

In every case the only option was to delete and recreate the CR. That left the subscription missing in between, and gave it a new gateway ID.

Related To:

• [Improvement]: Gateway subscription REST API can't set a reference ID or update a subscription's plan or token #3782

Related PRs:

• Allow caller-set subscription IDs, in-place plan/token updates, and fix subscription plan conflict errors #3804
• Add subscription plan and token update options to the gateway CLI, and port CLI integration tests to the test framework #3820
• [Gateway operator] externalRefId and in-place plan/token updates for Subscription CRs #3918

Changes

Subscription CR (v1 and v1alpha1)

• New optional spec.externalRefId: used as the gateway subscription ID instead of a generated UUID.
  • Validated in the CRD: 1–64 characters, matching ^[A-Za-z0-9][A-Za-z0-9._-]*$.
  • Must be unique on the gateway, across all APIs.
  • Immutable once deployed.
• Updated in place: subscriptionPlanId, subscriptionToken and status.
• Still immutable: externalRefId, apiId, applicationId, billingCustomerId and billingSubscriptionId.
• Regenerated files: deepcopy code, config/crd/bases, and the Helm chart's CRD copy.

Controller

• Every reconcile of a deployed CR sends one PUT with the status, the plan and the token. This keeps the CR the source of truth:
  • Removing subscriptionPlanId sends "subscriptionPlanId": null, which clears the plan on the gateway.
  • Sending the token on every update applies a rotated valueFrom Secret. The existing Secret drift detection triggers the redeploy.
• The status is applied even when the plan or token can't be:
  • If the token Secret is missing, or the gateway rejects the plan or token with 400 or 409, the operator sends the status on its own, and the CR still reports the original error.
  • So a deleted SubscriptionPlan CR or a missing Secret can't block revoking or deactivating a subscription.
  • Failures that clear on their own, such as a SubscriptionPlan that isn't deployed yet, are retried as before, and everything is then sent in one PUT. A 404 is not followed by a status-only update.
• Immutability check: it now uses a fingerprint of only the immutable fields.
  • A CR may have no fingerprint yet: it was created by an earlier operator version, or its annotation write was lost. For such a CR, the operator first checks that the gateway subscription in status.id is still listed under spec.apiId, belongs to spec.applicationId, and, on gateways that report it, matches spec.externalRefId.
  • Only then is the spec recorded as the baseline, and the old create-fields annotation (subscription-last-applied-create-fingerprint) removed. That annotation also covered the plan and token.
  • If the check fails, the CR gets the immutable-field error and nothing is sent. An edit the earlier operator rejected, such as a changed apiId, therefore stays rejected after the upgrade.
• Create conflict recovery: when a create gets 409, the existing subscription is adopted only if:
  • with externalRefId, it has that ID, is listed under the CR's own API, and belongs to the CR's application;
  • without externalRefId, it's the only subscription on the API for the CR's application. Application IDs are compared after trimming; unset, empty and blank all mean no application;
  • and, either way, no other Subscription CR on a shared gateway already holds that ID in status.id. Otherwise both CRs would manage, and on deletion remove, the same subscription.
• When nothing can be adopted:
  • With externalRefId, the CR gets a generic, non-retryable conflict that doesn't say whether the ID or the token collided. This stops a CR from taking over another subscription and overwriting its plan and token.
  • Without externalRefId, the create is retried as before.
• Gateways without Allow caller-set subscription IDs, in-place plan/token updates, and fix subscription plan conflict errors #3804 ignore externalRefId, assign their own IDs, and leave externalRefId out of their responses. On those, recovery uses the API and application lookup, as it did before.

Gateway client

• SubscriptionCreatePayload and SubscriptionResponse carry externalRefId.
• SubscriptionUpdatePayload adds subscriptionPlanId (always sent; nil is an explicit null) and subscriptionToken.
• New UpdateSubscriptionStatus, which sends only the status and leaves the plan and token unchanged.
• New ListSubscriptions and SameApplication. FindSubscriptionIDByAPIAndApplication now uses them: it matches normalized application IDs, and returns an ID only when exactly one subscription matches.

Example

gateway/examples/subscription.yaml documents externalRefId and which fields can change in place.

Compatibility

• Existing CRs keep working: they need no changes. Their annotations migrate on the next reconcile, once the gateway subscription is confirmed to match the CR. A CR holding an immutable-field edit that the earlier operator rejected stays rejected.
• Gateway version: in-place plan and token updates and externalRefId need a gateway with the subscription API changes from Allow caller-set subscription IDs, in-place plan/token updates, and fix subscription plan conflict errors #3804. Older gateways accept the PUT but ignore the plan and token, so such changes don't take effect there. Status updates and create conflict recovery work as before.

Known limitations

• If a subscription is removed from the gateway directly, for example by a manual delete or a database reset, the CR still ends up failed rather than recreating it. The same happened before this PR for CRs that set spec.status.
• Two CRs that create the same subscription at the same moment can both pass the ownership check, since neither has a status.id yet.

Testing

• Unit tests:
  • ListSubscriptions, SameApplication, and the update payload, including the explicit null plan;
  • FindSubscriptionIDByAPIAndApplication, including matching only the normalized application and returning nothing when several subscriptions match;
  • conflict recovery:
    • adopting an externalRefId subscription on the same API and application;
    • refusing one on another API or for another application with a generic 409;
    • refusing when the API has no subscriptions;
    • the fallback on gateways without externalRefId, and when externalRefId is unset or empty;
  • ownership: refusing an ID that another CR on the same gateway holds, while allowing the CR's own ID and the same ID on another gateway;
  • updates:
    • status, plan and token in one PUT;
    • a status-only PUT after a 400 or 409, or when the token Secret is missing;
    • no status-only PUT after a 404, or while waiting for a SubscriptionPlan to deploy;
  • the upgrade baseline:
    • recorded when the gateway subscription matches;
    • rejected when apiId, applicationId or externalRefId no longer match;
    • accepted under a gateway-assigned ID on older gateways;
  • the existing Secret drift test.
• go build, go vet and all operator unit tests pass.
• make manifests generate with the pinned controller-gen v0.16.5 produces no further changes, and the Helm chart's CRD copy matches the generated base.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: wso2/api-platform
• Branch: kubernetes/helm/operator-helm-chart/v1.2.x
• File: .coderabbit.yaml
• Commit: 8e7b0a8
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: 61e50baa-5ded-4bb6-b8b6-cf2e484d7082

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}