HTTP Client

This page is the technical reference for OCM HTTP client configuration. For a task-oriented walkthrough, see the Configure HTTP Client Behaviour how-to guides.

Configuration Type#

HTTP client behaviour is controlled by the http.config.ocm.software/v1alpha1 configuration type, embedded in the standard OCM configuration file:

type: generic.config.ocm.software/v1
configurations:
  - type: http.config.ocm.software/v1alpha1
    timeout: 30s
    retry:
      maxRetries: 5

By default the CLI looks for configuration in $HOME/.ocmconfig. Pass --config <file> to use a different file.

Schema#

The schema below defines the full structure of the http.config.ocm.software/v1alpha1 type as specified by JSON Schema 2020-12.

Notes#

Default Values#

All fields are optional. When omitted, OCM applies these defaults:

Duration Format#

All duration fields accept Go’s time.ParseDuration syntax: 300ms, 10s, 5m, 1h30m. Zero (0s) disables the limit. Negative values are only accepted for tcpKeepAlive (disables keep-alive probes); all other fields reject negative values.

timeout and Retries#

timeout covers the entire HTTP request, including retry attempts, their backoff waits, and the response body. It defaults to 0s, allowing large response bodies to stream to completion regardless of duration. When configured with a positive value, it is not reset between retries. Pick a value large enough to cover the worst-case retry chain: timeout ≥ slowestAttempt × (maxRetries + 1) + maxWait × maxRetries.

maxRetries Semantics#

maxRetries counts attempts after the initial request:

Retries cover 5xx, 429, 408, network timeouts, connection resets, unexpected EOF, and lost HTTP/2 connections or streams. A request with a body is retried only when the body can be rewound; seekable bodies such as file-backed blobs are rewound automatically. A failure after the response started streaming cannot be retried by the client; ocm transfer retries the whole affected step up to three times instead.

HTTP/2#

OCM negotiates HTTP/2 with TLS servers that offer it. HTTP/2 multiplexes every concurrent request to a host over a single connection, which OCM health-checks with pings (after 30s without frames, closed if unanswered within 15s). A lost connection therefore fails every transfer in flight to that host at once. Set disableHTTP2: true, globally or per host, to use HTTP/1.1, where each concurrent request has its own connection:

type: generic.config.ocm.software/v1
configurations:
  - type: http.config.ocm.software/v1alpha1
    hosts:
      ghcr.io:
        disableHTTP2: true

Plain HTTP#

OCM talks HTTPS to every OCI registry. plainHTTP: true makes OCM’s OCI registry clients use cleartext HTTP for a host. It is meant for development and air-gapped registries without TLS. Traffic, including credentials, is unencrypted, so set it per host and never for a public registry. OCM logs a warning each time it opens a repository, pings a registry, or downloads a Helm chart on a plain HTTP host.

This setting alone decides the connection. A scheme prefix on a repository base URL or a reference is deprecated and only checked against it: http:// on a host that is not plainHTTP is an error, https:// on a plainHTTP host warns about the downgrade, and every prefix logs a deprecation warning. See Migrate from http:// Prefixes.

type: generic.config.ocm.software/v1
configurations:
  - type: http.config.ocm.software/v1alpha1
    hosts:
      "registry.local:5000":
        plainHTTP: true

plainHTTP covers OCM’s OCI repositories, ociArtifact access, and Helm chart downloads. A chart at an oci:// URL follows the setting for its registry host. A classic Helm repository URL keeps its scheme as part of the address: an http:// URL is accepted only when its host is plainHTTP, and an https:// URL stays HTTPS.

Per-Host Merge Semantics#

When multiple http.config.ocm.software/v1alpha1 blocks appear in the same or layered config files, they are merged field by field — the last non-nil value wins. Host entries are merged map-key by map-key; the last entry for a given key wins. Per-host fields are then merged on top of the resolved global values using the same rule.

Host Key Matching#

The hosts map key is matched against request.URL.Host by exact string: first hostname:port, then bare hostname. Go strips the default port (:443 for HTTPS, :80 for HTTP) from URLs before matching, so use bare hostnames for default-port registries and hostname:port only for non-standard ports. Keys must be lowercase — Go normalises URL hostnames.

Proxy#

Proxy configuration is not a field in this type. OCM inherits Go’s standard http.ProxyFromEnvironment — set HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables. See Route Traffic Through a Proxy.

TLS Trust: Custom Root CAs#

To trust a private CA without disabling verification, set rootCAsPEM (inline PEM bundle) or rootCAsPEMFile (path) — globally or per host (these TLS fields are top-level, inlined alongside insecureSkipVerify). These certificates are appended to the system trust pool, so publicly-issued servers keep verifying. This is the recommended way to reach a self-hosted OCI registry, Helm repository, or RFC 3161 timestamping server presenting an internal certificate. rootCAsPEM takes precedence over rootCAsPEMFile; both are ignored when insecureSkipVerify is true. An invalid or unreadable bundle fails requests closed rather than silently falling back to system trust.

type: generic.config.ocm.software/v1
configurations:
  - type: http.config.ocm.software/v1alpha1
    hosts:
      timestamp.internal:8443:
        rootCAsPEMFile: /etc/ocm/internal-ca.pem

Alternatively, Go’s SSL_CERT_FILE / SSL_CERT_DIR environment variables replace (not extend) the built-in system CA path lists in crypto/x509. Prefer rootCAsPEM for additive, per-host trust. See TLS and Custom CA.

Related Documentation#

• Guides: Configure HTTP Client Behaviour - task-oriented how-to guides
• Guides: Configure Credentials for Multiple Registries - pairing HTTP config with credential setup
• Reference: Resolver Configuration - reference for resolver config in the same file