|
| 1 | +# Getting Started |
| 2 | + |
| 3 | +Let's have a quick overview on how you could use terranix. |
| 4 | + |
| 5 | +If you look for working examples, check out [examples at GitHub](https://github.com/terranix/terranix-examples). |
| 6 | + |
| 7 | +If you don’t know what [Terraform][tf] is, have a look at |
| 8 | +<a href="what-is-terranix.html">What is Terraform / OpenTofu?</a> |
| 9 | + |
| 10 | +This guide assumes you have Nix installed. If you don't have, check [Determinate Nix installer][det-nix]. |
| 11 | + |
| 12 | +[tf]: https://terraform.io |
| 13 | +[det-nix]: https://github.com/DeterminateSystems/nix-installer#determinate-nix-installer |
| 14 | + |
| 15 | +## shell.nix |
| 16 | + |
| 17 | +One way to get started is to create a `shell.nix` |
| 18 | +that holds your terranix and terraform setup. |
| 19 | + |
| 20 | +```nix |
| 21 | +{ pkgs ? import <nixpkgs> { } }: |
| 22 | +let |
| 23 | + hcloud_token = "..."; |
| 24 | + tf = pkgs.writers.writeBashBin "tf" '' |
| 25 | + export TF_VAR_hcloud_token="${hcloud_token}" |
| 26 | + ${pkgs.opentofu}/bin/tofu "$@" |
| 27 | + ''; |
| 28 | +in pkgs.mkShell { |
| 29 | + buildInputs = [ pkgs.terranix tf ]; |
| 30 | +} |
| 31 | +``` |
| 32 | + |
| 33 | +This installs both terranix and opentofu. |
| 34 | + |
| 35 | +It also creates a `tf` CLI wrapper that embeds an API key. |
| 36 | + |
| 37 | +You want to avoid putting the API token(s) directly into shell.nix. |
| 38 | + |
| 39 | +But that can be done in a number of ways. |
| 40 | + |
| 41 | +## config.nix |
| 42 | + |
| 43 | +Create a `config.nix` that holds your resource definitions. |
| 44 | + |
| 45 | +This example is adapted from the pure HCL example in [What is Terraform / OpenTofu?](./what-is-terranix.md): |
| 46 | + |
| 47 | +```nix |
| 48 | +{ lib, ... }: |
| 49 | +{ |
| 50 | + # Control the API token with a variable to hide it from version control |
| 51 | + variable.hcloud_token = { |
| 52 | + sensitive = true; |
| 53 | + }; |
| 54 | +
|
| 55 | + # Configure the Hetzner Cloud Provider |
| 56 | + provider.hcloud = { |
| 57 | + token = "\${var.hcloud_token}"; |
| 58 | + }; |
| 59 | +
|
| 60 | + resource.hcloud_server.my_server = { |
| 61 | + image = "debian-12"; |
| 62 | + name = "myserver.example.org"; |
| 63 | + server_type = "cx22"; |
| 64 | + datacenter = "nbg1-dc3"; |
| 65 | + ssh_keys = [ "\${hcloud_ssh_key.my_key.id}" ]; |
| 66 | + public_net = { |
| 67 | + ipv4_enabled = true; |
| 68 | + ipv6_enabled = true; |
| 69 | + }; |
| 70 | + }; |
| 71 | +
|
| 72 | + resource.hcloud_ssh_key.my_key = { |
| 73 | + name = "my-ssh-key"; |
| 74 | + public_key = ''''${file("~/.ssh/id_ed25519.pub")}''; |
| 75 | + }; |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +<div class="warning"> |
| 80 | +<b>Escaping string interpolation:</b> Since both Terraform and Nix use the same string |
| 81 | +interpolation syntax, <code>${}</code>, it is necessary to escape Terraform literal |
| 82 | +<code>${}</code> references so that they don't get picked up by Nix. This happens in two |
| 83 | +different ways in the example above: |
| 84 | + |
| 85 | +- `"\${var.hcloud_token}"`: Escaping here is necessary; `${var.hcloud_token}` is a Terraform string that gets interpreted when running `plan` or `apply`. If it were not escaped, it would result in a "variable not found" error in Nix, since `var` is not a Nix variable. |
| 86 | + |
| 87 | + It could also have been written as `lib.tf.ref "var.hcloud_token"` |
| 88 | + |
| 89 | +- `''''${file("~/.ssh/id_ed25519.pub")}''`: Because the Terraform expression contains double quotes, a Nix multi-line string is used to avoid also escaping the double quotes. Escaping a Nix `${...}` expression inside a multi-line string looks like `''${...}`, i.e. instead of a backslash, two single quotes escape the string interpolation. |
| 90 | + |
| 91 | + It could also have been written as `"\${file(\"~/.ssh/id_ed25519.pub\")}"`. |
| 92 | + |
| 93 | +The resulting Terraform JSON contains strings that contain these string interpolations. |
| 94 | + |
| 95 | +</div> |
| 96 | + |
| 97 | +## Create a Server |
| 98 | + |
| 99 | +Convert `config.nix` into Terraform JSON, `init` the Terraform provider, and `apply` the configuration: |
| 100 | + |
| 101 | +```shell |
| 102 | +terranix config.nix > config.tf.json |
| 103 | +tf init |
| 104 | +tf apply |
| 105 | +``` |
| 106 | + |
| 107 | +Note that the `tf` binary assumes the wrapper from shell.nix. |
| 108 | + |
| 109 | +Use `terraform` or `tofu` if you installed either of them plainly. |
| 110 | + |
| 111 | +## Destroy a Server |
| 112 | + |
| 113 | +cleaning everything up is the job of terraform. |
| 114 | + |
| 115 | +```shell |
| 116 | +tf destroy |
| 117 | +``` |
0 commit comments