HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Nomad
Nomad Home

You are viewing documentation for version v1.0.x. View latest version.

csi_plugin Stanza

Placementjob -> group -> task -> volume

The "csi_plugin" stanza allows the task to specify it provides a Container Storage Interface plugin to the cluster. Nomad will automatically register the plugin so that it can be used by other jobs to claim volumes.

csi_plugin {
  id        = "csi-hostpath"
  type      = "monolith"
  mount_dir = "/csi"
}

csi_plugin Parameters

  • id (string: <required>) - This is the ID for the plugin. Some plugins will require both controller and node plugin types (see below); you need to use the same ID for both so that Nomad knows they belong to the same plugin.

  • type (string: <required>) - One of node, controller, or monolith. Each plugin supports one or more types. Each Nomad client node where you want to mount a volume will need a node plugin instance. Some plugins will also require one or more controller plugin instances to communicate with the storage provider's APIs. Some plugins can serve as both controller and node at the same time, and these are called monolith plugins. Refer to your CSI plugin's documentation.

  • mount_dir (string: <required>) - The directory path inside the container where the plugin will expect a Unix domain socket for bidirectional communication with Nomad.

Note: Plugins running as node or monolith require root privileges (or CAP_SYS_ADMIN on Linux) to mount volumes on the host. With the Docker task driver, you can use the privileged = true configuration, but no other default task drivers currently have this option.

Note: During node drains, jobs that claim volumes must be moved before the node or monolith plugin for those volumes. You should run node or monolith plugins as system jobs and use the -ignore-system flag on nomad node drain to ensure that the plugins are running while the node is being drained.

Note: Only one plugin instance of a given plugin ID and type (controller or node) should be deployed on any given client node. Use a constraint as shown below.

csi_plugin Examples

job "plugin-efs" {
  datacenters = ["dc1"]

  # you can run node plugins as service jobs as well, but running
  # as a system job ensures all nodes in the DC have a copy.
  type = "system"

  # only one plugin of a given type and ID should be deployed on
  # any given client node
  constraint {
    operator = "distinct_hosts"
    value = true
  }

  group "nodes" {
    task "plugin" {
      driver = "docker"

      config {
        image = "amazon/aws-efs-csi-driver:latest"

        args = [
          "node",
          "--endpoint=unix://csi/csi.sock",
          "--logtostderr",
          "--v=5",
        ]

        # all CSI node plugins will need to run as privileged tasks
        # so they can mount volumes to the host. controller plugins
        # do not need to be privileged.
        privileged = true
      }

      csi_plugin {
        id        = "aws-efs0"
        type      = "node"
        mount_dir = "/csi"  # this path /csi matches the --endpoint
                            # argument for the container
      }
    }
  }
}