Configuration reference¶

This page contains the field reference for incus-apply resource documents.

Common fields¶

Field	Type	Description
`kind`	string	Required resource kind.
`name`	string	Required resource name. May include a remote prefix.
`config`	map	Resource configuration options.
`devices`	map	Device configurations.
`description`	string	Resource description.

Remotes¶

Incus supports named remote servers. By default, incus-apply targets whichever remote is configured as the default in the incus CLI.

Apply an entire run to a remote by passing the remote name with a trailing colon as the last positional argument:

incus-apply instance.yaml server-a:

Override the remote per resource by prefixing the resource name:

kind: instance
name: server-a:ubuntu
image: images:ubuntu/24.04

The per-resource prefix takes precedence over a CLI-level remote target.

Project¶

All resources are applied to an Incus project. By default, incus-apply uses the project configured for the incus CLI. Override it for a run with:

incus-apply . --project myproject

Instance fields¶

Field	Type	Description
`image`	string	Image to use, for example `images:debian/12`.
`vm`	bool	Create a VM instead of a container.
`empty`	bool	Create an empty instance.
`ephemeral`	bool	Create an ephemeral instance deleted when it stops.
`profiles`	list	Profiles to apply.
`storage`	string	Storage pool for the root disk.
`network`	string	Network to attach.
`target`	string	Cluster member target.
`apply.after`	list	Same-project instance names that must be applied first.

Cloud-init¶

When an instance defines config."cloud-init.vendor-data" or config."cloud-init.user-data", incus-apply waits for cloud-init to finish after creating the instance. For VMs, it first waits for the Incus agent.

Cloud-init values can be written either as a block scalar string or as an inline YAML mapping.

Block scalar form¶

config:
  cloud-init.user-data: |
    #cloud-config
    packages:
      - caddy

Inline YAML mapping form¶

config:
  cloud-init.user-data:
    #cloud-config
    packages:
      - caddy
    runcmd:
      - systemctl enable caddy

Complete instance example¶

kind: instance
name: web
image: images:debian/12
config:
  cloud-init.user-data:
    #cloud-config
    package_update: true
    packages:
      - caddy
    write_files:
      - path: /etc/caddy/Caddyfile
        content: |
          :80 {
            root * /var/www/html
            file_server
          }
    runcmd:
      - systemctl enable caddy
      - systemctl restart caddy

Storage pool fields¶

Field	Type	Description
`driver`	string	Storage driver such as `dir`, `zfs`, `btrfs`, `lvm`, or `ceph`.
`source`	string	Source path or device.

Storage volume and bucket fields¶

Field	Type	Description
`pool`	string	Required storage pool name.
`type`	string	Storage content type passed as `--type`, such as `block` or `filesystem`.

Storage bucket key fields¶

Storage bucket keys are S3 credentials that grant access to a storage bucket.

Field	Type	Description
`pool`	string	Required storage pool name.
`bucket`	string	Required parent bucket name.
`role`	string	`admin` for full access or `read-only` for list and get access.

---
kind: storage-bucket
name: assets
pool: default
config:
  size: 10GiB
description: S3-compatible object storage bucket
---
kind: storage-bucket-key
name: app-key
bucket: assets
pool: default
role: read-only
description: Read-only S3 credentials for the application

To use storage buckets on local storage pools such as dir, btrfs, lvm, or zfs, configure an S3 listen address first:

incus config set core.storage_buckets_address :8555

Network fields¶

Field	Type	Description
`networkType`	string	Network type, such as `bridge`, `ovn`, `macvlan`, `sriov`, or `physical`.

Network forward fields¶

For kind: network-forward, listen_address is the external address and network selects the parent network.

Field	Type	Description
`listen_address`	string	Required external listen address.
`network`	string	Required parent network name.
`ports`	list	Optional port forwarding rules in the same shape as `incus network forward edit`.

Use config.target_address to define the default target for unmatched traffic.

kind: network-forward
listen_address: 198.51.100.10
network: public
description: Shared external IP for web services
config:
  target_address: 10.42.0.10
ports:
  - protocol: tcp
    listen_port: "80"
    target_address: 10.42.0.11
    target_port: "8080"
  - protocol: tcp
    listen_port: "443"
    target_address: 10.42.0.12
    target_port: "8443"

Network ACL fields¶

Field	Type	Description
`ingress`	list	Ingress firewall rules.
`egress`	list	Egress firewall rules.

Variables¶

Variables are declared with a kind: vars document and referenced from resource documents with $VAR or ${VAR}.

---
kind: vars
vars:
  DB_NAME: myapp
  DB_USER: appuser
  DB_PASS: ${MYSQL_PASSWORD}
---
kind: instance
name: db
image: docker:mysql
config:
  environment.MYSQL_DATABASE: $DB_NAME
  environment.MYSQL_USER: $DB_USER
  environment.MYSQL_PASSWORD: $DB_PASS

Scoping¶

Variables are file-scoped by default.
Use global: true in a vars document to share variables across files.
File-scoped variables override global variables with the same name.

Shell environment¶

Shell environment variables can be referenced only inside the vars document.
Resource documents expand only variables declared through kind: vars.