[Proposal] Adopt Go Template Syntax for Gateway Artifact Variable and Secret Resolution

[renuka-fernando]

Summary

• Use Go text/template syntax ({{ env "KEY" }}, {{ secret "KEY" }}) for injecting dynamic values into gateway artifact files, replacing the $secret{KEY} syntax.
• Apply this to all gateway artifact YAMLs/JSONs (RestApi, LlmProvider, LlmProxy, LlmProviderTemplate, McpProxy, etc.), with template expressions supported in any string field across the entire artifact — not limited to policy params as with the current $secret{KEY} support, but also in fields like upstream.auth, and endpoint configuration.
• Render templates on the raw artifact string before YAML/JSON parsing so template expressions never need to round-trip through a structured decoder.
• Introduce a SecretTracker that records resolved secret values during rendering so the config-dump endpoint can redact them using value-based replacement.
• Ship a standard FuncMap including env, secret, redact, default, required, and common string helpers, with zero new external dependencies (stdlib text/template only).

Motivation

• $secret{KEY} is already supported uniformly across all artifact kinds, but only within policy params — fields like upstream auth credentials cannot currently reference secrets.
• Extending $secret{KEY} to cover all artifact fields, and separately adding $env{KEY} for environment variable injection, would require maintaining two custom mini-languages each needing their own parser, error reporting, and documentation.
• GitOps users already ship artifacts through Helm, Kustomize, and Consul Template; Go template syntax is the de facto standard of that ecosystem.

Proposal

• Adopt Go text/template as the single templating layer for all gateway artifact inputs, rendered before format-specific parsing. Template expressions are supported in any string field across the entire artifact — metadata, spec, policy params, upstream config, etc.
• Provide a well-defined FuncMap exposing env, secret, redact, default, required, and safe string helpers (upper, lower, trim, replace). All Go text/template built-in functions are also available — and, or, not, eq/ne/lt/gt, len, printf, etc. — enabling conditionals and comparisons without any additional registration.
• Introduce a redact pipe function that marks any value — regardless of source — for redaction in config dumps. The SecretTracker collects all values passed through redact during rendering; the dump serializer replaces any occurrence of those values in the output with ***REDACTED***.
• The secret function resolves keys through the existing gateway secrets service and internally pipes through redact, so secrets are always redacted without the user needing to add | redact explicitly. env does not redact by default — users pipe through redact when the env var holds a sensitive value.

Note: redact applies only to the gateway controller and policy engine config dump endpoints — it has no effect on the Envoy router config dump. There should be no sensitive data forwarded to the router. If a user applies redact to a field that is also configured in the router (e.g., upstream URL), the value will still appear in the Envoy dump unredacted — redact gives no protection there and only hides the value from the controller and PE dumps.

• Support both YAML and JSON artifact formats; rendering happens on raw strings so JSON template values work without escaping, and YAML template values use single-quoted scalars to avoid {{ being interpreted as a flow mapping.
• Fail loudly on unresolved required values: {{ env "KEY" | required "KEY must be set" }} aborts loading the artifact with a clear error.

Note — Helm/Kustomize double-templating: When artifact files are managed through Helm charts, Helm processes {{ }} expressions before the artifact reaches the gateway, causing failures on gateway-specific functions like env and secret. Escape gateway template expressions inside Helm templates using {{ "{{" }}:

auth:
  apiKey: '{{ "{{" }} secret "backend-api-key" {{ "}}" }}'

Helm renders this to the literal string {{ secret "backend-api-key" }}, which the gateway then processes normally.

This makes a single design decision cover two currently-open questions: (1) variable syntax for artifact files across the whole gateway, and (2) how secrets are redacted when artifact state is exposed via observability or debug endpoints.

Secret Metadata Propagation to Policy Engine

The gateway controller renders templates and resolves secrets before building xDS resources. By the time xDS is sent to the policy engine, all template expressions are gone — the PE sees only resolved values and cannot independently detect which fields contain secrets.

The PE has its own config dump endpoint (used for debugging) and must also redact secrets. Since config dumps are debug-only, value-based redaction is used: the controller passes the set of resolved secret values to the PE via xDS resource metadata, and the PE replaces any occurrence of those values in its dump output.

Proposed approach: The controller populates a TransportMetadata struct embedded in StoredPolicyConfig with the resolved secret values from SecretTracker.

// TransportMetadata carries controller-to-PE transport-level metadata,
// separate from the API configuration itself.
type TransportMetadata struct {
    SensitiveValues []string `json:"sensitive_values,omitempty"`
}

type StoredPolicyConfig struct {
    ID                string                       `json:"id"`
    Configuration     policyenginev1.Configuration `json:"configuration"`
    Version           int64                        `json:"version"`
    TransportMetadata TransportMetadata            `json:"transport_metadata,omitempty"`
}

The PE:

• Receives transport_metadata.sensitive_values as part of the existing xDS update flow, no protocol changes required
• Stores TransportMetadata in memory alongside the configuration
• On config dump, serializes the resource then replaces any occurrence of a tracked value with ***REDACTED***
• Excludes transport_metadata from the dump output itself (strip before serializing the dump response)

Configuration Changes

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: reading-list-api-v1
spec:
  context: /reading-list/v1
  upstream:
    main:
      url: '{{ env "BACKEND_URL" | default "http://localhost:8080" }}'
    auth:
      # secret is always redacted in dumps automatically
      apiKey: '{{ secret "backend-api-key" }}'
      # env var holding a sensitive value — explicitly marked for redaction
      token: '{{ env "BEARER_TOKEN" | redact }}'
  policies:
    - name: set-headers
      version: v1
      params:
        request:
          headers:
            - name: Authorization
              value: 'Bearer {{ secret "oauth-token" }}'
            - name: X-Log-Level
              value: '{{ if env "DEBUG" }}debug{{ else }}info{{ end }}'

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "LlmProvider",
  "metadata": { "name": "openai-prod" },
  "spec": {
    "displayName": "OpenAI Provider",
    "version": "v1.0",
    "template": "openai-template",
    "vhost": "api.openai.local",
    "upstream": {
      "url": "{{ env \"OPENAI_ENDPOINT\" | default \"https://api.openai.com/v1\" }}",
      "auth": {
        "type": "api-key",
        "header": "Authorization",
        "value": "{{ secret \"openai-api-key\" }}"
      }
    }
  }
}

Examples

Before:

spec:
  upstream:
    auth:
      apiKey: $secret{backend-api-key}

After:

spec:
  upstream:
    auth:
      # from secrets service — redacted automatically
      apiKey: '{{ secret "backend-api-key" }}'
      # from env var — redacted explicitly
      token: '{{ env "BEARER_TOKEN" | redact }}'

Drawbacks

• Verbosity for the simple case: {{ env "KEY" }} is noisier than $env{KEY} when no defaults or transformations are needed.
• YAML quoting footgun: template expressions starting at the beginning of a YAML value must be single-quoted, otherwise YAML parses {{ ... }} as a flow mapping and fails. Error messages must make this obvious.
• Template parse errors surface before schema errors: a malformed template produces a text/template parse error instead of a config-schema error, which may confuse users debugging field typos.
• No compile-time schema validation: template values are strings at parse time, so type-checking (e.g., port must be an int) happens after rendering, not before.
• redact does not apply to the router: redact only affects the gateway controller and policy engine config dump endpoints. Any artifact field that is also forwarded to the Envoy router will appear as-is in the Envoy admin config dump — redact has no effect there. There should be no sensitive data passed to the router; if a user mistakenly applies redact to a field that flows to the router (e.g., upstream URL), the value will still be visible in the Envoy dump.

Alternatives Considered

Alternative 1: Custom $env{KEY} / $secret{KEY} syntax (current proposal)

• What: Introduce a dedicated mini-syntax with a handwritten parser for artifact files.
• Pros: Very compact; unambiguous inside YAML; no quoting rules.
• Cons: Needs its own parser, docs, and error messages; will grow features (defaults, conditionals, transforms) and re-invent Go templates badly.
• Why rejected: Builds a second templating dialect that the team will maintain forever, while every feature it grows already exists in text/template.

Alternative 2: Shell/Docker-style ${env:KEY} / ${secret:KEY}

• What: Use Docker Compose / systemd-style variable interpolation.
• Pros: Familiar from Compose, systemd, and many CI systems; compact.
• Cons: No standard library parser in Go; conflicts with shell variable expansion in Compose files that already template our YAMLs; defaults require yet more ad-hoc syntax (${KEY:-default}).
• Why rejected: Double-interpolation hazard with Docker Compose, and still requires a custom parser.

Alternative 3: CEL (Common Expression Language)

• What: Use Google's CEL for configuration expressions.
• Pros: Powerful, typed, well-specified; already used by Kubernetes admission policies.
• Cons: Heavy dependency; overkill for string substitution; unfamiliar to most users as a config language; no native Go stdlib support.
• Why rejected: Weight and learning curve far exceed the need for "inject an env var with a default."

Secret Redaction Strategy: Value-based vs Path-based

• Value-based (GitHub Actions, Ansible): replace every occurrence of a resolved secret value in the serialized output. Simple to implement, catches accidental leaks in unexpected fields, but can produce false positives if a secret value equals a common config string (e.g., "true", "admin").
• Path-based (Terraform, Kubernetes): record which field paths were populated by {{ secret ... }} before rendering; redact only those paths in the structured dump. Deterministic, no false positives, but requires translating paths across model boundaries (artifact YAML → xDS → PE internal).
• Decision: value-based. Config dumps are debug-only endpoints. Real secrets (API keys, tokens) are high-entropy and will not collide with non-secret config values in practice. Value-based is simpler, requires no path translation, and catches leaks in derived or unexpected fields that path-based would miss.

Implementation Details

• Error reporting: Template parse and execution errors must include the offending line/column in the original artifact file. The controller wraps raw text/template errors with file location context before surfacing them, so users see artifact.yaml:27:14: unknown function "secret" rather than an opaque template engine error.
• required failure behavior: Treated the same as any other artifact validation failure. In immutable gateway mode, a required failure during startup prevents the gateway controller from starting entirely.

Compatibility

• Breaking changes?: Yes — $secret{KEY} is replaced by {{ secret "KEY" }}. Any artifact currently using $secret{KEY} in policy params must be migrated. Any artifact config value containing a literal {{ must also be escaped as {{ "{{" }}.

References

• Go text/template documentation
• Consul Template function list
• Helm template functions
• Terraform sensitive value redaction
• GitHub Actions secret masking

[malinthaprasan]

As of now we haven't used the existing $secret internally nor its exposed as a documentation as well. Hence +1 to remove $secret and allow the go template based option.

[renuka-fernando]

Here is a simple demo.

Here are the deployment steps.

1. Renders go templates
2. Gateway-level validations
3. Store the templated data in the DB
4. Pass the rendered data to the Router and Policy Engine.

Secret

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: Secret
metadata:
  name: my-top-secret
  labels:
    environment: production
    team: backend
    version: v1
spec:
  displayName: My Top Secret
  value: hello world :) this is not a secret!!! :)

LLM Provider

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: LlmProvider
metadata:
  name: wso2-openai-provider
spec:
  displayName: WSO2 OpenAI Provider
  version: v1.0
  template: openai
  vhost: api.openai.local
  upstream:
    url: "http://httpbin.org/anything"
    auth:
      type: api-key
      header: Authorization
      value: '{{ secret "my-top-secret" }}'
  accessControl:
    mode: deny_all
    exceptions:
      - path: /chat/completions
        methods: [POST]
      - path: /models
        methods: [GET]
      - path: /models/{modelId}
        methods: [GET]

Policy Engine Config Dump - Redacted Secret

DB - The Templated Value

Invocation

{
    "args": {},
    "data": "{\n    \"model\": \"gpt-4.1-2025-04-14\",\n    \"messages\": [\n        {\n            \"role\": \"user\",\n            \"content\": \"Hello\"\n        }\n    ]\n}",
    "files": {},
    "form": {},
    "headers": {
        "Accept": "*/*",
        "Accept-Encoding": "gzip, deflate, br",
        "Authorization": "hello world :) this is not a secret!!! :)",
        "Cache-Control": "no-cache",
        "Content-Length": "141",
        "Content-Type": "application/json",
        "Host": "httpbin.org",
        "Postman-Token": "9b5c67cf-f446-4cf0-a7ad-b84e76bb6549",
        "User-Agent": "PostmanRuntime/7.53.0",
        "X-Amzn-Trace-Id": "Root=1-69e08c09-0725b752249bb10e15be81a0",
        "X-Envoy-Expected-Rq-Timeout-Ms": "60000",
        "X-Envoy-Original-Host": "api.openai.local",
        "X-Envoy-Original-Path": "/chat/completions"
    },
    "json": {
        "messages": [
            {
                "content": "Hello",
                "role": "user"
            }
        ],
        "model": "gpt-4.1-2025-04-14"
    },
    "method": "POST",
    "origin": "203.94.95.14",
    "url": "http://httpbin.org/anything/chat/completions"
}