Skip to main content

Environment Config File

Instead of passing every flag on the command line, you can supply environment creation options through a YAML config file. Overlock supports both a single explicit config file and layered automatic discovery.

File Discovery (Layered Loading)​

When no --config flag is provided, Overlock automatically looks for config files in the current directory and merges them in the following order (later files override earlier ones):

  1. overlock.yaml
  2. .overlock.yaml
  3. .overlock.*.yaml — any files matching this glob, loaded in alphabetical order (e.g. .overlock.dev.yaml, .overlock.ci.yaml)

This layered approach lets you keep a base config in overlock.yaml and override specific values per environment or context in additional files.

Explicit Config File​

To use a specific file, pass the --config flag:

overlock env create my-env --config ./my-config.yaml

If the file is not found at the given path, Overlock exits with an error. If the file exists but cannot be parsed, Overlock logs a message and points you to this page.

File Format​

The config file is a YAML document. All fields are optional — only set the ones you want to override.

engine: kind
http_port: 80
https_port: 443
context: ""
engine_config: ""
mount: []
providers: []
configurations: []
functions: []
create_admin_service_account: false
admin_service_account_name: ""
cpu: ""
max_reconcile_rate: 1

Field Reference​

FieldTypeDefaultDescription
enginestringkindKubernetes engine to use: kind, k3s, k3d, k3s-docker
http_portint80Host port to map for HTTP traffic
https_portint443Host port to map for HTTPS traffic
contextstring—Kubernetes context name to create or use
engine_configstring—Path to an engine-specific config file (e.g. a KinD config YAML)
mountlist of strings—Bind mounts in host:container format, e.g. /data:/storage
providerslist of strings—Providers to install at creation time
configurationslist of strings—Configurations to install at creation time
functionslist of strings—Functions to install at creation time
create_admin_service_accountboolfalseCreate a cluster-admin service account
admin_service_account_namestringoverlock-adminName for the admin service account
cpustring—CPU limit for k3s-docker container nodes (e.g. 2, 0.5, 50%)
max_reconcile_rateint1Max concurrent reconciliations for Crossplane

Examples​

Minimal config​

engine: k3s-docker
max_reconcile_rate: 5

Pre-installing packages​

engine: kind
configurations:
  - xpkg.upbound.io/devops-toolkit/dot-application:v3.0.31
providers:
  - xpkg.upbound.io/crossplane-contrib/provider-helm:v0.19.0

Layered config workflow​

Keep a base file checked into your project:

# overlock.yaml
engine: kind
max_reconcile_rate: 1

Add a local override that you .gitignore:

# .overlock.local.yaml
max_reconcile_rate: 10
http_port: 8080
https_port: 8443

Overlock merges both files, with .overlock.local.yaml taking precedence.