API Undeployment Handling in Gateway-Controller

[dushaniw]

Problem Statement

When Platform-API sends an APIUndeployed event (indicating a deployment is being transitioned out of active state), Gateway-Controller needs to handle it appropriately. This is distinct from the GW Controller REST API [DELETE /apis/{id}]endpoint, which permanently removes APIs, its API keys etc. We need to define what "undeployed" means in the gateway's state model and how it should behave.

Proposed Solution

When APIUndeployed Event Arrives:

1. Set status to "undeployed" (NOT delete)

   cfg.Status = models.StatusUndeployed
   cfg.UpdatedAt = time.Now()
   

   A new status is introduced to ConfigStatus as undeployed. Will be keeping the DeployedVersion in StoredConfig as it is. It tracks the last successful deployment.

2. Keep config in memory/DB for potential redeploy

   • Supports v1 → undeploy → v2 deploy cycle
   • Uses same apiId as key (no DeploymentID needed)

3. Clear xDS routes (snapshot excludes undeployed)

   • Router removes the routes automatically
   • Trigger snapshot update

4. Preserve API Keys and Policies

   • API keys are not removed as they may be needed if API is redeployed
   • Policy configurations are not removed as they are tied to the API and will be re-added on redeploy
   • Only xDS routes are cleared

• This approach supports separates concerns for REST DELETE = permanent removal and Event UNDEPLOY = temporary deactivation
• And matches platform-api semantics where the Platform keeps artifact and gateway tracks undeployed state

REST API Considerations

Need to handle the visibility of undeployed APIs in Controller REST API with this solution.

• ListAPIs, SearchDeployments: Exclude undeployed by default (treat as inactive)
• GetConfigDump: Exclude undeployed for clarity
• GetAPI by handle: Return 404 if undeployed (treat as "not found")
• Whether to give a REST Undeploy Endpoint in GW Controller API. However, undeploy is an intermediate state in the PlatformAPI deployment lifecycle, not a primary operation. Standalone GW users should CREATE or DELETE APIs directly, not undeploy them.

[renuka-fernando]

+1

BTW, we can include this in the Gateway Controller's Config Dump with status as inactive. This config dump is for troubleshooting purposes.

If we want to support this even in the standalone gateway, without losing API keys, we can add a new field in the spec section like enabled: true or false or active or not. BTW, we can do this if we get such a requirement.

[malinthaprasan]

+1 for keeping the undeployed status instead of deletion.

Regarding REST APIs,

1. ListAPIs: Shall we list all the APIs along with deployment status?. SearchDeployments: We should not list undeployed APIs.
2. GetAPI by handle: Can still return 200 with deployment status
3. I think we can provide an updeploy operation. Its a temporary suspension without deletion. Keeping API keys etc are applicable here too.

[renuka-fernando]

If we are providing a way to undeploy APIs using the GW Controller REST API, we should also make it possible to define it in the API YAML spec. Users may use the GitOps approach or the K8s Operator approach, and this will enable those users to have the undeploy option as well.

Proposed Field: enabled

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: weather-api-v1.0
spec:
  enabled: false  # API is undeployed (routes cleared, config preserved)
  displayName: Weather-API
  version: v1.0
  context: /weather/$version
  ...

• enabled: true (default) - API is deployed and routes are active
• enabled: false - API is undeployed (routes cleared, API keys and config preserved)

Industry Patterns

Platform	Field	Values	Use Case
Kubernetes CronJob	spec.suspend	true/false	Temporarily stop job scheduling
Argo Rollouts	spec.paused	true/false	Pause in-flight rollout
ArgoCD	syncPolicy.automated.enabled	true/false	Enable/disable automated sync

Why enabled over alternatives?

Option	Issue
suspend: true	Semantically implies "paused mid-operation"; CronJob uses this for stopping future executions
paused: true	Implies an in-flight operation is paused (Argo Rollouts pattern)
state: deployed/undeployed	More verbose; enum adds complexity when boolean suffices
enabled: true/false	Positive-sense boolean, universally understood, matches ArgoCD pattern

Following Kubernetes API design best practices, enabled is a positive-sense boolean that clearly communicates intent without ambiguity.

[malinthaprasan]

Sorry, shouldn't this be part of a seperate "status" field which is not part of the spec?
This is similar to k8s pod yaml.

[malinthaprasan]

Ah, maybe its correct to use field under spec because its the desired state.

Rather than using a generic enabled: true/false, I suggest using deploymentState since this is specifically about deployment lifecycle:

So we might need both "status" and spec level status fields. We might add the root level "status" later (not required with these changes).

spec level status fields - This is the desired state.
root level status - This is the actual current state.

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: weather-api-v1.0
spec:
  deploymentState: undeployed         # User intent
  displayName: Weather-API
  version: v1.0
  context: /weather/$version

status:
  deploymentState: undeployed         # Observed current state
  lastTransitionTime: "2026-01-21T08:53:44Z"
  .. and any other status