Incus profiles and projects: industrialise and compartmentalise

Read this page in French

Two Incus mechanisms take you from "a few instances by hand" to an industrialised setup. Profiles are reusable configuration sets (resources, network, storage) applied to several instances. Projects compartmentalise sets of instances, images and networks, like separate spaces on one server. This guide shows how to create them, combine them and use them. Tested on Incus 7.0. For anyone managing more than a handful of containers.

What you will learn

• Create and apply a configuration profile.
• Combine several profiles on an instance.
• Compartmentalise with projects.
• Choose between a profile and a project.

Profiles: a reusable configuration

A profile gathers settings (CPU and memory limits, network and disk devices) that apply to several instances at once. Every instance uses at least the default profile:

incus profile list

+---------+-----------------------+---------+
|  NAME   |      DESCRIPTION      | USED BY |
+---------+-----------------------+---------+
| default | Default Incus profile | 3       |
+---------+-----------------------+---------+

You create a profile and define configuration in it:

incus profile create web
incus profile set web limits.memory=1GiB
incus profile show web
# name: web
# config:
#   limits.memory: 1GiB

Applying and combining profiles

A profile applies at launch, or is added to an existing instance. Above all, profiles stack: Incus applies them in order, and the last one wins on conflict.

# at creation, combining default and web
incus launch images:debian/13 srv -p default -p web

# on an existing instance
incus profile add srv web

That is the key to industrialising: a base profile (network, SSH keys), a web profile (resources), a monitoring profile (agent), assembled by role without repeating configuration.

Projects: compartmentalising one server

A project is an isolated space: its instances, images, profiles and networks are its own and do not interfere with the others. It is the multi-tenant unit of Incus.

incus project list
# | default (current) | ... | Default Incus project |

incus project create test-proj

You switch between projects, or target one for the duration of a command:

incus project switch test-proj      # change the current project
incus --project test-proj list      # one command inside a project

Every project starts empty: instances created inside it do not show in default, and the reverse holds too. Ideal for separating environments (dev, prod), clients or teams on a single server.

Profile or project: which one

The two answer different needs, and they combine.

Need	Tool
Reuse a configuration (resources, devices)	profile
Isolate sets of instances and networks	project
Instance roles (web, db, monitoring)	stacked profiles
Separate environments or clients	projects

Glissez pour voir

In practice: projects carve the server into spaces, and inside each project profiles industrialise the instance configuration. That same mechanism, pushed further with quotas and scoped credentials, is what turns a cluster into a multi-tenant private cloud.

Key points

• A profile is a reusable configuration; every instance uses at least default.
• Profiles stack (-p base -p web), the last one wins: you compose by role.
• A project is a compartmentalised space (its own instances, images, networks).
• You switch with incus project switch or target with --project.
• Profiles for configuration, projects for isolation: the two combine.

FAQ: common questions about Incus profiles and projects

What is an Incus profile?

A profile is a reusable set of configuration (CPU and memory limits, network and disk devices) applied to several instances. Every instance uses at least the default profile.

How do you combine several profiles on an Incus instance?

You pass several -p options at launch, for example incus launch images:debian/13 srv -p default -p web. Incus applies the profiles in order, and the last one wins on conflict.

What is an Incus project?

A project is a compartmentalised space on a single Incus server: its instances, images, profiles and networks are its own and do not interfere with other projects. It is the multi-tenant unit of Incus. You create one with incus project create and switch with incus project switch.

Incus profile or project: which one should you use?

A profile is for reusing configuration (resources, devices) across several instances. A project is for isolating sets of instances, images and networks.

Next steps

• Terraform provider: version profiles and projects as code instead of recreating them by hand on every server.
• Ansible connection plugin: populate the inside of instances launched from your profiles, without SSH.
• Securing Incus: turn an ordinary project into a restricted one that forbids privileged containers.

×

📖 Voir la documentation →