Skip to content

[Gateway operator] externalRefId and in-place plan/token updates for Subscription CRs #3918

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
thivindu wants to merge 4 commits into
base: main
Choose a base branch
from
Open

[Gateway operator] externalRefId and in-place plan/token updates for Subscription CRs #3918

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
04ec495
Support externalRefId and in-place plan/token updates in the gateway …
thivindu Oct 25, 2026
239fb30
Adopt a subscription after a create conflict only for the CR's applic…
thivindu Oct 25, 2026
b7efb1a
Fix review comments
thivindu Oct 30, 2026
98db446
Verify subscription updates and keep the status fallback retryable
thivindu Oct 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions gateway/examples/subscription.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,16 @@
# A Subscription binds an application to an API and (optionally) a plan.
# The token is sourced from a Kubernetes Secret so the plaintext is never
# stored in the CR; the operator forwards it to the gateway which only
# persists its hash. The gateway-issued UUID is recorded in .status.id and
# used for subsequent update/delete calls.
# persists its hash. The gateway-issued UUID (or spec.externalRefId, when set)
# is recorded in .status.id and used for subsequent update/delete calls.
# subscriptionPlanId, status and the token (including a change to the Secret
# data) are updated in place; the other spec fields are immutable.
apiVersion: gateway.api-platform.wso2.com/v1
kind: Subscription
metadata:
name: petstore-acme-bronze
spec:
# externalRefId: acme-petstore-sub-01 # optional; used as the subscription ID
apiId: petstore-api-v1.0
subscriptionPlanId: bronze-1k-per-min
status: ACTIVE
Expand Down
24 changes: 18 additions & 6 deletions kubernetes/gateway-operator/api/v1/subscription_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,26 +21,38 @@ import (
)

// SubscriptionSpec mirrors the management-API SubscriptionCreateRequest
// payload. The gateway-controller issues a UUID id which the controller
// persists to .status.id for subsequent PUT/DELETE.
// payload. The gateway-controller issues a UUID id (or uses externalRefId when
// set) which the controller persists to .status.id for subsequent PUT/DELETE.
// subscriptionToken, subscriptionPlanId and status can be changed after the
// subscription is deployed; the other fields are immutable.
type SubscriptionSpec struct {
// ExternalRefId is an optional caller-supplied reference ID. When set, the
// gateway uses it as the subscription id instead of generating one.
// Must be unique on the gateway. Immutable once deployed.
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=64
// +kubebuilder:validation:Pattern=`^[A-Za-z0-9][A-Za-z0-9._-]*$`
// +optional
ExternalRefId *string `json:"externalRefId,omitempty"`

// ApiId is the API identifier (deployment id or handle).
// +kubebuilder:validation:Required
ApiId string `json:"apiId"`

// SubscriptionToken is the opaque token used to invoke the API. The
// token is sent as plaintext to the gateway which stores only its hash;
// inline in the CR or supplied via valueFrom.
// inline in the CR or supplied via valueFrom. Changing it (or the
// referenced Secret data) rotates the token on the gateway in place.
// +kubebuilder:validation:Required
SubscriptionToken SecretValueSource `json:"subscriptionToken"`

// ApplicationId is an optional application identifier.
// +optional
ApplicationId *string `json:"applicationId,omitempty"`

// SubscriptionPlanId is an optional plan UUID. When the plan is also
// managed via SubscriptionPlan CR, set this to the SubscriptionPlan's
// .status.id once it has been deployed.
// SubscriptionPlanId is an optional plan UUID, or the name of a
// SubscriptionPlan CR in the same namespace. Changing it moves the
// subscription to the new plan in place; removing it removes the plan.
// +optional
SubscriptionPlanId *string `json:"subscriptionPlanId,omitempty"`

Expand Down
5 changes: 5 additions & 0 deletions kubernetes/gateway-operator/api/v1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

24 changes: 18 additions & 6 deletions kubernetes/gateway-operator/api/v1alpha1/subscription_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,26 +21,38 @@ import (
)

// SubscriptionSpec mirrors the management-API SubscriptionCreateRequest
// payload. The gateway-controller issues a UUID id which the controller
// persists to .status.id for subsequent PUT/DELETE.
// payload. The gateway-controller issues a UUID id (or uses externalRefId when
// set) which the controller persists to .status.id for subsequent PUT/DELETE.
// subscriptionToken, subscriptionPlanId and status can be changed after the
// subscription is deployed; the other fields are immutable.
type SubscriptionSpec struct {
// ExternalRefId is an optional caller-supplied reference ID. When set, the
// gateway uses it as the subscription id instead of generating one.
// Must be unique on the gateway. Immutable once deployed.
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=64
// +kubebuilder:validation:Pattern=`^[A-Za-z0-9][A-Za-z0-9._-]*$`
// +optional
ExternalRefId *string `json:"externalRefId,omitempty"`

// ApiId is the API identifier (deployment id or handle).
// +kubebuilder:validation:Required
ApiId string `json:"apiId"`

// SubscriptionToken is the opaque token used to invoke the API. The
// token is sent as plaintext to the gateway which stores only its hash;
// inline in the CR or supplied via valueFrom.
// inline in the CR or supplied via valueFrom. Changing it (or the
// referenced Secret data) rotates the token on the gateway in place.
// +kubebuilder:validation:Required
SubscriptionToken SecretValueSource `json:"subscriptionToken"`

// ApplicationId is an optional application identifier.
// +optional
ApplicationId *string `json:"applicationId,omitempty"`

// SubscriptionPlanId is an optional plan UUID. When the plan is also
// managed via SubscriptionPlan CR, set this to the SubscriptionPlan's
// .status.id once it has been deployed.
// SubscriptionPlanId is an optional plan UUID, or the name of a
// SubscriptionPlan CR in the same namespace. Changing it moves the
// subscription to the new plan in place; removing it removes the plan.
// +optional
SubscriptionPlanId *string `json:"subscriptionPlanId,omitempty"`

Expand Down
5 changes: 5 additions & 0 deletions kubernetes/gateway-operator/api/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

48 changes: 36 additions & 12 deletions ...rnetes/gateway-operator/config/crd/bases/gateway.api-platform.wso2.com_subscriptions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,10 @@ spec:
spec:
description: |-
SubscriptionSpec mirrors the management-API SubscriptionCreateRequest
payload. The gateway-controller issues a UUID id which the controller
persists to .status.id for subsequent PUT/DELETE.
payload. The gateway-controller issues a UUID id (or uses externalRefId when
set) which the controller persists to .status.id for subsequent PUT/DELETE.
subscriptionToken, subscriptionPlanId and status can be changed after the
subscription is deployed; the other fields are immutable.
properties:
apiId:
description: ApiId is the API identifier (deployment id or handle).
Expand All @@ -64,22 +66,32 @@ spec:
description: BillingSubscriptionId is an optional billing subscription
identifier.
type: string
externalRefId:
description: |-
ExternalRefId is an optional caller-supplied reference ID. When set, the
gateway uses it as the subscription id instead of generating one.
Must be unique on the gateway. Immutable once deployed.
maxLength: 64
minLength: 1
pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
type: string
status:
description: |-
Status is the lifecycle state for this subscription. Mirrors the
management-API SubscriptionCreateRequest.Status enum.
type: string
subscriptionPlanId:
description: |-
SubscriptionPlanId is an optional plan UUID. When the plan is also
managed via SubscriptionPlan CR, set this to the SubscriptionPlan's
.status.id once it has been deployed.
SubscriptionPlanId is an optional plan UUID, or the name of a
SubscriptionPlan CR in the same namespace. Changing it moves the
subscription to the new plan in place; removing it removes the plan.
type: string
subscriptionToken:
description: |-
SubscriptionToken is the opaque token used to invoke the API. The
token is sent as plaintext to the gateway which stores only its hash;
inline in the CR or supplied via valueFrom.
inline in the CR or supplied via valueFrom. Changing it (or the
referenced Secret data) rotates the token on the gateway in place.
properties:
value:
description: |-
Expand Down Expand Up @@ -240,8 +252,10 @@ spec:
spec:
description: |-
SubscriptionSpec mirrors the management-API SubscriptionCreateRequest
payload. The gateway-controller issues a UUID id which the controller
persists to .status.id for subsequent PUT/DELETE.
payload. The gateway-controller issues a UUID id (or uses externalRefId when
set) which the controller persists to .status.id for subsequent PUT/DELETE.
subscriptionToken, subscriptionPlanId and status can be changed after the
subscription is deployed; the other fields are immutable.
properties:
apiId:
description: ApiId is the API identifier (deployment id or handle).
Expand All @@ -256,22 +270,32 @@ spec:
description: BillingSubscriptionId is an optional billing subscription
identifier.
type: string
externalRefId:
description: |-
ExternalRefId is an optional caller-supplied reference ID. When set, the
gateway uses it as the subscription id instead of generating one.
Must be unique on the gateway. Immutable once deployed.
maxLength: 64
minLength: 1
pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
type: string
status:
description: |-
Status is the lifecycle state for this subscription. Mirrors the
management-API SubscriptionCreateRequest.Status enum.
type: string
subscriptionPlanId:
description: |-
SubscriptionPlanId is an optional plan UUID. When the plan is also
managed via SubscriptionPlan CR, set this to the SubscriptionPlan's
.status.id once it has been deployed.
SubscriptionPlanId is an optional plan UUID, or the name of a
SubscriptionPlan CR in the same namespace. Changing it moves the
subscription to the new plan in place; removing it removes the plan.
type: string
subscriptionToken:
description: |-
SubscriptionToken is the opaque token used to invoke the API. The
token is sent as plaintext to the gateway which stores only its hash;
inline in the CR or supplied via valueFrom.
inline in the CR or supplied via valueFrom. Changing it (or the
referenced Secret data) rotates the token on the gateway in place.
properties:
value:
description: |-
Expand Down
Loading
Loading