The Waypoint website is being redesigned to help you find what you are looking for more effectively.

»Nomad

For a step by step tutorial, visit HashiCorp Learn.

»Builders

Nomad is a simple, flexible scheduler and workload orchestrator. Nomad uses Docker images for building, which are generated by these builders:

»Nomad Client

A Nomad API client is used for deploying to the Nomad platform with each of the Nomad plugins. This client uses environment variables to connect to a Nomad cluster. These can be configured with runner config.

NOMAD_CA_CERT
NOMAD_CLIENT_CERT
NOMAD_CLIENT_KEY
NOMAD_TLS_SKIP_VERIFY
NOMAD_TOKEN

Note: This is not an all-inclusive list. Please refer to the GoLang Nomad API client documentation.

»nomad (platform)

Deploy to a nomad cluster as a service using docker.

»Interface

»Examples

deploy {
        use "nomad" {
          region = "global"
          datacenter = "dc1"
          auth {
            username = "username"
            password = "password"
          }
          static_environment = {
            "environment": "production",
            "LOG_LEVEL": "debug"
          }
          service_port = 3000
          replicas = 1
        }
}

deploy {
        use "nomad" {
          region = "global"
          datacenter = "dc1"
          auth {
            username = "username"
            password = "password"
          }
          static_environment = {
            "environment": "production",
            "LOG_LEVEL": "debug"
          }
          service_port = 3000
          replicas = 1
        }
}

»Required Parameters

These parameters are used in the use stanza for this plugin.

»auth

The credentials for docker registry.

Type: nomad.AuthConfig

»consul_token

The Consul ACL token used to register services with the Nomad job.

Uses the runner config environment variable CONSUL_HTTP_TOKEN.

»resources (category)

The amount of resources to allocate to the deployed allocation.

»resources.cpu

Amount of CPU in MHz to allocate to this task.

Type: int
Optional
Default: 100

»resources.memorymb

Amount of memory in MB to allocate to this task.

Type: int
Optional
Default: 300

»vault_token

The Vault token used to deploy the Nomad job with a token having specific Vault policies attached.

Uses the runner config environment variable VAULT_TOKEN.

»Optional Parameters

These parameters are used in the use stanza for this plugin.

»datacenter

The Nomad datacenter to deploy the job to.

Type: string
Optional
Default: dc1

»namespace

The Nomad namespace to deploy the job to.

Type: string
Optional

»region

The Nomad region to deploy the job to.

Type: string
Optional
Default: global

»replicas

The replica count for the job.

Type: int
Optional
Default: 1

»service_port

TCP port the job is listening on.

Type: uint
Optional

»static_environment

Environment variables to add to the job.

Type: map of string to string
Optional

»Output Attributes

Output attributes can be used in your waypoint.hcl as variables via artifact or deploy.

»id

Type: string

»name

Type: string

»resource_state

Type: opaqueany.Any

»nomad-jobspec (platform)

Deploy to a Nomad cluster from a pre-existing Nomad job specification file.

This plugin lets you use any pre-existing Nomad job specification file to deploy to Nomad. This deployment is able to support all the features of Waypoint. You may use Waypoint's templating features to template the Nomad jobspec with information such as the artifact from a previous build step, entrypoint environment variables, etc.

»Artifact Access

You may use Waypoint's templating features to access information such as the artifact from the build or push stages. An example below shows this by using templatefile mixed with variables such as artifact.image to dynamically configure the Docker image within the Nomad job specification.

Note: If using Nomad interpolation in your jobspec file, and the templatefile function in your waypoint.hcl file, any interpolated values must be escaped with a second $. For example: $${meta.metadata} instead of ${meta.metadata}.

»Entrypoint Functionality

Waypoint entrypoint functionality such as logs, exec, app configuration, and more require two properties to be true:

The running image must already have the Waypoint entrypoint installed and configured as the entrypoint. This should happen in the build stage.
Proper environment variables must be set so the entrypoint knows how to communicate to the Waypoint server. This step happens in this deployment stage.

Step 2 does not happen automatically. You must manually set the entrypoint environment variables using the templating feature. One of the examples below shows the entrypoint environment variables being injected.

»URL Service

If you want your workload to be accessible by the Waypoint URL service, you must set the PORT environment variable within your job and be using the Waypoint entrypoint (documented in the previous section).

The PORT environment variable should be the port that your web service is listening on that the URL service will connect to. See one of the examples below for more details.

»Interface

»Examples

// The waypoint.hcl file
deploy {
  use "nomad-jobspec" {
    // Templated to perhaps bring in the artifact from a previous
    // build/registry, entrypoint env vars, etc.
    jobspec = templatefile("${path.app}/app.nomad.tpl")
  }
}

// The app.nomad.tpl file
job "web" {
  datacenters = ["dc1"]

  group "app" {
    task "app" {
      driver = "docker"

      config {
        image = "${artifact.image}:${artifact.tag}"
      }

      env {
        %{ for k,v in entrypoint.env ~}
        ${k} = "${v}"
        %{ endfor ~}

        // Ensure we set PORT for the URL service. This is only necessary
        // if we want the URL service to function.
        PORT = 3000
      }
    }
  }
}

// The waypoint.hcl file
deploy {
  use "nomad-jobspec" {
    // Templated to perhaps bring in the artifact from a previous
    // build/registry, entrypoint env vars, etc.
    jobspec = templatefile("${path.app}/app.nomad.tpl")
  }
}

// The app.nomad.tpl file
job "web" {
  datacenters = ["dc1"]

  group "app" {
    task "app" {
      driver = "docker"

      config {
        image = "${artifact.image}:${artifact.tag}"
      }

      env {
        %{ for k,v in entrypoint.env ~}
        ${k} = "${v}"
        %{ endfor ~}

        // Ensure we set PORT for the URL service. This is only necessary
        // if we want the URL service to function.
        PORT = 3000
      }
    }
  }
}

»Required Parameters

These parameters are used in the use stanza for this plugin.

»consul_token

The Consul ACL token used to register services with the Nomad job.

Uses the runner config environment variable CONSUL_HTTP_TOKEN.

»jobspec

Path to a Nomad job specification file.

Type: string

»vault_token

The Vault token used to deploy the Nomad job with a token having specific Vault policies attached.

Uses the runner config environment variable VAULT_TOKEN.

»Optional Parameters

These parameters are used in the use stanza for this plugin.

»hcl1

Parses jobspec as HCL1 instead of HCL2.

Type: bool
Optional
Default: false

»Output Attributes

Output attributes can be used in your waypoint.hcl as variables via artifact or deploy.

»id

Type: string

»name

Type: string

»resource_state

Type: opaqueany.Any

»nomad-jobspec-canary (releasemanager)

Promotes a Nomad canary deployment initiated by a Nomad jobspec deployment.

If your Nomad deployment is configured to use canaries, this releaser plugin lets you promote (or fail) the canary deployment. You may also target specific task groups within your job for promotion, if you have multiple task groups in your canary deployment.

Note: Using the -prune=false flag is recommended for this releaser. By default, Waypoint prunes and destroys all unreleased deployments and keeps only one previous deployment. Therefore, if -prune=false is not set, Waypoint may delete your job via "pruning" a previous version. See deployment pruning for more information.

»Release URL

If you want the URL of the release of your deployment to be published in Waypoint, you must set the meta 'waypoint.hashicorp.com/release_url' in your jobspec. The value specified in this meta field will be published as the release URL for your application. In the future, this may source from Consul.

»Interface

»Examples

// The waypoint.hcl file
release {
  use "nomad-jobspec-canary" {
    groups = [
      "app"
    ]
  }
}

// The app.nomad.tpl file
job "web" {
  datacenters = ["dc1"]

  group "app" {
    network {
      mode = "bridge"
      port "http" {
        to = 80
      }
    }

    // Setting a canary in the update stanza indicates a canary deployment
    update {
      max_parallel = 1
      canary       = 1
      auto_revert  = true
      auto_promote = false
      health_check = "task_states"
    }

    service {
      name = "app"
      port = 80
      connect {
        sidecar_service {}
      }
    }

    task "app" {
      driver = "docker"
      config {
        image = "${artifact.image}:${artifact.tag}"
        ports  = ["http"]
      }

      env {
        %{ for k,v in entrypoint.env ~}
        ${k} = "${v}"
        %{ endfor ~}

        // Ensure we set PORT for the URL service. This is only necessary
        // if we want the URL service to function.
        PORT = 80
      }
    }
  }

  group "app-gateway" {
    network {
      mode = "bridge"
      port "inbound" {
        static = 8080
        to     = 8080
      }
    }

    service {
      name = "gateway"
      port = "8080"

      connect {
        gateway {
          proxy {}

          ingress {
            listener {
              port = 8080
              protocol = "http"
              service {
                name  = "app"
                hosts = [ "*" ]
              }
            }
          }
        }
      }
    }
  }
  meta = {
    // Ensure we set meta for Waypoint to detect the release URL
    "waypoint.hashicorp.com/release_url" = "http://app.ingress.dc1.consul:8080"
  }
}

// The waypoint.hcl file
release {
  use "nomad-jobspec-canary" {
    groups = [
      "app"
    ]
  }
}

// The app.nomad.tpl file
job "web" {
  datacenters = ["dc1"]

  group "app" {
    network {
      mode = "bridge"
      port "http" {
        to = 80
      }
    }

    // Setting a canary in the update stanza indicates a canary deployment
    update {
      max_parallel = 1
      canary       = 1
      auto_revert  = true
      auto_promote = false
      health_check = "task_states"
    }

    service {
      name = "app"
      port = 80
      connect {
        sidecar_service {}
      }
    }

    task "app" {
      driver = "docker"
      config {
        image = "${artifact.image}:${artifact.tag}"
        ports  = ["http"]
      }

      env {
        %{ for k,v in entrypoint.env ~}
        ${k} = "${v}"
        %{ endfor ~}

        // Ensure we set PORT for the URL service. This is only necessary
        // if we want the URL service to function.
        PORT = 80
      }
    }
  }

  group "app-gateway" {
    network {
      mode = "bridge"
      port "inbound" {
        static = 8080
        to     = 8080
      }
    }

    service {
      name = "gateway"
      port = "8080"

      connect {
        gateway {
          proxy {}

          ingress {
            listener {
              port = 8080
              protocol = "http"
              service {
                name  = "app"
                hosts = [ "*" ]
              }
            }
          }
        }
      }
    }
  }
  meta = {
    // Ensure we set meta for Waypoint to detect the release URL
    "waypoint.hashicorp.com/release_url" = "http://app.ingress.dc1.consul:8080"
  }
}

»Required Parameters

This plugin has no required parameters.

»Optional Parameters

These parameters are used in the use stanza for this plugin.

»fail_deployment

If true, marks the deployment as failed.

Type: bool
Optional

»groups

List of task group names which are to be promoted.

Type: list of string
Optional

»nomad (task)

Launch a Nomad job for on-demand tasks from the Waypoint server.

This will use the standard Nomad environment used for with the server install to launch on demand Nomad jobs for Waypoint server tasks.

»Interface

»Examples

task {
    use "nomad" {}
}

task {
    use "nomad" {}
}

»Required Parameters

This plugin has no required parameters.

»Optional Parameters

These parameters are used in the use stanza for this plugin.

»datacenter

The Nomad datacenter to deploy the on-demand runner task to.

Type: string
Optional
Default: dc1

»namespace

The Nomad namespace to deploy the on-demand runner task to.

Type: string
Optional
Default: default

»nomad_host

Hostname of the Nomad server to use for launching on-demand tasks.

Type: string
Optional
Default: http://localhost:4646

»region

The Nomad region to deploy the on-demand runner task to.

Type: string
Optional
Default: global

»resources_cpu

Amount of CPU in MHz to allocate to this task. This can be overriden with the '-nomad-runner-cpu' flag on server install.

Type: int
Optional
Default: 200

»resources_memory

Amount of memory in MB to allocate to this task. This can be overriden with the '-nomad-runner-memory' flag on server install.

Type: int
Optional
Default: 2000

»Output Attributes

Output attributes can be used in your waypoint.hcl as variables via artifact or deploy.

»id

Type: string