Control Linux Containers via Salt
depends: | lxc package for distribution |
---|
lxc >= 1.0 (even beta alpha) is required
New in version 2015.5.0.
Apply a network profile to a container
CLI Examples:
salt 'minion' lxc.apply_network_profile web1 centos
salt 'minion' lxc.apply_network_profile web1 centos \
nic_opts="{'eth0': {'mac': 'xx:xx:xx:xx:xx:xx'}}"
salt 'minion' lxc.apply_network_profile web1 \
"{'eth0': {'mac': 'xx:xx:xx:xx:xx:yy'}}"
nic_opts="{'eth0': {'mac': 'xx:xx:xx:xx:xx:xx'}}"
Return True if the named container can be attached to via the lxc-attach command
CLI Example:
salt 'minion' lxc.attachable ubuntu
Install and configure salt in a container.
Delay in seconds between end of container creation and bootstrapping. Useful when waiting for container to obtain a DHCP lease.
New in version 2015.5.0.
CLI Examples:
salt 'minion' lxc.bootstrap container_name [config=config_data] \
[approve_key=(True|False)] [install=(True|False)]
Create a new container as a clone of another container
Container Cloning Arguments
CLI Examples:
salt '*' lxc.clone myclone orig=orig_container
salt '*' lxc.clone myclone orig=orig_container snapshot=True
Thin wrapper to lxc.init to be used from the saltcloud lxc driver
CLI Example:
salt '*' lxc.cloud_init foo
Interface between salt.cloud.lxc driver and lxc.init vm_ is a mapping of vm opts in the salt.cloud format as documented for the lxc driver.
This can be used either:
Warning
BE REALLY CAREFUL CHANGING DEFAULTS !!! IT'S A RETRO COMPATIBLE INTERFACE WITH THE SALT CLOUD DRIVER (ask kiorky).
additional ips which will be wired on the main bridge (br0) which is connected to internet. Be aware that you may use manual virtual mac addresses providen by you provider (online, ovh, etc). This is a list of mappings {ip: '', mac: '', netmask:''} Set gateway to None and an interface with a gateway to escape from another interface that eth0. eg:
- {'mac': '00:16:3e:01:29:40',
'gateway': None, (default)
'link': 'br0', (default)
'netmask': '', (default)
'ip': '22.1.4.25'}
CLI Example:
salt '*' lxc.cloud_init_interface foo
Copy a file or directory from the host into a container.
Destination on the container. Must be an absolute path.
Changed in version 2015.5.0: If the destination is a directory, the file will be copied into that directory.
makedirs : False
Create the parent directory on the container if it does not already exist.
New in version 2015.5.0.
CLI Example:
salt 'minion' lxc.cp /tmp/foo /root/foo
Create a new container.
Network profile to use for container
New in version 2015.5.0.
Container Creation Arguments
The template to use. For example, ubuntu or fedora. Conflicts with the image argument.
Note
The download template requires the following three parameters to be defined in options:
The available images can be listed using the lxc.images function.
Template-specific options to pass to the lxc-create command. These correspond to the long options (ones beginning with two dashes) that the template script accepts. For example:
options='{"dist": "centos", "release": "6", "arch": "amd64"}'
Destroy the named container.
Warning
Destroys all data associated with the container.
If True, the container will be destroyed even if it is running/frozen.
Changed in version 2015.5.0: Default value changed to False. This more closely matches the behavior of lxc-destroy(1), and also makes it less likely that an accidental command will destroy a running container that was being used for important things.
CLI Examples:
salt '*' lxc.destroy foo
salt '*' lxc.destroy foo stop=True
Edit an LXC configuration file. If a setting is already present inside the file, its value will be replaced. If it does not exist, it will be appended to the end of the file. Comments and blank lines will be kept in-tact if they already exist in the file.
After the file is edited, its contents will be returned. By default, it will be returned in simple format, meaning an unordered dict (which may not represent the actual file order). Passing in an out_format of commented will return a data structure which accurately represents the order and content of the file.
CLI Example:
salt 'minion' lxc.edit_conf /etc/lxc/mycontainer.conf \
out_format=commented lxc.network.type=veth
salt 'minion' lxc.edit_conf /etc/lxc/mycontainer.conf \
out_format=commented \
lxc_config="[{'lxc.network.name': 'eth0', \
'lxc.network.ipv4': '1.2.3.4'},
{'lxc.network.name': 'eth2', \
'lxc.network.ipv4': '1.2.3.5',\
'lxc.network.gateway': '1.2.3.1'}]"
Returns whether the named container exists.
CLI Example:
salt '*' lxc.exists name
Freeze the named container
If True and the container is stopped, the container will be started before attempting to freeze.
New in version 2015.5.0.
CLI Example:
salt '*' lxc.freeze name
New in version 2015.5.0.
Gather a pre-configured set of container configuration parameters. If no arguments are passed, an empty profile is returned.
Profiles can be defined in the minion or master config files, or in pillar or grains, and are loaded using config.get. The key under which LXC profiles must be configured is lxc.container_profile.profile_name. An example container profile would be as follows:
lxc.container_profile:
ubuntu:
template: ubuntu
backing: lvm
vgname: lxc
size: 1G
Parameters set in a profile can be overridden by passing additional container creation arguments (such as the ones passed to lxc.create) to this function.
A profile can be defined either as the name of the profile, or a dictionary of variable names and values. See the LXC Tutorial for more information on how to use LXC profiles.
CLI Example:
.. code-block:: bash
salt-call lxc.get_container_profile centos salt-call lxc.get_container_profile ubuntu template=ubuntu backing=overlayfs
New in version 2015.5.0.
Gather a pre-configured set of network configuration parameters. If no arguments are passed, the following default profile is returned:
{'eth0': {'link': 'br0', 'type': 'veth', 'flags': 'up'}}
Profiles can be defined in the minion or master config files, or in pillar or grains, and are loaded using config.get. The key under which LXC profiles must be configured is lxc.network_profile. An example network profile would be as follows:
lxc.network_profile.centos:
eth0:
link: br0
type: veth
flags: up
Parameters set in a profile can be overridden by passing additional arguments to this function.
A profile can be passed either as the name of the profile, or a dictionary of variable names and values. See the LXC Tutorial for more information on how to use network profiles.
Warning
The ipv4, ipv6, gateway, and link (bridge) settings in network profiles will only work if the container doesnt redefine the network configuration (for example in /etc/sysconfig/network-scripts/ifcfg-<interface_name> on RHEL/CentOS, or /etc/network/interfaces on Debian/Ubuntu/etc.)
CLI Example:
.. code-block:: bash
salt-call lxc.get_network_profile default
Returns the value of a cgroup parameter for a container
CLI Example:
salt '*' lxc.get_parameter container_name memory.limit_in_bytes
New in version 2015.5.0.
List the available images for LXC's download template.
CLI Examples:
salt myminion lxc.images
salt myminion lxc.images dist=centos
Returns information about a container
CLI Example:
salt '*' lxc.info name
Initialize a new container.
This is a partial idempotent function as if it is already provisioned, we will reset a bit the lxc configuration file but much of the hard work will be escaped as markers will prevent re-execution of harmful tasks.
cgroups memory limit, in MB
Changed in version 2015.5.0: If no value is passed, no limit is set. In earlier Salt versions, not passing this value causes a 1024MB memory limit to be set, and it was necessary to pass memory=0 to set no limit.
Network profile to use for the container
New in version 2015.5.0.
Deprecated since version 2015.5.0: Use network_profile instead
Extra options for network interfaces, will override
{"eth0": {"hwaddr": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1", "ipv6": "2001:db8::ff00:42:8329"}}
or
{"eth0": {"hwaddr": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1/24", "ipv6": "2001:db8::ff00:42:8329"}}
Set to True to denote a password hash instead of a plaintext password
New in version 2015.5.0.
Deprecated since version 2015.5.0: Use clone_from instead
Delay in seconds between end of container creation and bootstrapping. Useful when waiting for container to obtain a DHCP lease.
New in version 2015.5.0.
CLI Example:
salt 'minion' lxc.init name [cpuset=cgroups_cpuset] \
[cpushare=cgroups_cpushare] [memory=cgroups_memory] \
[nic=nic_profile] [profile=lxc_profile] \
[nic_opts=nic_opts] [start=(True|False)] \
[seed=(True|False)] [install=(True|False)] \
[config=minion_config] [approve_key=(True|False) \
[clone_from=original] [autostart=True] \
[priv_key=/path_or_content] [pub_key=/path_or_content] \
[bridge=lxcbr0] [gateway=10.0.3.1] \
[dnsservers[dns1,dns2]] \
[users=[foo]] [password='secret'] \
[password_encrypted=(True|False)]
List containers classified by state
Return output matching a specific state (frozen, running, or stopped).
New in version 2015.5.0.
CLI Examples:
salt '*' lxc.list
salt '*' lxc.list extra=True
salt '*' lxc.list limit=running
Return a list of the containers available on the minion
If True, return only active (i.e. running) containers
New in version 2015.5.0.
CLI Example:
salt '*' lxc.ls
salt '*' lxc.ls active=True
Read in an LXC configuration file. By default returns a simple, unsorted dict, but can also return a more detailed structure including blank lines and comments.
- out_format:
- set to 'simple' if you need the old and unsupported behavior. This wont support the multiple lxc values (eg: multiple network nics)
CLI Examples:
salt 'minion' lxc.read_conf /etc/lxc/mycontainer.conf
salt 'minion' lxc.read_conf /etc/lxc/mycontainer.conf out_format=commented
New in version 2015.5.0.
Restart the named container. If the container was not running, the container will merely be started.
CLI Example:
salt myminion lxc.restart name
New in version 2015.5.0.
Run cmd.retcode within a container
Warning
Many shell builtins do not work, failing with stderr similar to the following:
lxc_container: No such file or directory - failed to exec 'command'
The same error will be displayed in stderr if the command being run does not exist. If the retcode is nonzero and not what was expected, try using lxc.run_stderr or lxc.run_all.
CLI Example:
salt myminion lxc.retcode mycontainer 'ip addr show'
New in version 2015.5.0.
Run cmd.run within a container
Warning
Many shell builtins do not work, failing with stderr similar to the following:
lxc_container: No such file or directory - failed to exec 'command'
The same error will be displayed in stderr if the command being run does not exist. If no output is returned using this function, try using lxc.run_stderr or lxc.run_all.
CLI Example:
salt myminion lxc.run mycontainer 'ifconfig -a'
New in version 2015.5.0.
Run cmd.run_all within a container
Warning
Many shell builtins do not work, failing with stderr similar to the following:
lxc_container: No such file or directory - failed to exec 'command'
The same error will be displayed in stderr if the command being run does not exist.
CLI Example:
salt myminion lxc.run_all mycontainer 'ip addr show'
Deprecated since version 2015.5.0.
Use lxc.run instead
New in version 2015.5.0.
Run cmd.run_stderr within a container
Warning
Many shell builtins do not work, failing with stderr similar to the following:
lxc_container: No such file or directory - failed to exec 'command'
The same error will be displayed if the command being run does not exist.
CLI Example:
salt myminion lxc.run_stderr mycontainer 'ip addr show'
New in version 2015.5.0.
Run cmd.run_stdout within a container
Warning
Many shell builtins do not work, failing with stderr similar to the following:
lxc_container: No such file or directory - failed to exec 'command'
The same error will be displayed in stderr if the command being run does not exist. If no output is returned using this function, try using lxc.run_stderr or lxc.run_all.
CLI Example:
salt myminion lxc.run_stdout mycontainer 'ifconfig -a'
Changed in version 2015.5.0: The dnsservers and searchdomains parameters can now be passed as a comma-separated list.
Update /etc/resolv.conf
CLI Example:
salt myminion lxc.set_dns ubuntu "['8.8.8.8', '4.4.4.4']"
Set the value of a cgroup parameter for a container.
CLI Example:
salt '*' lxc.set_parameter name parameter value
Changed in version 2015.5.0: Function renamed from set_pass to set_password. Additionally, this function now supports (and defaults to using) a password hash instead of a plaintext password.
Set the password of one or more system users inside containers
If true, password must be a password hash. Set to False to set a plaintext password (not recommended).
New in version 2015.5.0.
CLI Example:
salt '*' lxc.set_pass container-name root '$6$uJ2uAyLU$KoI67t8As/0fXtJOPcHKGXmUpcoYUcVR2K6x93walnShTCQvjRwq25yIkiCBOqgbfdKQSFnAo28/ek6716vEV1'
salt '*' lxc.set_pass container-name root foo encrypted=False
Start the named container
Deprecated since version 2015.5.0: Use lxc.restart
Restart the container if it is already running
CLI Example:
salt myminion lxc.start name
Returns the state of a container.
CLI Example:
salt '*' lxc.state name
Stop the named container
Do not wait for the container to stop, kill all tasks in the container. Older LXC versions will stop containers like this irrespective of this argument.
Changed in version 2015.5.0: Default value changed to False
CLI Example:
salt myminion lxc.stop name
New in version 2015.5.0.
List the available LXC template scripts installed on the minion
CLI Examples:
salt myminion lxc.templates
Unfreeze the named container.
CLI Example:
salt '*' lxc.unfreeze name
Edit LXC configuration options
CLI Example:
salt myminion lxc.update_lxc_conf ubuntu \
lxc_conf="[{'network.ipv4.ip':'10.0.3.5'}]" \
lxc_conf_unset="['lxc.utsname']"
Write out an LXC configuration file
This is normally only used internally. The format of the data structure must match that which is returned from lxc.read_conf(), with out_format set to commented.
An example might look like:
[
{'lxc.utsname': '$CONTAINER_NAME'},
'# This is a commented line\n',
'\n',
{'lxc.mount': '$CONTAINER_FSTAB'},
{'lxc.rootfs': {'comment': 'This is another test',
'value': 'This is another test'}},
'\n',
{'lxc.network.type': 'veth'},
{'lxc.network.flags': 'up'},
{'lxc.network.link': 'br0'},
{'lxc.network.mac': '$CONTAINER_MACADDR'},
{'lxc.network.ipv4': '$CONTAINER_IPADDR'},
{'lxc.network.name': '$CONTAINER_DEVICENAME'},
]
CLI Example:
salt 'minion' lxc.write_conf /etc/lxc/mycontainer.conf \
out_format=commented
Docs for previous releases are available on readthedocs.org.
Latest Salt release: 2014.7.2