github.com/taylorchu/nomad@v0.5.3-rc1.0.20170407200202-db11e7dd7b55/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/file" 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`), they are automatically 45 unarchived before the starting the task. 46 47 ## `artifact` Parameters 48 49 - `destination` `(string: "local/$1")` - Specifies the path to download the 50 artifact, relative to the root of the task's directory. If omitted, the 51 default value is to place the binary in `local/`. The destination is treated 52 as a directory and source files will be downloaded into that directory path. 53 54 - `options` `(map<string|string>: nil)` - Specifies configuration parameters to 55 fetch the artifact. The key-value pairs map directly to parameters appended to 56 the supplied `source` URL. Please see the [`go-getter` 57 documentation][go-getter] for a complete list of options and examples 58 59 - `source` `(string: <required>)` - Specifies the URL of the artifact to download. 60 See [`go-getter`][go-getter] for details. 61 62 ## `artifact` Examples 63 64 The following examples only show the `artifact` stanzas. Remember that the 65 `artifact` stanza is only valid in the placements listed above. 66 67 ### Download File 68 69 This example downloads the artifact from the provided URL and places it in 70 `local/file.txt`. The `local/` path is relative to the task's directory. 71 72 ```hcl 73 artifact { 74 source = "https://example.com/file.txt" 75 } 76 ``` 77 78 ### Download with Custom Destination 79 80 This example downloads the artifact from the provided URL and places it at 81 `/tmp/example.txt`, as specified by the optional `destination` parameter. 82 83 ```hcl 84 artifact { 85 source = "https://example.com/file.txt" 86 destination = "/tmp/example.txt" 87 } 88 ``` 89 90 ### Download using git 91 92 This example downloads the artifact from the provided github url and places it at 93 `local/repo`, as specified by the optional `destination` parameter. 94 95 ```hcl 96 artifact { 97 source = "git::https://github.com/example/nomad-examples" 98 destination = "local/repo" 99 } 100 ``` 101 102 To download from private repo, sshkeys need to be set. The key must be 103 base64-encoded string. Run `base64 -w0 <file>` 104 105 ```hcl 106 artifact { 107 source = "git@github.com:example/nomad-examples" 108 destination = "local/repo" 109 options { 110 sshkeys = "<string>" 111 } 112 } 113 ``` 114 115 ### Download and Unarchive 116 117 This example downloads and unarchives the result in `local/file`. Because the 118 source URL is an archive extension, Nomad will automatically decompress it: 119 120 ```hcl 121 artifact { 122 source = "https://example.com/file.tar.gz" 123 } 124 ``` 125 126 To disable automatic unarchiving, set the `archive` option to false: 127 128 ```hcl 129 artifact { 130 source = "https://example.com/file.tar.gz" 131 options { 132 archive = false 133 } 134 } 135 ``` 136 137 ### Download and Verify Checksums 138 139 This example downloads an artifact and verifies the resulting artifact's 140 checksum before proceeding. If the checksum is invalid, an error will be 141 returned. 142 143 ```hcl 144 artifact { 145 source = "https://example.com/file.zip" 146 147 options { 148 checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33" 149 } 150 } 151 ``` 152 153 ### Download from an S3 Bucket 154 155 These examples download artifacts from Amazon S3. There are several different 156 types of [S3 bucket addressing][s3-bucket-addr] and [S3 region-specific 157 endpoints][s3-region-endpoints]. 158 159 This example uses path-based notation on a publicly-accessible bucket: 160 161 ```hcl 162 artifact { 163 source = "https://s3-us-west-2.amazonaws.com/my-bucket-example/my_app.tar.gz" 164 } 165 ``` 166 167 If a bucket requires authentication, it may be supplied via the `options` 168 parameter: 169 170 ```hcl 171 artifact { 172 options { 173 aws_access_key_id = "<id>" 174 aws_access_key_secret = "<secret>" 175 aws_access_token = "<token>" 176 } 177 } 178 ``` 179 180 To force the S3-specific syntax, use the `s3::` prefix: 181 182 ```hcl 183 artifact { 184 source = "s3::https://s3-eu-west-1.amazonaws.com/my-bucket-example/my_app.tar.gz" 185 } 186 ``` 187 188 Alternatively you can use virtual hosted style: 189 190 ```hcl 191 artifact { 192 source = "https://my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz" 193 } 194 ``` 195 196 [go-getter]: https://github.com/hashicorp/go-getter "HashiCorp go-getter Library" 197 [s3-bucket-addr]: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro "Amazon S3 Bucket Addressing" 198 [s3-region-endpoints]: http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region "Amazon S3 Region Endpoints"