nomad/website/source/docs/job-specification/artifact.html.md

layout, page_title, sidebar_current, description

layout	page_title	sidebar_current	description
docs	artifact Stanza - Job Specification	docs-job-specification-artifact	The "artifact" stanza instructs Nomad to fetch and unpack a remote resource, such as a file, tarball, or binary, and permits downloading artifacts from a variety of locations using a URL as the input source.

artifact Stanza

Placement	job -> group -> task -> **artifact**

The artifact stanza instructs Nomad to fetch and unpack a remote resource, such as a file, tarball, or binary. Nomad downloads artifacts using the popular go-getter library, which permits downloading artifacts from a variety of locations using a URL as the input source.

job "docs" {
  group "example" {
    task "server" {
      artifact {
        source      = "https://example.com/file.tar.gz"
        destination = "/tmp/file"
        options {
          checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33"
        }
      }
    }
  }
}

Nomad supports downloading http, https, git, hg and S3 artifacts. If these artifacts are archived (zip, tgz, bz2), they are automatically unarchived before the starting the task.

artifact Parameters

• destination (string: "local/$1") - Specifies the path to download the artifact, relative to the root of the task's directory. If omitted, the default value is to place the binary in local/. The destination is treated as a directory and source files will be downloaded into that directory path.

• options (map<string|string>: nil) - Specifies configuration parameters to fetch the artifact. The key-value pairs map directly to parameters appended to the supplied source URL. Please see the go-getter documentation for a complete list of options and examples

• source (string: <required>) - Specifies the URL of the artifact to download. Only http, https, and s3 URLs are supported. See go-getter for details.

artifact Examples

The following examples only show the artifact stanzas. Remember that the artifact stanza is only valid in the placements listed above.

Download File

This example downloads the artifact from the provided URL and places it in local/file.txt. The local/ path is relative to the task's directory.

artifact {
  source = "https://example.com/file.txt"
}

Download with Custom Destination

This example downloads the artifact from the provided URL and places it at /tmp/example.txt, as specified by the optional destination parameter.

artifact {
  source      = "https://example.com/file.txt"
  destination = "/tmp/example.txt"
}

Download and Unarchive

This example downloads and unarchives the result in local/file. Because the source URL is an archive extension, Nomad will automatically decompress it:

artifact {
  source = "https://example.com/file.tar.gz"
}

To disable automatic unarchiving, set the archive option to false:

artifact {
  source = "https://example.com/file.tar.gz"
  options {
    archive = false
  }
}

Download and Verify Checksums

This example downloads an artifact and verifies the resulting artifact's checksum before proceeding. If the checksum is invalid, an error will be returned.

artifact {
  source = "https://example.com/file.zip"

  options {
    checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33"
  }
}

Download from an S3 Bucket

These examples download artifacts from Amazon S3. There are several different types of S3 bucket addressing and S3 region-specific endpoints.

This example uses path-based notation on a publicly-accessible bucket:

artifact {
  source = "https://s3-us-west-2.amazonaws.com/my-bucket-example/my_app.tar.gz"
}

If a bucket requires authentication, it may be supplied via the options parameter:

artifact {
  options {
    aws_access_key_id     = "<id>"
    aws_access_key_secret = "<secret>"
    aws_access_token      = "<token>"
  }
}

To force the S3-specific syntax, use the s3:: prefix:

artifact {
  source = "s3::https://s3-eu-west-1.amazonaws.com/my-bucket-example/my_app.tar.gz"
}

Alternatively you can use virtual hosted style:

artifact {
  source = "https://my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz"
}