github.com/smintz/nomad@v0.8.3/website/source/docs/job-specification/artifact.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "artifact Stanza - Job Specification" 4 sidebar_current: "docs-job-specification-artifact" 5 description: |- 6 The "artifact" stanza instructs Nomad to fetch and unpack a remote resource, 7 such as a file, tarball, or binary, and permits downloading artifacts from a 8 variety of locations using a URL as the input source. 9 --- 10 11 # `artifact` Stanza 12 13 <table class="table table-bordered table-striped"> 14 <tr> 15 <th width="120">Placement</th> 16 <td> 17 <code>job -> group -> task -> **artifact**</code> 18 </td> 19 </tr> 20 </table> 21 22 The `artifact` stanza instructs Nomad to fetch and unpack a remote resource, 23 such as a file, tarball, or binary. Nomad downloads artifacts using the popular 24 [`go-getter`][go-getter] library, which permits downloading artifacts from a 25 variety of locations using a URL as the input source. 26 27 ```hcl 28 job "docs" { 29 group "example" { 30 task "server" { 31 artifact { 32 source = "https://example.com/file.tar.gz" 33 destination = "/tmp/directory" 34 options { 35 checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33" 36 } 37 } 38 } 39 } 40 } 41 ``` 42 43 Nomad supports downloading `http`, `https`, `git`, `hg` and `S3` artifacts. If 44 these artifacts are archived (`zip`, `tgz`, `bz2`, `xz`), they are 45 automatically unarchived before the starting the task. 46 47 ## `artifact` Parameters 48 49 - `destination` `(string: "local/")` - Specifies the directory path to download 50 the artifact, relative to the root of the task's directory. If omitted, the 51 default value is to place the artifact in `local/`. The destination is treated 52 as a directory unless `mode` is set to `file`. Source files will be downloaded 53 into that directory path. 54 55 - `mode` `(string: "any")` - One of `any`, `file`, or `dir`. If set to `file` 56 the `destination` must be a file, not a directory. By default the 57 `destination` will be `local/<filename>`. 58 59 - `options` `(map<string|string>: nil)` - Specifies configuration parameters to 60 fetch the artifact. The key-value pairs map directly to parameters appended to 61 the supplied `source` URL. Please see the [`go-getter` 62 documentation][go-getter] for a complete list of options and examples 63 64 - `source` `(string: <required>)` - Specifies the URL of the artifact to download. 65 See [`go-getter`][go-getter] for details. 66 67 ## `artifact` Examples 68 69 The following examples only show the `artifact` stanzas. Remember that the 70 `artifact` stanza is only valid in the placements listed above. 71 72 ### Download File 73 74 This example downloads the artifact from the provided URL and places it in 75 `local/file.txt`. The `local/` path is relative to the task's directory. 76 77 ```hcl 78 artifact { 79 source = "https://example.com/file.txt" 80 } 81 ``` 82 83 ### Download with Custom Destination 84 85 This example downloads the artifact from the provided URL and places it at 86 `/tmp/example/file.txt`, as specified by the optional `destination` parameter. 87 88 ```hcl 89 artifact { 90 source = "https://example.com/file.txt" 91 destination = "/tmp/example" 92 } 93 ``` 94 95 ### Download using git 96 97 This example downloads the artifact from the provided GitHub URL and places it at 98 `local/repo`, as specified by the optional `destination` parameter. 99 100 ```hcl 101 artifact { 102 source = "git::https://github.com/example/nomad-examples" 103 destination = "local/repo" 104 } 105 ``` 106 107 To download from private repo, sshkey need to be set. The key must be 108 base64-encoded string. Run `base64 -w0 <file>` 109 110 ```hcl 111 artifact { 112 source = "git@github.com:example/nomad-examples" 113 destination = "local/repo" 114 options { 115 sshkey = "<string>" 116 } 117 } 118 ``` 119 120 ### Download and Unarchive 121 122 This example downloads and unarchives the result in `local/file`. Because the 123 source URL is an archive extension, Nomad will automatically decompress it: 124 125 ```hcl 126 artifact { 127 source = "https://example.com/file.tar.gz" 128 } 129 ``` 130 131 To disable automatic unarchiving, set the `archive` option to false: 132 133 ```hcl 134 artifact { 135 source = "https://example.com/file.tar.gz" 136 options { 137 archive = false 138 } 139 } 140 ``` 141 142 ### Download and Verify Checksums 143 144 This example downloads an artifact and verifies the resulting artifact's 145 checksum before proceeding. If the checksum is invalid, an error will be 146 returned. 147 148 ```hcl 149 artifact { 150 source = "https://example.com/file.zip" 151 152 options { 153 checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33" 154 } 155 } 156 ``` 157 158 ### Download from an S3-compatible Bucket 159 160 These examples download artifacts from Amazon S3. There are several different 161 types of [S3 bucket addressing][s3-bucket-addr] and [S3 region-specific 162 endpoints][s3-region-endpoints]. As of Nomad 0.6 non-Amazon S3-compatible 163 endpoints like [Minio] are supported, but you must explicitly set the "s3::" 164 prefix. 165 166 This example uses path-based notation on a publicly-accessible bucket: 167 168 ```hcl 169 artifact { 170 source = "https://s3-us-west-2.amazonaws.com/my-bucket-example/my_app.tar.gz" 171 } 172 ``` 173 174 If a bucket requires authentication, it may be supplied via the `options` 175 parameter: 176 177 ```hcl 178 artifact { 179 options { 180 aws_access_key_id = "<id>" 181 aws_access_key_secret = "<secret>" 182 aws_access_token = "<token>" 183 } 184 } 185 ``` 186 187 To force the S3-specific syntax, use the `s3::` prefix: 188 189 ```hcl 190 artifact { 191 source = "s3::https://s3-eu-west-1.amazonaws.com/my-bucket-example/my_app.tar.gz" 192 } 193 ``` 194 195 Alternatively you can use virtual hosted style: 196 197 ```hcl 198 artifact { 199 source = "https://my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz" 200 } 201 ``` 202 203 [go-getter]: https://github.com/hashicorp/go-getter "HashiCorp go-getter Library" 204 [Minio]: https://www.minio.io/ 205 [s3-bucket-addr]: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro "Amazon S3 Bucket Addressing" 206 [s3-region-endpoints]: http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region "Amazon S3 Region Endpoints"