Using a custom registry

By default, the boe CLI fetches extensions from the public registry at ghcr.io/tetratelabs/built-on-envoy. In corporate or air-gapped environments you may need to host extensions in an internal OCI registry instead. This guide explains how to configure boe to use a custom registry and how to publish extensions to it.

Configuring the CLI

Point boe to your internal registry by setting the BOE_REGISTRY environment variable. All commands that interact with the registry (run, gen-config) will use it automatically:

export BOE_REGISTRY=registry.internal.example.com/envoy-extensions

If the registry requires authentication, provide credentials via environment variables:

export BOE_REGISTRY_USERNAME=my-user
export BOE_REGISTRY_PASSWORD=my-token

You can also pass these values as CLI flags:

boe run --registry registry.internal.example.com/envoy-extensions \
        --username my-user \
        --password my-token \
        ...

Insecure (HTTP) registries

If the registry does not support TLS (for example, a local development registry), enable insecure mode:

export BOE_REGISTRY_INSECURE=true

Or with the --insecure flag:

boe run --registry localhost:5000/extensions --insecure --extension example-go

Publishing extensions to a custom registry

Extensions are packaged as standard OCI artifacts, so any OCI-compliant registry can host them.

The extension scaffolding generates Makefiles that automate building and pushing extension artifacts. Set the BOE_REGISTRY variable when invoking make to target your registry.

export BOE_REGISTRY=registry.internal.example.com/envoy-extensions
export BOE_REGISTRY_INSECURE=true    # If pushing to an insecure registry

Once the environment variable is set, you cn invoke your extension Makefile targets to generate and push the extension artifacts:

make push_image   # Push the extension image
make push_code    # Push the extension source code

Environment variables reference

See the full list in the Environment Variables reference.