diff --git a/book.toml b/book.toml index daaf5a4..93f9509 100644 --- a/book.toml +++ b/book.toml @@ -47,3 +47,4 @@ follow-web-links = false # Redirecting because of typos and restructuring "getting-startet-with-nix-flakes.html" = "getting-started-with-flakes.html" +"flakes.html" = "getting-started-with-flakes.html" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index df01afc..c09f6a4 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -12,7 +12,6 @@ - [Functions](functions.md) - [`evalTerranixConfiguration`](eval-terranix-configuration.md) - [Modules](modules.md) -- [terranix via nix flakes](flakes.md) # News diff --git a/src/flakes.md b/src/flakes.md deleted file mode 100644 index d27d102..0000000 --- a/src/flakes.md +++ /dev/null @@ -1,119 +0,0 @@ -terranix is available via the [nix flakes](https://nixos.wiki/wiki/Flakes). - -
-If you don’t know what NixOS or -Terraform is, have a look at -what terranix is. -
- -## Using terranix via flakes - -You can check out an example using the `template` feature of nix flakes. - -```shell -nix flake init --template github:terranix/terranix-examples -``` - -## Using terranixConfiguration - -You can render the `config.tf.json` using the `lib.terranixConfiguration`. - -Here is a minimal `flake.nix` - -```nix -{ - inputs.terranix.url = "github:terranix/terranix"; - outputs = { terranix, ... }: - let - system = "x86_64-linux"; - in - { - defaultPackage.${system} = terranix.lib.terranixConfiguration { - inherit system; - modules = [ ./config.nix ]; - }; - }; -} -``` - -You can run `nix build -o config.tf.json`, which should create a `config.tf.json` -in your current folder. -Now you are ready to run `terraform`. - -### Import terranix modules - -You can include a terranix module like a `nixosModule` with flakes. - -```nix -inputs.github.url = "github:terranix/terranix-module-github"; -... -terraformConfiguration = terranix.lib.terranixConfiguration{ - inherit system; - modules = [ - github.terranixModule - ./config.nix - ]; -}; -``` - -## Writing terranix modules - -If you want to create your own terranix module -you can start with the module template from `terranix-examples` - -```shell -nix flake init --template "github:terranix/terranix-examples#module" -``` - -terranix modules should obey the following output structure: - -- `terranixModules.` -- `terranixModule` : contains all `terranixModules` combined of the given flake. - -### using terranixOptions - -It's good practise to provide a `options.json` and `options.md` on the top of your -Repository. -The function `lib.terranixOptions` renders a `options.json` which contains a lot of information, -which can be easily queried by [jq](https://stedolan.github.io/jq/manual/). - -For example you can pull the options.json of the -[terranix github module](https://github.com/terranix/terranix-module-github) - -```shell - curl https://raw.githubusercontent.com/terranix/terranix-module-github/main/options.json | \ - jq 'to_entries | .[] | - { - label: .key, - type: .value.type, - description: .value.description, - example: .value.example | tojson, - default: .value.default | tojson, - defined: .value.declarations[0].path, - url: .value.declarations[0].url, - }' | \ - jq -s '{ options: . }' -``` - -## Using terranixConfigurationAst or terranixOptionsAst - -If you want to get deeper insides in the output of `terranixConfiguration` or `terranixOptions` -you can make use of the `terranixConfigurationAst` or the `terranixOptionsAst` function. - -Here is a simple example of using `nix repl` and `terranixConfigurationAst`. - -```nix -nix-repl> terranixAst = (builtins.getFlake "github:terranix/terranix").lib.terranixConfigurationAst -nix-repl> terranix = terranixAst { - system = "x86_64-linux"; - modules = [{ - resource.local_file = { - content = "yolo"; - filename = "./example"; - }; - }]; -} -nix-repl> terranix.config.resource.local_file -{ content = "yolo"; filename = "./example"; } - -``` diff --git a/src/getting-started-with-flakes.md b/src/getting-started-with-flakes.md index 553428d..9e8d471 100644 --- a/src/getting-started-with-flakes.md +++ b/src/getting-started-with-flakes.md @@ -3,12 +3,19 @@ [Nix flakes](https://nixos.wiki/wiki/Flakes) make dependency management of modules and packages much easier. -Deeper look at terranix and nix flakes is done in the -[flake chapter](flakes.md). +## Quick start from template + +The fastest way to get started is with the terranix flake template: + +```shell +nix flake init --template github:terranix/terranix-examples +``` + +This creates a `flake.nix` and `config.nix` you can build right away. ## A minimal flake.nix -Extending [Getting started](./getting-started.md), this minimal flake your terranix resources are defined in `config.nix`: +Extending [Getting started](./getting-started.md), this minimal flake defines your terranix resources in `config.nix`: ```nix { @@ -98,3 +105,26 @@ You can create Nix flake _apps_ that let you run: }; } ``` + +## Writing terranix modules + +You can scaffold a new terranix module with: + +```shell +nix flake init --template "github:terranix/terranix-examples#module" +``` + +A terranix module flake should provide the following outputs: + +- `terranixModules.` — individual modules +- `terranixModule` — all `terranixModules` combined + +The function `lib.terranixOptions` can render an `options.json` for your module, +which is useful for generating documentation. See the +[terranix-module-github](https://github.com/terranix/terranix-module-github) +repository for an example. + +For more on the module system itself, see the [Modules](modules.md) page. + +As a next step, read [terranix and flake modules](./terranix-and-flake-modules.md) +to use flake-parts to manage terranix configurations declaratively diff --git a/src/modules.md b/src/modules.md index 041c531..9372299 100644 --- a/src/modules.md +++ b/src/modules.md @@ -81,7 +81,8 @@ config = mkAssert (cfg.parameter != "fail") "parameter is set to fail!" { }; ``` -## provide terranix modules using nix flakes +## Provide terranix modules using nix flakes Have a look at -[the flake documentation](flakes.md#writing-terranix-modules). +[Writing terranix modules](getting-started-with-flakes.md#writing-terranix-modules) +in the flakes documentation. diff --git a/src/news-2021-11-17_release-2.5.2.md b/src/news-2021-11-17_release-2.5.2.md index c48ed8a..5ec559d 100644 --- a/src/news-2021-11-17_release-2.5.2.md +++ b/src/news-2021-11-17_release-2.5.2.md @@ -13,5 +13,5 @@ for your input on this release. - add terranixOptionAst Have a look at -[the flakes documentation](flakes.md#using-terranixconfigurationast-or-terranixconfigurationast) +[Evaluating terranix configurations](eval-terranix-configuration.md) if you want to know how to use these functions.