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"