LXC Driver

Name: lxc

The lxc driver provides an interface for using LXC for running application containers. You can download the external LXC driver here. For more detailed instructions on how to set up and use this driver, please refer to the LXC guide.

Task Configuration

task "busybox" {
  driver = "lxc"

  config {
    log_level = "trace"
    verbosity = "verbose"
    template = "/usr/share/lxc/templates/lxc-busybox"
    template_args = []

    # these optional values can be set in the template
    distro =          ""
    release =         ""
    arch =            ""
    image_variant =   "default"
    image_server =    "images.linuxcontainers.org"
    gpg_key_id =      ""
    gpg_key_server =  ""
    disable_gpg =     false
    flush_cache =     false
    force_cache =     false
  }
}

The lxc driver supports the following configuration in the job spec:

• template - The LXC template to run.

  config {
    template = "/usr/share/lxc/templates/lxc-alpine"
  }
  

• template_args - A list of argument strings to pass into the template.

• log_level - (Optional) LXC library's logging level. Defaults to error. Must be one of trace, debug, info, warn, or error.

  config {
    log_level = "debug"
  }
  

• verbosity - (Optional) Enables extra verbosity in the LXC library's logging. Defaults to quiet. Must be one of quiet or verbose.

  config {
    verbosity = "quiet"
  }
  

• volumes - (Optional) A list of host_path:container_path strings to bind-mount host paths to container paths. Mounting host paths outside of the allocation working directory is allowed by default. You can prevent mounting host paths outside of the allocation working directory on individual clients by setting the volumes_enabled option to false in the client's configuration

  Note: Unlike the similar option for the docker driver, this option must not have an absolute path as the container_path component. This will cause an error when submitting a job.

  Setting this does not affect the standard bind-mounts of alloc, local, and secrets, which are always created.

  config {
    volumes = [
      # Use absolute paths to mount arbitrary paths on the host
      "/path/on/host:path/in/container",
  
      # Use relative paths to rebind paths already in the allocation dir
      "relative/to/task:also/in/container"
    ]
  }
  

• release - (Optional) The name/version of the distribution. By default this is set by the template.

• arch - (Optional) The architecture of the container. By default this is set by the template.

• image_server - (Optional) The hostname of the image server. Defaults to images.linuxcontainers.org.

• image_variant - (Optional) The variant of the image. Defaults to default or as set by the template.

• disable_gpg - (Optional) Disable GPG validation of images. Defaults to false, and enabling this flag is not recommended.

• flush_cache - (Optional) Flush the local copy of the image (if present) and force it to be fetched from the image server. Defaults to false.

• force_cache - (Optional) Force the use of the local copy even if expired. Defaults to false.

• gpg_key_server: GPG key server used for checking image signatures. Default is set by the underlying LXC library.

• gpg_key_id: GPG key ID used for checking image signatures. Default is set by the underlying LXC library.

Networking

Currently the lxc driver only supports host networking. See the none networking type in the lxc.container.conf manual for more information.

Client Requirements

The lxc driver requires the following:

• 64-bit Linux host
• The linux_amd64 Nomad binary
• The LXC driver binary placed in the plugin_dir directory.
• liblxc to be installed
• lxc-templates to be installed

Plugin Options

• enabled - The lxc driver may be disabled on hosts by setting this option to false (defaults to true).

• volumes_enabled - Specifies whether host can bind-mount host paths to container paths (defaults to true).

• lxc_path - The location in which all containers are stored (commonly defaults to /var/lib/lxc). See lxc-create for more details.

• gc block:

  • container - Defaults to true. This option can be used to disable Nomad from removing a container when the task exits. Under a name conflict, Nomad may still remove the dead container.

An example of using these plugin options with the new plugin syntax is shown below:

plugin "nomad-driver-lxc" {
  config {
    enabled = true
    volumes_enabled = true
    lxc_path = "/var/lib/lxc"
    gc {
      container = false
    }
  }
}

Please note the plugin name should match whatever name you have specified for the external driver in the plugin_dir directory.

Client Configuration

The lxc driver has the following client-level options:

• lxc.enable - The lxc driver may be disabled on hosts by setting this option to false (defaults to true).

Client Attributes

The lxc driver will set the following client attributes:

• driver.lxc - Set to 1 if LXC is found and enabled on the host node.
• driver.lxc.version - Version of lxc e.g.: 1.1.0.

Resource Isolation

This driver supports CPU and memory isolation via the lxc library. Network isolation is not supported as of now.