salt.modules.nspawn
Manage nspawn containers
New in version 2015.8.0.
systemd-nspawn(1) is a tool used to manage lightweight namespace containers. This execution module provides several functions to help manage these containers.
Minions running systemd >= 219 will place new containers in /var/lib/machines
, while those running systemd < 219 will place them in /var/lib/container
.
-
Bootstrap a container from package servers, if dist is None the os the minion is running as will be created, otherwise the needed bootstrapping tools will need to be available on the host.
CLI Example:
salt myminion nspawn.bootstrap_container <name>
salt.modules.nspawn.bootstrap_container(name, dist=None, version=None)
-
Bootstrap a container from package servers, if dist is None the os the minion is running as will be created, otherwise the needed bootstrapping tools will need to be available on the host.
CLI Example:
salt '*' nspawn.bootstrap_salt arch1
salt.modules.nspawn.bootstrap_salt(name, config=None, approve_key=True, install=True, pub_key=None, priv_key=None, bootstrap_url=None, force_install=False, unconditional_install=False, bootstrap_delay=None, bootstrap_args=None, bootstrap_shell=None)
-
Copy a file from the host into a container
- name
-
Container name
- source
-
File to be copied to the container
- dest
-
Destination on the container. Must be an absolute path.
- overwriteFalse
-
Unless this option is set to
True
, then if a file exists at the location specified by thedest
argument, an error will be raised.
makedirs : False
Create the parent directory on the container if it does not already exist.
CLI Example:
salt 'minion' nspawn.copy_to /tmp/foo /root/foo
salt.modules.nspawn.copy_to(name, source, dest, overwrite=False, makedirs=False)
-
Set the named container to not be launched at boot
CLI Example:
salt myminion nspawn.enable <name>
salt.modules.nspawn.disable(name)
-
Set the named container to be launched at boot
CLI Example:
salt myminion nspawn.enable <name>
salt.modules.nspawn.enable(name)
-
Returns true if the named container exists
CLI Example:
salt myminion nspawn.exists <name>
salt.modules.nspawn.exists(name)
-
Return info about a container
Note
The container must be running for
machinectl
to gather information about it. If the container is stopped, then this function will start it.- startFalse
-
If
True
, then the container will be started to retrieve the info. AStarted
key will be in the return data if the container was started.
CLI Example:
salt myminion nspawn.info arch1 salt myminion nspawn.info arch1 force_start=False
salt.modules.nspawn.info(name, **kwargs)
-
Lists all nspawn containers
CLI Example:
salt myminion nspawn.list_all
salt.modules.nspawn.list_all()
-
Lists running nspawn containers
Note
nspawn.list
also works to list running containersCLI Example:
salt myminion nspawn.list_running salt myminion nspawn.list
salt.modules.nspawn.list_running()
-
Lists stopped nspawn containers
CLI Example:
salt myminion nspawn.list_stopped
salt.modules.nspawn.list_stopped()
-
Returns the PID of a container
- name
-
Container name
CLI Example:
salt myminion nspawn.pid arch1
salt.modules.nspawn.pid(name)
-
Issue a clean shutdown to the container. Equivalent to running
machinectl poweroff
on the named container.For convenience, running
nspawn.stop``(as shown in the CLI examples below) is equivalent to running ``nspawn.poweroff
.Note
machinectl poweroff
is only supported in systemd >= 219. On earlier systemd versions, running this function will simply issue a clean shutdown viasystemctl
.CLI Examples:
salt myminion nspawn.poweroff arch1 salt myminion nspawn.stop arch1
salt.modules.nspawn.poweroff(name)
-
Execute a
machinectl pull-dkr
to download a docker image and add it to /var/lib/machines as a new container.Note
Requires systemd >= 219
- url
-
URL from which to download the container
- name
-
Name for the new container
- index
-
URL of the Docker index server from which to pull (must be an
http://
orhttps://
URL).
CLI Examples:
salt myminion nspawn.pull_dkr centos/centos6 cent6 index=https://get.docker.com salt myminion nspawn.pull_docker centos/centos6 cent6 index=https://get.docker.com
salt.modules.nspawn.pull_dkr(url, name, index)
-
Execute a
machinectl pull-raw
to download a .qcow2 or raw disk image, and add it to /var/lib/machines as a new container.Note
Requires systemd >= 219
- url
-
URL from which to download the container
- name
-
Name for the new container
- verifyFalse
-
Perform signature or checksum verification on the container. See the
machinectl(1)
man page (section titled "Image Transfer Commands") for more information on requirements for image verification. To perform signature verification, useverify=signature
. For checksum verification, useverify=checksum
. By default, no verification will be performed.
CLI Examples:
salt myminion nspawn.pull_raw http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz fedora21
salt.modules.nspawn.pull_raw(url, name, verify=False)
-
Execute a
machinectl pull-raw
to download a .tar container image, and add it to /var/lib/machines as a new container.Note
Requires systemd >= 219
- url
-
URL from which to download the container
- name
-
Name for the new container
- verifyFalse
-
Perform signature or checksum verification on the container. See the
machinectl(1)
man page (section titled "Image Transfer Commands") for more information on requirements for image verification. To perform signature verification, useverify=signature
. For checksum verification, useverify=checksum
. By default, no verification will be performed.
CLI Examples:
salt myminion nspawn.pull_tar http://foo.domain.tld/containers/archlinux-2015.02.01.tar.gz arch2
salt.modules.nspawn.pull_tar(url, name, verify=False)
-
Reboot the container by sending a SIGINT to its init process. Equivalent to running
machinectl reboot
on the named container.For convenience, running
nspawn.restart
(as shown in the CLI examples below) is equivalent to runningnspawn.reboot
.Note
machinectl reboot
is only supported in systemd >= 219. On earlier systemd versions, running this function will instead restart the container viasystemctl
.CLI Examples:
salt myminion nspawn.reboot arch1 salt myminion nspawn.restart arch1
salt.modules.nspawn.reboot(name, kill=False)
-
Remove the named container
Warning
This function will remove all data associated with the container. It will not, however, remove the btrfs subvolumes created by pulling container images (
nspawn.pull_raw
,nspawn.pull_tar
,nspawn.pull_dkr
).- stopFalse
-
If
True
, the container will be destroyed even if it is running/frozen.
CLI Examples:
salt '*' nspawn.remove foo salt '*' nspawn.remove foo stop=True
salt.modules.nspawn.remove(name, stop=False)
-
Run
cmd.retcode
within a container- name
-
Name of the container in which to run the command
- cmd
-
Command to run
- no_startFalse
-
If the container is not running, don't start it
- preserve_stateTrue
-
After running the command, return the container to its previous state
- stdinNone
-
Standard input to be used for the command
- output_logleveldebug
-
Level at which to log the output from the command. Set to
quiet
to suppress logging. - use_vtFalse
-
Use SaltStack's utils.vt to stream output to console. Assumes
output=all
. - keep_envNone
-
If not passed, only a sane default PATH environment variable will be set. If
True
, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.
CLI Example:
salt myminion nspawn.retcode mycontainer 'ip addr show'
salt.modules.nspawn.retcode(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)
-
Run
cmd.run
within a container- name
-
Name of the container in which to run the command
- cmd
-
Command to run
- no_startFalse
-
If the container is not running, don't start it
- preserve_stateTrue
-
After running the command, return the container to its previous state
- stdinNone
-
Standard input to be used for the command
- output_logleveldebug
-
Level at which to log the output from the command. Set to
quiet
to suppress logging. - use_vtFalse
-
Use SaltStack's utils.vt to stream output to console.
- keep_envNone
-
If not passed, only a sane default PATH environment variable will be set. If
True
, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.
CLI Example:
salt myminion nspawn.run mycontainer 'ifconfig -a'
salt.modules.nspawn.run(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)
-
Run
cmd.run_all
within a containerNote
While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container.
- name
-
Name of the container in which to run the command
- cmd
-
Command to run
- no_startFalse
-
If the container is not running, don't start it
- preserve_stateTrue
-
After running the command, return the container to its previous state
- stdinNone
-
Standard input to be used for the command
- output_logleveldebug
-
Level at which to log the output from the command. Set to
quiet
to suppress logging. - use_vtFalse
-
Use SaltStack's utils.vt to stream output to console. Assumes
output=all
. - keep_envNone
-
If not passed, only a sane default PATH environment variable will be set. If
True
, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.
CLI Example:
salt myminion nspawn.run_all mycontainer 'ip addr show'
salt.modules.nspawn.run_all(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)
-
Run
cmd.run_stderr
within a container- name
-
Name of the container in which to run the command
- cmd
-
Command to run
- no_startFalse
-
If the container is not running, don't start it
- preserve_stateTrue
-
After running the command, return the container to its previous state
- stdinNone
-
Standard input to be used for the command
- output_logleveldebug
-
Level at which to log the output from the command. Set to
quiet
to suppress logging. - use_vtFalse
-
Use SaltStack's utils.vt to stream output to console. Assumes
output=all
. - keep_envNone
-
If not passed, only a sane default PATH environment variable will be set. If
True
, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.
CLI Example:
salt myminion nspawn.run_stderr mycontainer 'ip addr show'
salt.modules.nspawn.run_stderr(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)
-
Run
cmd.run_stdout
within a container- name
-
Name of the container in which to run the command
- cmd
-
Command to run
- no_startFalse
-
If the container is not running, don't start it
- preserve_stateTrue
-
After running the command, return the container to its previous state
- stdinNone
-
Standard input to be used for the command
- output_logleveldebug
-
Level at which to log the output from the command. Set to
quiet
to suppress logging. - use_vtFalse
-
Use SaltStack's utils.vt to stream output to console. Assumes
output=all
. - keep_envNone
-
If not passed, only a sane default PATH environment variable will be set. If
True
, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.
CLI Example:
salt myminion nspawn.run_stdout mycontainer 'ifconfig -a'
salt.modules.nspawn.run_stdout(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)
-
Start the named container
CLI Example:
salt myminion nspawn.start <name>
salt.modules.nspawn.start(name)
-
Return state of container (running or stopped)
CLI Example:
salt myminion nspawn.state <name>
salt.modules.nspawn.state(name)
-
Kill all processes in the container without issuing a clean shutdown. Equivalent to running
machinectl terminate
on the named container.For convenience, running
nspawn.stop
and passingkill=True
(as shown in the CLI examples below) is equivalent to runningnspawn.terminate
.Note
machinectl terminate
is only supported in systemd >= 219. On earlier systemd versions, running this function will simply issue a clean shutdown viasystemctl
.CLI Examples:
salt myminion nspawn.terminate arch1 salt myminion nspawn.stop arch1 kill=True
salt.modules.nspawn.terminate(name)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.nspawn.html