Skip to content

Create a new container.

Usage

$ klee container create [OPTIONS] IMAGE [COMMAND]...

Refer to the options section for an overview of available OPTIONS for this command.

Description

klee container create (or shorthand: klee create) command creates a new container from the specified image, without starting it.

When creating a container, Kleened creates a ZFS dataset based on the image and prepares it for running the specified command. If no command is specified, Kleened uses the CMD specified in the image. The container ID is then printed to STDOUT.

Specifying IMAGE

The IMAGE argument takes the following two forms:

  • IMAGE_ID[@SNAPSHOT_ID]
  • IMAGE_NAME>[:TAG][@<SNAPSHOT_ID>]

If TAG is omitted latest is assumed. For example,

  • FreeBSD means the image FreeBSD with tag latest
  • FreeBSD:13.2-STABLE means the image FreeBSD with tag 13.2-STABLE
  • FreeBSD:base@6b3c821605d4 means the FreeBSD:base image but create the container from the snapshot 6b3c821605d4
  • 48fa55889b0f use the image having ID 48fa55889b0f
  • 48fa55889b0f@2028818d6f06 use the image as above but create the container from the snapshot 2028818d6f06

For more information about snapshots see the Build snapshots section.

Specifying mounts

When creating containers volumes/directories/files can be mounted into the container using one or more --mount/-m MOUNT options. MOUNT must use the following syntax:

SOURCE:DESTINATION[:rw|ro]

where

  • SOURCE can be either a volume name or an absolute path on the host system. If SOURCE starts with '/' it is interpreted as a host path. If a volume name is specified, and the volume does not exist, it will be created.
  • DESTINATION is the path of the mount within the container. If it does not exist it will be created.
  • Optionally, if the mount is postfixed with :ro or :rw the mount will be read-only or read-write, respectively. If omitted, :rw is assumed.

For example:

  • klee container create -m logs:/var/log ... mount a volume named logs into the container at /var/log.
  • klee container create -m my_archive:/archive:ro ... create a read-only archive mountpoint in the container root for the my_archive volume.
  • klee container create -m /home/some_user:/home/some_user ... mount the host directory /home/some_user into the same path within the container.

Specifying jail parameters

See the jail parameter section in the handbook.

Starting the container

Use klee container start (or shorthand: klee start) command to start the container. Combinining klee container create and klee container start is equivalent to klee container run.

The klee create command shares most of its options with klee run. Refer to the klee container run command section for details on the available flags and options.

Limiting ressources of containers

It is not possible to handle ressource contraints in Kleene atm. However, FreeBSD does support ressource limiting of jails/containers using rctl(8) which can be done manually until it is integrated into Kleene. See the rctl(8) manual pages for details.

For example uses of this command, refer to the examples section below.

Options

Name, shorthand Description
--user, -u Default user that run commands in the container. This parameter will be overwritten by the jail parameter exec.jail_user if it is set.
--env, -e Set environment variables (e.g. --env FIRST=SomeValue --env SECOND=AnotherValue)
--mount, -m Mount a volume/directory/file on the host filesystem into the container. Mounts are specfied by --mount SOURCE:DESTINATION[:rw\|ro].
--jailparam, -J Set jail parameters. Replace defaults (such as 'mount.devfs', 'exec.clean', etc.) by specifying alternative values. See docs for details.
--persist, -P Do not remove this container when pruning
--restart Restarting policy of the container. Set to 'no' for no automatic restart of the container. Set to 'on-startup' to start the container each time Kleened is. [default: no]
--driver, -l Network driver of the container. Possible values: 'ipnet', 'host', 'vnet', and 'disabled'. If no network and no driver is supplied, the network driver is set to 'host'. If a network is set but no driver, it is set to 'ipnet'.
--network, -n Connect container to a network.
--ip IPv4 address used for the container. If omitted, an unused ip is allocated from the IPv4 subnet of network.
--ip6 IPv6 address used for the container. If omitted, an unused ip is allocated from the IPv6 subnet of network.
--publish, -p Publish ports using the syntax HOST_PORT[:CONTAINER_PORT][/PROTOCOL] or INTERFACE:HOST_PORT:CONTAINER_PORT[/PROTOCOL]. CONTAINER_PORT defaults to HOST_PORT and PROTOCOL defaults to 'tcp'.
--name Assign a name to the container
--help Show this message and exit.

Examples

More examples available at the klee container run command documentation.

Create and start a container

The following example creates an interactive container with a pseudo-TTY attached, then starts the container and attaches to it:

$ klee container create --name mycontainer hello-world:latest
4d9d4e72a07f

$ klee container start -it mycontainer
created execution instance 71c359af03f7
Hello World

executable 71c359af03f7 and its container exited with exit-code 0

The above is the equivalent of a klee run:

$ klee container run -it --name mycontainer hello-world:latest
6e33dbacde70
created execution instance 4eb13ad4c3a4
Hello World

executable 4eb13ad4c3a4 and its container exited with exit-code 0

Initialize volumes

Container volumes can be automatically created during the klee container create phase:

$ klee container create -v /data --name storage FreeBSD13.2-STABLE
5f8e437e5c95

$ klee volume ls
 VOLUME NAME    CREATED
──────────────────────────────
 6dedc1df7b42   10 secondsago

Parent command

Command Description
klee container