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 list#

List of virtual registries.

name string#

virtual_registry:
  registries:
  - name: example

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 boolean#

virtual_registry:
  registries:
  - name: example
    default: true

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 string#

virtual_registry:
  registries:
  - name: example
    load_balancer: random

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 number#

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    auth_ttl: 3600

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 number#

virtual_registry:
  registries:
  - name: example
    default_ttl: 3600

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 number#

virtual_registry:
  registries:
  - name: example
    default_grace: 3600

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 number#

virtual_registry:
  registries:
  - name: example
    default_keep: 3600

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.

extra_vcl 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 string#

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

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 boolean#

virtual_registry:
  registries:
  - name: example
    disable_cache: true

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 boolean#

virtual_registry:
  registries:
  - name: example
    readonly: true

Default: false

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

enable_firewall boolean#

virtual_registry:
  registries:
  - name: example
    enable_firewall: true

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 boolean#

virtual_registry:
  registries:
  - name: example
    enable_cluster: true

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 boolean#

virtual_registry:
  registries:
  - name: example
    preserve_manifest: true

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 string#

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

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 list#

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

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

glob string#

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

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

remotes list#

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

List of remotes. See remotes configuration.

base_url string#

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

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 boolean#

virtual_registry:
  redirects:
    enabled: false

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 boolean#

virtual_registry:
  redirects:
    signing:
      enabled: true

Default: false

Enable HMAC signing of /redirectz URLs.

key_env string#

virtual_registry:
  redirects:
    signing:
      key_env: REDIRECT_SIGNING_KEY

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