Virtual Registry

Configuration for the Virtual Registry. A registry should have a name and must have a remote, all other parameters are optional.

Example:

virtual_registry:
  registries:
   - name: example
     remotes:
     - url: https://example.com

registries

Type: List

List of virtual registries.

name

virtual_registry:
  registries:
  - name: example

Type: String

Default: default

The registry name should be short, unique, and recognizable. It is used for subdomain routing when there are multiple registries and metrics are segmented on registry name.

default

virtual_registry:
  registries:
  - name: example
    default: true

Type: Boolean

Default: false

If set to true, all requests that don’t match any other registry subdomain will be handled by this registry. Only one registry can be the default registry.

If only one registry is specified, it automatically becomes the default registry.

load_balancer

virtual_registry:
  registries:
  - name: example
    load_balancer: random

Type: String

Default: fallback

The load balancing policy to use when there are multiple remotes.

• fallback: Use remotes in order of appearance. The first remote is selected first, then retries go down through the list.
• random: Balance traffic to remotes evenly. A random remote is selected from the list and retries never pick the same backend twice for a given fetch.
• hash: Pick the same remote for the same cache key. A consistent hashing algorithm is used to select a remote and retries pick new remotes in a consistent order.

auth_ttl

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    auth_ttl: 3600

Type: Number

Default: 3600

The number of seconds to cache each users authorization per artifact. Setting this to 0 causes the users authorization to be checked against the remote registry on every request.

default_ttl

virtual_registry:
  registries:
  - name: example
    default_ttl: 3600

Type: Number

Default: 120

The number of seconds to cache objects that are not otherwise covered by a specific cache policy or considered uncacheable.

Overrides the global varnish.params.default_ttl for this registry.

default_grace

virtual_registry:
  registries:
  - name: example
    default_grace: 3600

Type: Number

Default: 10

The number of seconds to grace objects that are not otherwise covered by a specific cache policy or considered uncacheable.

Overrides the global varnish.params.default_grace for this registry.

default_keep

virtual_registry:
  registries:
  - name: example
    default_keep: 3600

Type: Number

Default: 0

The number of seconds to keep stale objects that are not otherwise covered by a specific cache policy or considered uncacheable.

Overrides the global varnish.params.default_keep for this registry.

manifest_ttl

virtual_registry:
  registries:
  - name: example
    manifest_ttl: 60

Type: Number

TTL in seconds for manifest artifacts (such as an npm packument or a PyPI simple index). By default, mutable manifests are revalidated with the remote on every request; setting manifest_ttl caches them for a fixed window instead. Digest-pinned (immutable) manifests are unaffected.

package_ttl

virtual_registry:
  registries:
  - name: example
    package_ttl: 86400

Type: Number

TTL in seconds for package artifacts. Caps the built-in immutable lifetime of package downloads. Mutable packages that must revalidate are unaffected.

other_ttl

virtual_registry:
  registries:
  - name: example
    other_ttl: 300

Type: Number

TTL in seconds for artifacts that are not classified as a manifest or a package.

extra_vcl

Type: List

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    extra_vcl:
    - /etc/varnish-supervisor/example.vcl

Extra VCL to prepend to the configuration generated by the Virtual Registry. Extra VCLs are included in the order they appear in this list.

base_url

virtual_registry:
  registries:
  - name: example
    base_url: https://my-registry.example.com

Type: String

Base URL of the virtual registry. This is used when the registry needs to generate URLs that point back to itself (e.g., in manifests or redirect responses).

base_url can be set to http:// or https:// without a domain to determine the scheme used for the redirect. This can be useful when the Virtual Registry is placed behind a TLS terminating proxy, especially when preserve_subdomain is enabled for the Virtual Registry remote.

Overrides the global virtual_registry.base_url for this registry.

disable_cache

virtual_registry:
  registries:
  - name: example
    disable_cache: true

Type: Boolean

Default: false

Disable artifact caching for this registry. When enabled, requests are still proxied to the registry’s remotes, but responses are not cached and every request is fetched fresh from the remote. Caching is enabled by default.

readonly

virtual_registry:
  registries:
  - name: example
    readonly: true

Type: Boolean

Default: false

Whether this registry should be treated as read-only. When enabled, write operations (push, delete) are rejected.

enable_firewall

virtual_registry:
  registries:
  - name: example
    enable_firewall: true

Type: Boolean

Default: false

Enable the Artifact Firewall for this registry. When enabled, requests are evaluated against the configured firewall rules. Requires a top-level firewall configuration.

enable_cluster

virtual_registry:
  registries:
  - name: example
    enable_cluster: true

Type: Boolean

Default: false

Enable clustering for this registry. When enabled, cluster-wide request coalescing is enabled for package requests to this Virtual Registry. Requires a top-level cluster configuration.

Only package requests are coalesced between cluster nodes, manifest and preflight auth requests go directly to the remote.

preserve_manifest

virtual_registry:
  registries:
  - name: example
    preserve_manifest: true

Type: Boolean

Default: false

Preserve original manifests from the remote without inserting the base URL. When disabled, the registry rewrites manifest URLs to point through the virtual registry.

cache_req_body_limit

virtual_registry:
  registries:
  - name: example
    cache_req_body_limit: 10MB

Type: String

Default: 10MB

Maximum request body size to buffer for cacheable POST requests (e.g. git-upload-pack). The value is a byte size such as 512KB, 10MB, or 1GB.

routes

virtual_registry:
  registries:
  - name: example
    routes:
    - glob: "*.example.com"

Type: List

Additional routes to associate with this registry. Routes allow matching requests to registries based on the Host header using glob patterns.

glob

virtual_registry:
  registries:
  - name: example
    routes:
    - glob: "*.example.com"

Type: String

Glob pattern to match against the Host header for routing requests to this registry.

remotes

virtual_registry:
  registries:
   - name: example
     remotes:
     - url: https://example.com

Type: List

List of remotes. See remotes configuration.

base_url

virtual_registry:
  base_url: https://my-registry.example.com

Type: String

Default base URL applied to every registry that does not set its own base_url. This is convenient when multiple registries share the same public hostname. A per-registry base_url takes precedence over this value. See the per-registry base_url for how the base URL is used, including scheme-only values.

redirects

virtual_registry:
  redirects:
    enabled: true
    signing:
      enabled: true
      key_env: REDIRECT_SIGNING_KEY

Configuration for the /redirectz endpoint. The Virtual Registry rewrites certain upstream URLs (for example Git LFS objects, Composer dist archives, and signed-blob redirects) so that they route back through itself via /redirectz, where the content can be cached.

enabled

virtual_registry:
  redirects:
    enabled: false

Type: Boolean

Default: true

Enable the /redirectz endpoint. When set to false, the endpoint is closed entirely and clients requesting it receive a 404 response.

signing

virtual_registry:
  redirects:
    signing:
      enabled: true
      key_env: REDIRECT_SIGNING_KEY

HMAC signing of /redirectz URLs. When enabled, the Virtual Registry appends a ;sig=... matrix parameter to the URLs it rewrites, and rejects requests to /redirectz whose signature is missing or invalid. This prevents clients from crafting arbitrary /redirectz URLs.

enabled

virtual_registry:
  redirects:
    signing:
      enabled: true

Type: Boolean

Default: false

Enable HMAC signing of /redirectz URLs.

key_env

virtual_registry:
  redirects:
    signing:
      key_env: REDIRECT_SIGNING_KEY

Type: String

Name of the environment variable that holds the HMAC signing key. Required when signing is enabled.

deny_unknown_hosts

virtual_registry:
  redirects:
    deny_unknown_hosts: true

Type: Boolean

Default: false

Restrict /redirectz upstream hosts and transparent redirect targets to each registry’s configured remotes plus any extra_known_hosts. When enabled, redirects to any other host are refused. When disabled, redirects to arbitrary hosts are followed.

extra_known_hosts

virtual_registry:
  redirects:
    extra_known_hosts:
    - cdn.example.com
    - downloads.example.org

Type: List

Additional hosts to allow /redirectz and transparent redirects to fetch from, beyond each registry’s configured remotes. Has no effect unless deny_unknown_hosts is enabled.