nomad-mixin

README

Nomad Mixin for Porter

This is a Porter mixin for interacting with Nomad.

Installation

todo

Mixin Syntax

In your porter.yaml file, add nomad as a mixin:

mixins:
  - nomad:

To use the mixin in an Install/Upgrade/Uninstall step, add the "jobs" block to your porter.yaml file (using install here an example):

install:
  - nomad:
      jobs:
        - path: nomad/pytechco-redis.nomad.hcl
        - path: nomad/pytechco-web.nomad.hcl
        - path: nomad/pytechco-setup.nomad.hcl
        - dispatch: pytechco-setup
          meta:
            budget: "200"
        - path: nomad/pytechco-employee.nomad.hcl

The job step supports the following 3 actions which can be specified as a list item in the jobs: block:

• path: runs a Nomad job file using the given Nomad hcl file.
• dispatch: dispatches a parametrized Nomad job using the given job name. Note that this requires a previously registered Nomad batch job.
  • meta: (optional): a map of key/value pairs that will be passed as metadata to the Nomad job.
  • idPrefixTemplate (optional): a prefix added to dispatched job IDs.
  • payload (optional): base64 encoded string containng the payload to pass to the Nomad job. Limited to 65536 bytes.
• stop: stops a Nomad job using the given job name.
  • purge: (optional): if set to true, the job will be purged immediately.

Each of the 3 actions above can also take in the following options, which can be passed as arguments to each individual Nomad run, overriding any global Nomad parameters set earlier:

• address (string): the address of the Nomad server to connect to.
• region (string): the region of the Nomad server to connect to.
• namespace (string): the namespace of the Nomad server to connect to.
• caCert (string): the path to the CA cert file to use for TLS.
• caPath (string): the path to a directory of CA cert files to use for TLS.
• clientCert (string): the path to the client cert file to use for TLS.
• clientKey (string): the path to the client key file to use for TLS.
• tlsServerName (string): the server name to use as the SNI host when connecting via TLS.
• tlsSkipVerify (bool): disables TLS host verification.
• token (string): the ACL token to use when connecting to Nomad.

If you don't want to specify these settings for each individual job, you can specify them globally in the porter.yaml file as porter parameters, which will create corresponding environment variable inside the bundle. For example, the sample-bundle in this repo specifies a porter parameter named ip_address which sets the NOMAD_ADDR environment variable. Thus, there is no need to specify the address in each individual Nomad job run, since the Nomad mixin will automatically use the NOMAD_ADDR if set. The mixin will automatically use the following environment variables if set:

• NOMAD_ADDR
• NOMAD_REGION
• NOMAD_NAMESPACE
• NOMAD_HTTP_AUTH
• NOMAD_CACERT
• NOMAD_CAPATH
• NOMAD_CLIENT_CERT
• NOMAD_CLIENT_KEY
• NOMAD_TLS_SERVER_NAME
• NOMAD_SKIP_VERIFY
• NOMAD_TOKEN

For more information about these environment variables, see the Nomad documentation. Note that you can still override these environment variables for each individual job run by specifying the corresponding arguments in the run itself.

Additionally, the mixin also supports porter outputs. To specify an output for a job, add the outputs block to your job, with a list of name/key pairs to your run like so

nomad:
  jobs:
    - path: nomad/pytechco-redis.nomad.hcl
      outputs:
        - name: redis-evalId
          key: evalId

You can also specify a top-level outputs block in the porter.yaml, to specify the outputs of the bundle as a whole

outputs:
  - name: redis-evalId
    type: string
  - name: web-evalId
    type: string

This output can then be used in subsequent steps in your porter.yaml file using the syntax ${ bundle.outputs.redis-evalId }, see the porter documentation for more details.

Currently, the only supported output key is evalId, which is the ID of the Nomad evaluation that was created when the job was run. Note that not all Nomad jobs will create an evaluation, so this output will only be available for jobs that do.

Example Bundle

See the sample-bundle directory for a bundle that uses the Nomad mixin to run the official Nomad tutorial. The install step runs the various jobs from the tutorial, and the uninstall step stops and purges the jobs. Remember to provide the ip_address porter param when running the bundle (refer to the official Nomad tutorial for how to start a development sever agent). The bundle also specifies 2 porter outputs which gets used with the exec mixin.