Enabling caching proxy for builds

Konflux supports HTTP proxy caching to improve build performance. When enabled, container build operations can use a Squid HTTP proxy to cache layers, reducing build times for subsequent builds.

Prerequisites

The caching proxy requires Squid to be installed on the cluster. Cluster administrators can install Squid using the Helm chart from the caching repository.

How it works

The caching proxy feature uses two levels of configuration:

  • Pipeline level: The enable-cache-proxy parameter controls whether a specific pipeline uses the caching proxy.

  • Cluster level: A cluster-config ConfigMap in the konflux-info namespace provides the proxy configuration and can disable proxy usage cluster-wide.

The pipeline’s init task reads the configuration and emits HTTP_PROXY and NO_PROXY values to be used by the buildah task.

Enabling the caching proxy

The caching proxy is disabled by default. To enable the caching proxy for a component’s build pipeline, set the enable-cache-proxy pipeline parameter to true.

Procedure

  1. In the PipelineRun YAML files in the .tekton directory, set the enable-cache-proxy parameter to true in the spec.params section:

    spec:
  params:
  - name: enable-cache-proxy
    value: "true"

  2. Commit your changes to the repository of the component.

Cluster-level configuration

The caching proxy behavior can be configured at the cluster level using a ConfigMap named cluster-config in the konflux-info namespace. This ConfigMap is globally readable from all namespaces in the cluster, but writable only by the infrastructure team.

The ConfigMap supports the following keys:

allow-cache-proxy

When set to false, disables the caching proxy for all pipelines in the cluster, regardless of individual pipeline settings. When set to true or unset, pipelines can use the proxy if they have enable-cache-proxy set to true.

data:
  allow-cache-proxy: "true"
http-proxy

The HTTP proxy URL to use for builds. If not set, defaults to squid.caching.svc.cluster.local:3128.

data:
  http-proxy: "squid.caching.svc.cluster.local:3128"
no-proxy

A comma-separated list of hosts that should bypass the proxy. If not set, the init task uses a default list of common container registries.

data:
  no-proxy: "quay.io,registry.redhat.io,docker.io"
Example cluster-config ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-config
  namespace: konflux-info
data:
  allow-cache-proxy: "true"
  http-proxy: "squid.caching.svc.cluster.local:3128"
  no-proxy: "quay.io,registry.redhat.io,docker.io"

Configuration precedence

The caching proxy is enabled only when both of the following conditions are met:

  1. The pipeline parameter enable-cache-proxy is set to true.

  2. The cluster-level allow-cache-proxy is either set to true or is unset.

If allow-cache-proxy is explicitly set to false at the cluster level, the proxy is disabled for all pipelines, even if individual pipelines have enable-cache-proxy set to true.

Supported registries

The caching proxy supports the following container image registries:

  • quay.io and other registry proxies that use it as a backend (for example, registry.access.redhat.com and registry.redhat.io)

  • docker.io

  • nvcr.io

  • registry.fedoraproject.org

The following registry hosts are not supported at this time:

  • gcr.io

  • *.pkg.dev

Logging

The init task logs the proxy configuration applied to the pipeline run and the reasoning for the applied settings. You can view these logs in the pipeline run’s init task output.

Example log output when cache proxy is enabled
Fetching cluster-config from konflux-info namespace...
Cache proxy enabled (cluster-enabled: true, task-enable: true)
Setting HTTP_PROXY to squid.caching.svc.cluster.local:3128
Setting NO_PROXY to quay.io,registry.redhat.io,docker.io
Example log output when cache proxy is disabled
Fetching cluster-config from konflux-info namespace...
Cache proxy disabled (cluster-enabled: true, task-enable: false)
Setting HTTP_PROXY to
Setting NO_PROXY to

If the cluster-config ConfigMap is not found, the init task logs a warning and proceeds with default values:

Warning: Failed to fetch cluster-config ConfigMap. Proceeding with defaults.

Troubleshooting

If the caching proxy is not working after setting enable-cache-proxy to true, your pipeline YAML may be missing required configuration. The proxy feature requires a complete chain of parameter passing:

  1. The enable-cache-proxy pipeline parameter must be defined in the pipeline’s params section.

  2. The init task must receive the enable-cache-proxy parameter.

  3. The init task outputs http-proxy and no-proxy results.

  4. The buildah task (or variant) must receive HTTP_PROXY and NO_PROXY parameters that reference the init task results.

If any part of this chain is missing, the proxy will not work. MintMaker automatically applies these configurations through task migrations.

Checking for missing configuration

Procedure

  1. Check your repository for any unmerged MintMaker pull requests that update the pipeline configuration.

  2. Merge any unmerged MintMaker PRs. The migration adds all required parameters automatically.

  3. If no MintMaker PR exists, manually add the missing configuration to your pipeline YAML:

    1. Add the pipeline parameter enable-cache-proxy:

      spec:
  pipelineSpec:
    params:
      - name: enable-cache-proxy
        default: "false"
        description: Enable cache proxy configuration
        type: string

    2. Add the enable-cache-proxy parameter to the init task:

      tasks:
  - name: init
    params:
      - name: enable-cache-proxy
        value: $(params.enable-cache-proxy)
    taskRef:
      name: init
      version: "0.2"

    3. Add the HTTP_PROXY and NO_PROXY parameters to the buildah task (or variant like buildah-remote, buildah-oci-ta) to receive proxy values from the init task results:

      - name: build-container
  params:
    - name: HTTP_PROXY
      value: $(tasks.init.results.http-proxy)
    - name: NO_PROXY
      value: $(tasks.init.results.no-proxy)
    # ... other params
  taskRef:
    name: buildah

  4. Verify that the caching proxy is working by checking the init and buildah task logs for the proxy configuration messages.

Verifying proxy configuration in logs

After enabling the caching proxy, check the task logs to confirm the configuration is applied correctly.

Example init task log output when cache proxy is enabled
Fetching cluster-config from konflux-info namespace...
Cache proxy enabled (cluster-enabled: true, task-enable: true)
Setting HTTP_PROXY to squid.caching.svc.cluster.local:3128
Setting NO_PROXY to quay.io,registry.redhat.io,docker.io
Example buildah task log output when cache proxy is enabled
[2026-01-27T10:15:30.123456789+00:00] Setting proxy to squid.caching.svc.cluster.local:3128
[2026-01-27T10:15:30.123456789+00:00] Bypassing proxy for quay.io,registry.redhat.io,docker.io
Example init task log output when cache proxy is disabled
Fetching cluster-config from konflux-info namespace...
Cache proxy disabled (cluster-enabled: true, task-enable: false)
Setting HTTP_PROXY to
Setting NO_PROXY to

If you see only "Unsetting proxy" messages without the preceding "Setting proxy" messages in the buildah task logs, the HTTP_PROXY and NO_PROXY parameters may not be correctly wired from the init task results.