HashiConf 2024 Now streaming live from Boston! Attend for free
Sentinel
Sentinel Home

Remote Sources

There are a number of options for formatting the URL provided to the source attribute on policy and import "module" blocks. This flexibility should solve most use cases and allow for reusable policies and modules.

Supported Protocols

NOTE: All protocols are supported on the CLI, however each production Sentinel integration may not. Be sure to read the appropriate integration documentation to check the supported protocols.

  • Local filesystem
  • Git
  • Mercurial
  • HTTP
  • Amazon S3
  • Google GCP

Forced Protocols

Due to the ambiguous nature of URLs, it is possible to force a particular protocol to be used during the fetch. To achieve this, simply prefix the url with the appropriate protocol as listed below:

  • file - Local filesystem
  • git - Git
  • hg - Mercurial
  • http or https - HTTP
  • s3 - Amazon S3
  • gcp - Google GCP

Example:

git::http://github.com/hashicorp/sentinel.git

The above would download the provided HTTP URL using the Git protocol.

Protocol Options

In addition to some global options, there are options available to specific protocols to perform features such as authentication.

Subdirectories / File Pathing

When supplying URLs that point to a directory (eg. git), a subdirectory and file can be provided by suffixing the URL with // and the path. For example, if we have a git repository that has a policy, main.sentinel in the root, we could directly fetch the file by using the following:

git::https://github.com/hashicorp/sentinel-docs-example.git//main.sentinel

Or, if the file was nested in the policies folder:

git::https://github.com/hashicorp/sentinel-docs-example.git//policies/main.sentinel

Checksumming

For downloads of any protocol, you can automatically verify a checksum. To checksum a file, append a checksum query parameter to the URL. The parameter value can be in the format of type:value or just value, where type is "md5", "sha1", "sha256", "sha512" or "file" . The "value" should be the actual checksum value or download URL for "file". When type part is omitted, type will be guessed based on the length of the checksum string.

./foo.sentinel?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21
 
./foo.sentinel?checksum=b7d96c89d09d9e204f5fedc4d5d55b21
 
./foo.sentinel?checksum=file:./foo.txt.sha256sum

Unarchiving

An archive query parameter can be supplied to explicitly state what format to attempt to extract, if required. The supported formats are:

If a URL has an extension that matches one of the supported formats, it will use that format to unarchive.

./file.zip

The above would use the zip format to unarchive.

./path/to/file?archive=zip

Would force the zip format. If for some reason you required archiving to be disabled, this can also be achieved by using the false value.

./path/to/file?archive=false

Git (git)

  • ref - The Git ref to checkout. This is a ref, so it can point to a commit SHA, a branch name, etc. If it is a named ref such as a branch name, it will be updated to the latest on each get.
  • sshkey - An SSH private key to use during clones. The provided key must be a base64-encoded string. For example, to generate a suitable sshkey from a private key file on disk, you would run base64 -w0 \<file>. Note: Git 2.3+ is required to use this feature.
  • depth - The Git clone depth. The provided number specifies the last n revisions to clone from the repository.

The git getter accepts both URL-style SSH addresses like git::ssh://git@example.com/foo/bar, and "scp-style" addresses like git::git@example.com/foo/bar. In the latter case, omitting the git:: forced prefix is allowed if the username prefix is exactly git@.

The "scp-style" addresses cannot be used in conjunction with the ssh:// scheme prefix, because in that case the colon is used to mark an optional port number to connect on, rather than to delimit the path from the host.

Mercurial (hg)

  • rev - The Mercurial revision to checkout.

HTTP (http or https)

Basic Authentication

To use HTTP basic authentication, simply prepend username:password@ to the hostname in the URL such as https://Aladdin:OpenSesame@www.example.com/index.html. All special characters, including the username and password, must be URL encoded.

S3 (s3)

The following query parameters are available and will take priority when authenticating against an S3 bucket.