Rename WSO2 API Platform Gateway CRD

[NomadXD]

When using both the Kubernetes Gateway API and the WSO2 API Platform Gateway Operator in the same cluster, there is a CRD naming conflict that creates a confusing user experience. Both Kubernetes Gateway API and WSO2 API Platform Gateway Operator define a resource named Gateway.

• Kubernetes Gateway API: gateways.gateway.networking.k8s.io
• WSO2 API Platform: gateways.gateway.api-platform.wso2.com

When users run kubectl get gateways, they only see one of these resources. Due to alphabetical ordering of API groups, gateway.api-platform.wso2.com is typically resolved before gateway.networking.k8s.io, meaning users see the API Platform gateways instead of the standard Kubernetes Gateway API resources. This forces users to use fully qualified names:

# Users must specify the full API group to disambiguate
kubectl get gateways.gateway.networking.k8s.io -A
kubectl get gateways.gateway.api-platform.wso2.com -A

The Kubernetes API Conventions emphasize choosing resource names carefully. While different API groups can technically have the same resource name (due to the full <resource>.<group> namespacing), this creates bad user experience.

A key best practice for Custom Resource Definitions is to avoid naming conflicts with standard Kubernetes APIs. The Kubernetes Gateway API (gateway.networking.k8s.io) is a standard API maintained by the Kubernetes SIG-Network and has reached GA status.

Impact of This Naming Conflict

This naming conflict creates several significant issues:

1. Forced Use of Fully Qualified Names

Users and tools must always use fully qualified resource names to avoid ambiguity, which increases complexity and cognitive load:

kubectl get gateways.gateway.networking.k8s.io -A
kubectl get gateways.gateway.api-platform.wso2.com -A

2. Broken Ecosystem Tools (Scripts and Automation)

The Kubernetes Gateway API is a standard with widespread adoption. Many shell scripts, CI/CD pipelines, and automation tools use shorthand kubectl commands that expect gateways to refer to the standard Gateway API. Examples include:

• Shell scripts and automation: Scripts using kubectl get gateways, kubectl describe gateway <name>, kubectl delete gateway <name>
• CI/CD pipelines: Deployment verification scripts checking gateway status with kubectl get gateways
• Monitoring scripts: Health checks and status verification that list or inspect gateways
• Documentation and tutorials: Examples showing shorthand commands like kubectl get gateways

These scripts and automation will either:

• Operate on the wrong Gateway resource silently
• Require modification to use fully qualified names everywhere (gateways.gateway.networking.k8s.io)
• Fail with confusing error messages when resources don't behave as expected

Note: Kubernetes operators and controllers are not affected since they specify the full Group/Version/Kind in their resource watches.

Proposed Solution: Rename WSO2 API Platform Gateway CRD

We propose renaming the WSO2 API Platform Gateway CRD to avoid conflict with the standard Kubernetes Gateway API. Here are suggested alternative names:

Option 1: APIGateway (Recommended)

• Resource name: apigateways.api-platform.wso2.com
• Kind: APIGateway

Pros:

• Clear and descriptive - immediately indicates API management purpose
• Distinguishes from traffic routing Gateway
• Concise and easy to type
• Industry-standard term (AWS API Gateway, Azure API Gateway, etc.)

Cons:

• None

Example usage:

kubectl get apigateways -A
kubectl describe apigateway my-api-gateway

Option 2: GatewayRuntime

• Resource name: gatewayruntimes.api-platform.wso2.com
• Kind: GatewayRuntime

Pros:

• Emphasizes the runtime/deployment aspect
• Distinguishes from configuration-focused K8s Gateway API
• Technically accurate

Cons:

• Longer to type
• Less immediately clear about API management purpose
• "Runtime" might not be obvious to all users

Example usage:

kubectl get gatewayruntimes -A
kubectl describe gatewayruntime my-gateway-runtime

Option 3: GatewayProxy

• Resource name: gatewayproxies.api-platform.wso2.com
• Kind: GatewayProxy

Pros:

• Emphasizes proxy functionality
• Distinguishes from K8s Gateway API

Cons:

• Less descriptive of API management purpose
• "Proxy" is a generic term

Example usage:

kubectl get gatewayproxies -A
kubectl describe gatewayproxy my-gateway-proxy

[renuka-fernando]

cc: @Tharsanan1 @Krishanx92 @malinthaprasan

[Tharsanan1]

@NomadXD we will rename it to APIGateway and release operator 0.3.0

[renuka-fernando]

+1