[Proposal] Gateway Image Build: Version from build.yaml, Not CLI Flags

[renuka-fernando]

Summary

Update (2026-02-02): Renamed gateway.yaml → build.yaml and gateway-lock.yaml → build-lock.yaml to better reflect the build-focused purpose of these files.

• Gateway version is mandatory for ap gateway image build (no more latest default)
• Rename policy-manifest.yaml → build.yaml (build now covers full gateway, not just policy engine)
• Rename policy-manifest-lock.yaml → build-lock.yaml
• CLI/gateway major version compatibility enforced (ap v1.x works with gateway v1.x only)
• Version comes from build.yaml only (no CLI flag override)
• CI/CD support with meaningful exit codes

Sample new build.yaml:

gateway:
  version: "1.0.4"    # Required: gateway version to build
  # Optional: override base images for air-gapped/custom deployments
  # images:
  #   builder: "internal-registry.company.com/wso2/gateway-builder:1.0.4"
  #   controller: "internal-registry.company.com/wso2/gateway-controller:1.0.4"
  #   router: "internal-registry.company.com/wso2/gateway-router:1.0.4"

policies:
  - name: jwt-auth
    gomodule: github.com/wso2/gateway-controllers/policies/jwt-auth@v0
  - name: rate-limit
    gomodule: github.com/wso2/gateway-controllers/policies/rate-limit@v0

ap gateway image build \
  --out-controller=custom/wso2/gateway-controller:1.0.4 \
  --out-router=custom/wso2/gateway-router:1.0.4 \
  --out-policy-engine=custom/wso2/gateway-policy-engine:1.0.4

Motivation

Problem Statement

The ap gateway image build command currently defaults to latest when no version is specified, which creates several serious issues:

1. Non-reproducible builds: Running the same command at different times can produce different gateway images, making debugging and rollbacks difficult.

2. CLI flag overrides break GitOps: Using --version or --builder-image/--controller-image/--router-image CLI flags to specify versions bypasses version control. The actual version used in a build is not captured in the repository, making it impossible to reproduce builds or audit what was deployed. Different team members or CI jobs may use different flags, leading to inconsistent deployments.

3. Version compatibility failures: The ap CLI and gateway have strict compatibility requirements (major versions must match), but the current default makes it easy to accidentally use incompatible versions.

Detailed Design

Overview

The design consolidates gateway configuration into a single build.yaml file that explicitly declares the target gateway version. A corresponding build-lock.yaml captures resolved image references and policy checksums for reproducible builds. The CLI enforces version compatibility and provides clear feedback in both interactive and CI/CD environments.

Changes Required

Component	File/Area	Change Description
CLI	ap gateway image build	Remove latest default, require version from build.yaml
CLI	ap gateway image build	Add --skip-version-check flag for compatibility bypass
CLI	ap gateway image build	Add flags to output built image names (e.g., --out-controller, --out-router, --out-policy-engine)
CLI	Version validation	Implement major version compatibility check between CLI and gateway
Config	policy-manifest.yaml	Rename to build.yaml with new schema
Config	policy-manifest-lock.yaml	Rename to build-lock.yaml with new schema
Docs	CLI documentation	Document exit codes and migration steps

Configuration Changes

Why Rename policy-manifest.yaml to build.yaml?

Previously, the ap gateway image build command only built the policy engine, hence the name policy-manifest.yaml made sense. Now the command builds the entire gateway (controller, router, and policy engine), so renaming to build.yaml better reflects the broader scope.

New build.yaml Schema

The build.yaml file replaces policy-manifest.yaml with an expanded schema that includes explicit gateway versioning:

gateway:
  version: "1.0.4"    # Required: gateway version to build
  # Optional: override base images for air-gapped/custom deployments
  # images:
  #   builder: "custom-registry/gateway-builder:1.0.4"
  #   controller: "custom-registry/gateway-controller:1.0.4"
  #   router: "custom-registry/gateway-router:1.0.4"

policies:
  - name: jwt-auth
    gomodule: github.com/wso2/gateway-controllers/policies/jwt-auth@v0
  - name: rate-limit
    gomodule: github.com/wso2/gateway-controllers/policies/rate-limit@v0

If --out-* flags are not specified, output images are tagged with the gateway.version value (e.g., gateway-controller:1.0.4, gateway-router:1.0.4, gateway-policy-engine:1.0.4).

New build-lock.yaml Schema

The lock file captures the fully resolved state for reproducible builds:

generatedAt: "2026-02-01T10:30:00Z"
generatedBy: "ap v1.2.0"

gateway:
  version: "1.0.4"
  images:
    builder: "ghcr.io/wso2/api-platform/gateway-builder:1.0.4"
    controller: "ghcr.io/wso2/api-platform/gateway-controller:1.0.4"
    router: "ghcr.io/wso2/api-platform/gateway-router:1.0.4"
    policyEngine: "ghcr.io/wso2/api-platform/gateway-policy-engine:1.0.4"

policies:
  - name: jwt-auth
    version: v0.1.1
    gomodule: github.com/wso2/gateway-controllers/policies/jwt-auth@v0.1.1
  - name: rate-limit
    version: v0.1.1
    gomodule: github.com/wso2/gateway-controllers/policies/rate-limit@v0.1.1

Version Source

The gateway configuration is read from build.yaml only. No CLI flags, no environment variables, no fallbacks.

Field	Required	Purpose
gateway.version	Yes	Gateway version to build; also used as default tag for output images
gateway.images	No	Override base images for air-gapped/custom deployments

If version is missing, the build fails with exit code 3.

File	Purpose
build.yaml	Source of truth - configuration must be specified here
build-lock.yaml	Read-only output - records resolved versions for audit/reproducibility

Why no CLI override?

• GitOps alignment: Version should be in version-controlled files, not CLI arguments
• Single source of truth: Eliminates confusion about which version was actually used
• Reproducibility: Same build.yaml always builds the same version

CLI/Gateway Version Compatibility

The ap CLI enforces major version compatibility with the gateway:

ap CLI Version	Compatible Gateway Versions
ap v1.x	gateway v1.x only
ap v2.x	gateway v2.x only
ap v3.x	gateway v3.x only

Exit Codes

The CLI uses meaningful exit codes for automation:

Scenario	Behavior
Missing version in build.yaml	Error with exit code 3
Incompatible version	Error with exit code 2 + upgrade suggestion
Successful build	Exit code 0
General error	Exit code 1

[renuka-fernando]

Related discussion: #516

Directory structure

gateways/
├── ai-gateway/
│   ├── gateway.yaml
│   └── gateway-lock.yaml
└── ecommerce-gateway/
    ├── gateway.yaml
    └── gateway-lock.yaml

By default newly build images will prefixed with the parent dir name.

i.e.

ghcr.io/wso2/api-platform/ai-gateway-gateway-controller:1.0.4
ghcr.io/wso2/api-platform/ai-gateway-router:1.0.4
ghcr.io/wso2/api-platform/ai-gateway-policy-engine:1.0.4

[Krishanx92]

+1 to include gateway version to manifest yaml, otherwise giving base image version from cli is not very intuitive.
Also with out keep it as gateway.yaml shall we keep the manifest key word as well?

policy-manifest.yaml —> gateway-manifest.yaml

[pubudu538]

We should not bind the version of the API Platform CLI to the gateway version. CLI is not only for the gateway but also it works with other platform components as well. Could you please explain the reasons behind this decision?

[renuka-fernando]

Do we need ap v1 to support gateway v2 as well?
For now, we can support this, BTW, if we have done some breaking changes in the gateway v2 rest API, we may need to ask users to use ap v2. For now, let's not enforce this.

[renuka-fernando]

@nuwand, @malinthaprasan, @pubudu538 and @Krishanx92 agreed on changing the gateway.yaml -> build.yaml as currently we have Config.toml (without gateway prefix), hence just build.yaml

[piyumaldk]

The suggested build.yaml uses a gateway version without the "v" prefix, which is inconsistent with the policy versioning format. However, since this follows Docker versioning conventions, we will keep the structure as mentioned above.

[renuka-fernando]

gateway:
  version: "1.0.4"    ##### without "v"
policies:
  - name: jwt-auth
    gomodule: github.com/wso2/gateway-controllers/policies/jwt-auth@v0 ##### with "v"
  - name: advanced-ratelimit
    gomodule: github.com/wso2/gateway-controllers/policies/advanced-ratelimit@v0.2.1 ##### with "v"

@nuwand, please note.