The Terraform Hydra provider is a plugin for Terraform that allows for
declarative management of a Hydra instance. You can find it on the Terraform


To use this provider, you will need the following:

NOTE: You can use this provider with commit

(at the absolute earliest), but it has a known issue where some internal
fields were not nullified, leading to state differences between Hydra and
Terraform, and is not recommended.

Getting started

To get started with this provider, you'll need to create a configuration file
that will tell Terraform to use this provider. This will look something like the
following snippet:

terraform {
  required_providers {
    hydra = {
      version = "~> 0.1"
      source  = "DeterminateSystems/hydra"

After that's done, you'll need to specify where your Hydra instance can be
reached and provide credentials for this provider to be able to work its magic:

NOTE: Hard-coded credentials are not recommended, so while it is possible
to use them (just uncomment the username and password items and fill them in
with valid values), you are urged to use the HYDRA_USERNAME and
HYDRA_PASSWORD environment variables.

provider "hydra" {
  host = "https://hydra.example.com"
  # username = "alice"
  # password = "foobar"

Now that you can connect to Hydra, it's time to create a project with the
hydra_project resource:

resource "hydra_project" "nixpkgs" {
  name         = "nixpkgs"
  display_name = "Nixpkgs"
  description  = "Nix Packages collection"
  homepage     = "https://nixos.org/nixpkgs"
  owner        = "alice"
  enabled      = true
  visible      = true

You can attach a jobset to this project with the hydra_jobset

NOTE: The check_interval is 0 for this example to prevent Hydra from
starting an evaluation on the entirety of Nixpkgs. Change this to a non-zero
value if you would like to tell Hydra it can start evaluating this jobset.

resource "hydra_jobset" "trunk-flake" {
  project     = hydra_project.nixpkgs.name
  state       = "enabled"
  visible     = true
  name        = "trunk-flake"
  type        = "flake"
  description = "master branch"

  flake_uri = "github:NixOS/nixpkgs/master"

  check_interval    = 0
  scheduling_shares = 3000
  keep_evaluations  = 3

  email_notifications = true
  email_override      = "[email protected]"

That's it for the basic usage of this provider!

You may also want to check out the example configurations inside the
examples/ directory

Importing from an existing Hydra instance

You can migrate from a hand-configured Hydra to Terraform-managed configuration
files using our included generator,

The generator enumerates the server's projects and jobsets, generating a .tf
file for each project. The generator also produces a script of terraform import commands.

The workflow is:

  1. Execute generator.sh
  2. Commit the generated .tf files to your repository
  3. Execute the generated terraform import script
  4. Discard the terraform import script, as it should not be necessary anymore

Your Terraform network and state file will now have up-to-date data for all of
your existing project and jobset resources, and a terraform plan should report
no differences were detected.

$ cd tools
$ nix-shell
# Usage: generator.sh <server-root> <out-dir> <import-file>
#     Arguments:
#         <server-root>    The root of the Hydra server to import projects and jobsets from.
#         <out-dir>        The directory to output generated Terraform configuration files to.
#         <import-file>    Where to write the generated list of 'terraform import' statements.
nix-shell$ ./generator.sh hydra.example.com outdir generated-tf-import.sh


In addition to the dependencies for using this provider, hacking on this
provider also requires the following:

Running locally

This assumes a running instance of Hydra is available.

$ nix-shell
nix-shell$ make install
nix-shell$ cd examples/default
nix-shell$ terraform init && terraform plan

Regenerating API bindings

This will fetch the latest hydra-api.yaml from Hydra and generate API bindings
against that specification.

$ nix-shell
nix-shell$ make api

Running acceptance tests locally

NOTE: You should use a throwaway Hydra instance to prevent anything
unexpected happening.

$ nix-shell
nix-shell$ HYDRA_HOST= HYDRA_USERNAME=alice HYDRA_PASSWORD=foobar make testacc


Pull requests are welcome. When submitting one, please follow the checklist in
the template to ensure everything works properly.

The typical contribution workflow is as follows:

  1. Make your change
  2. Format it with make fmt (requires goimports)
  3. Verify it builds with make build
  4. Install it with make install
  5. Spin up a local Hydra server to test with (see the Hydra documentation on
    Executing Hydra During Development)
  6. Extend one of the examples so that it will exercise your
    change (or write your own example!)
  7. Remove the .terraform.lock.hcl file (if it exists) and run terraform init && terraform apply
  8. Once everything looks good, write a test for your change
  9. Commit and open a pull request (be sure to follow the checklist in the


Q. Does this provider support Basic Authentication?

A. Yes! Just set the HYDRA_HOST environment variable to e.g.
https://user:[email protected]. You can also set the host in your
configuration to this, but hard-coded credentials are insecure and not