API Call Execution in Kyverno#

Overview#

The pkg/engine/apicall/ package handles Kyverno's outbound HTTP requests for policy context entries of type APICall. It manages the full lifecycle: variable substitution in URLs and data, request construction, header injection, TLS configuration, response size enforcement, and storing results back into the evaluation context.

Entry point: New() constructs an apiCall struct backed by an Executor. Call FetchAndLoad() to execute a call and store the result, or Fetch() + Store() individually.

Call Dispatch: K8s API vs. Service Calls#

Executor.Execute() routes on whether APICall.URLPath is set:

• URLPath set → executeK8sAPICall(): delegates to client.RawAbsPath() (the in-cluster Kubernetes client). RBAC Forbidden/Unauthorized errors are surfaced with explicit "permission denied" messages.
• Service set → executeServiceCall(): builds a standalone HTTP client and fires an outbound request to the configured URL.

Only GET and POST are accepted for service calls; other methods are rejected at request-build time 1.

Request Construction#

buildHTTPRequest() assembles the *http.Request:

1. Body encoding — For POST requests, buildRequestData() flattens []kyvernov1.RequestData (key-value pairs) into a JSON object via json.NewEncoder. GET requests send no body.
2. Context propagation — The request is created with http.NewRequestWithContext, passing the caller's context.Context for cancellation/timeout support 2.
3. Headers — addHTTPHeaders() iterates over service.Headers and adds each via req.Header.Add().

Variable substitution in the URL, method, and data fields happens before execution in Fetch() via variables.SubstituteAllInType().

Authorization Token Injection#

addHTTPHeaders() automatically injects a Bearer token when no Authorization header has been explicitly set 3:

if req.Header.Get("Authorization") == "" {
    if token, ok := readScopedToken(); ok && token != "" {
        req.Header.Add("Authorization", "Bearer "+token)
    }
}

readScopedToken() reads a projected ServiceAccount token from disk. The default path is /var/run/secrets/kyverno/apicall/token 4, overridable via the KYVERNO_SCOPED_TOKEN_PATH environment variable 5. If the file is missing or unreadable, a warning is logged once (via sync.Once) and the call proceeds without an Authorization header — it does not fail 6.

This token carries a custom OIDC audience (default: kyverno-svc.kyverno.io) configured in the Helm chart via .Values.apiCallToken.audience. A leaked scoped token cannot be replayed against the Kubernetes API server because its audience won't match 7.

The same readScopedToken() is used by scopedTokenClient (created via NewScopedTokenClient()), which wires the same automatic injection for outbound CEL HTTP calls across all policy compilers.

TLS and HTTP Client#

buildHTTPClient() returns:

• A plain http.Client{Timeout: timeout} when no CABundle is configured.
• A TLS-hardened client (minimum TLS 1.2, custom CA pool from service.CABundle PEM) wrapped with OpenTelemetry tracing transport when a CA bundle is provided 8.

Configuration#

APICallConfiguration controls two parameters:

Constructed via NewAPICallConfiguration(maxLen, timeout).

Namespace Scoping for K8s API Calls#

Namespaced policies enforce namespace isolation in Fetch(): if policyNamespace is non-empty, the resolved URLPath must contain a namespace segment matching policyNamespace. Cross-namespace access and cluster-scoped resource access from namespaced policies are both rejected 11.

Result Handling#

After fetching, transformAndStore() either:

• Stores raw JSON directly into the engine context under the entry name (no JMESPath configured), or
• Applies an optional JMESPath filter, marshals the result, and stores it.

If execution fails and a Default value is configured on the ContextAPICall, the default is returned instead of propagating the error 12.

Key Files#