HTTP Client Configuration

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 all retry attempts and their backoff waits — it is not reset between retries. Pick timeout large enough to cover the worst-case retry chain: timeout ≥ slowestAttempt × (maxRetries + 1) + maxWait × maxRetries.

maxRetries Semantics#

maxRetries counts attempts after the initial request:

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: SSL_CERT_FILE and SSL_CERT_DIR#

insecureSkipVerify is the only TLS field in this config type. To trust a private CA without disabling verification, use the SSL_CERT_FILE / SSL_CERT_DIR environment variables — they are replacements for the built-in system CA path lists in Go’s crypto/x509 loader, not additions. See TLS and Custom CA.

Related Documentation#

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