{"id":27958431,"url":"https://github.com/determinatesystems/nixos-vault-service","last_synced_at":"2026-03-08T12:37:01.187Z","repository":{"id":37022388,"uuid":"462811158","full_name":"DeterminateSystems/nixos-vault-service","owner":"DeterminateSystems","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-23T17:33:32.000Z","size":170,"stargazers_count":51,"open_issues_count":12,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-23T17:41:28.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeterminateSystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-02-23T16:13:02.000Z","updated_at":"2025-04-23T16:54:34.000Z","dependencies_parsed_at":"2023-10-15T22:02:24.606Z","dependency_job_id":"e0f0db58-af27-4c46-9ad2-73a5edbd0f49","html_url":"https://github.com/DeterminateSystems/nixos-vault-service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Fnixos-vault-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Fnixos-vault-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Fnixos-vault-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Fnixos-vault-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeterminateSystems","download_url":"https://codeload.github.com/DeterminateSystems/nixos-vault-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252932370,"owners_count":21827285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-07T18:23:50.162Z","updated_at":"2026-03-08T12:37:01.147Z","avatar_url":"https://github.com/DeterminateSystems.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nixos-vault-service\n\nThe NixOS Vault Service module is a NixOS module that allows easily integrating\nVault with existing systemd services.\n\n\u003e **NOTE**: The goal is not magic, so some services may need to be changed or patched.\n\n## Usage\n\n### With Flakes\n\n```nix\n# flake.nix\n{\n  inputs.nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n  inputs.vaultModule = {\n    url = \"github:DeterminateSystems/nixos-vault-service/main\";\n    inputs.nixpkgs.follows = \"nixpkgs\";\n  };\n\n  outputs = { self, nixpkgs, vaultModule }: {\n    nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {\n      system = \"x86_64-linux\";\n      modules = [\n        vaultModule.nixosModule\n        ./configuration.nix\n      ];\n    };\n  };\n}\n```\n\n### Without Flakes\n\nThere are many ways to make this module available in your system configuration\nwithout flakes. This is an example of just one possible method:\n\n```nix\n# vault.nix\nlet\n  vaultModuleSrc = builtins.fetchGit {\n    url = \"https://github.com/DeterminateSystems/nixos-vault-service.git\";\n    ref = \"main\";\n  };\n\n  vaultModule = import vaultModuleSrc;\nin\n{\n  imports = [ vaultModule.nixosModule ];\n}\n```\n\n## Configuration\n\nAfter you have the module imported by your system's configuration, you can now\nbeing integrating your services with Vault.\n\n### Options\n\n* `detsys.vaultAgent.defaultAgentConfig` (optional, default: `{ }`) \u0026ndash; The default configuration for all Vault agents. Defers to individual service's `agentConfig`, if set. See [`agentConfig` options](#agentconfig-options) for more information.\n* `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.enable` (optional, default: `false`) \u0026ndash; Whether to enable Vault integration with the service specified by `\u003cservice-name\u003e`.\n* `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.agentConfig` (optional, default: `{ }`) \u0026ndash; The Vault agent configuration for this service. See [`agentConfig` options](#agentconfig-options) for more information.\n* `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.environment` (optional, default: `{ }`) \u0026ndash; Environment variable secret configuration.\n  * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.environment.changeAction` (optional, default: `\"restart\"`) \u0026ndash; What action to take if any secrets in the environment change. One of `\"restart\"`, `\"stop\"`, or `\"none\"`.\n  * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.environment.templateFiles` (optional, default: `{ }`) \u0026ndash; Set of files containing environment variables for Vault to template.\n    * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.environment.templateFiles.\u003cfilename\u003e.file` (required) \u0026ndash; The file containing the environment variable(s) for Vault to template.\n  * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.environment.template` (optional, default: `null`) \u0026ndash; A multi-line string containing environment variables for Vault to template.\n* `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.secretFiles` (optional, default: `{ }`) \u0026ndash; Secret file configuration.\n  * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.secretFiles.defaultChangeAction` (optional, default: `\"restart\"`) \u0026ndash; What action to take if any secrets in any of these files change. One of `\"restart\"`, `\"reload\"`, `\"stop\"`, or `\"none\"`.\n  * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.secretFiles.files` (optional: default `{ }`) \u0026ndash; Set of files for Vault to template.\n    * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.secretFiles.files.\u003cfilename\u003e.changeAction` (optional, default: the `defaultChangeAction`) \u0026ndash; What action to take if the secret file changes. One of `\"restart\"`, `\"reload\"`, `\"stop\"`, or `\"none\"`.\n    * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.secretFiles.files.\u003cfilename\u003e.templateFile` (optional, default: `null`) \u0026ndash; A file containing a Vault template. Conflicts with `template`.\n    * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.secretFiles.files.\u003cfilename\u003e.template` (optional, default: `null`) \u0026ndash; A string containing a Vault template. Conflicts with `templateFile`.\n    * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.secretFiles.files.\u003cfilename\u003e.perms` (optional, default: `\"0400\"`) \u0026ndash; The octal mode of the secret file.\n    * `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.secretFiles.files.\u003cfilename\u003e.path` (read-only) \u0026ndash; The path to the secret file inside `\u003cservice-name\u003e`'s namespace's `PrivateTmp`.\n\n#### `agentConfig` options\n\nThe `agentConfig` options are partially typed in order to allow us to set defaults, as well as prevent users from using obviously broken configurations.\n\nThese options apply for both `detsys.vaultAgent.defaultAgentConfig` and `detsys.vaultAgent.systemd.services.\u003cservice-name\u003e.agentConfig`.\n\n* `agentConfig.auto_auth` (optional, default: `{ }`) \u0026ndash; The Vault agent's `auto_auth` configuration.\n* `agentConfig.auto_auth.method` (optional, default: `[ ]`) \u0026ndash; The `auto_auth`'s `method` configuration. Note that this does not support the HCL-esque way of defining this option with `method \"aws\" { ... }` -- you must specify the `type` and `config` separately.\n* `agentConfig.auto_auth.method.[].type` (required) \u0026ndash; The `auto_auth.method`'s type.\n* `agentConfig.auto_auth.method.[].config` (required) \u0026ndash; The `auto_auth.method`'s configuration.\n* `agentConfig.template_config` (optional, default: `{ }`) \u0026ndash; The Vault agent's `template_config` configuration.\n* `agentConfig.template_config.exit_on_retry_failure` (optional, default: `true`) \u0026ndash; Whether or not to exit the Vault agent when it fails to retry any further. Must be true.\n\nAny options not listed here may be manually specified, but will not be type-checked.\n\nFor example, to specify the `cache.use_auto_auth_token` option, you would only need to specify `agentConfig.cache.use_auto_auth_token = true;`.\n\n### Examples\n\n#### Demonstrating all the options\n\n```nix\n{\n  detsys.vaultAgent.defaultAgentConfig = {\n    # The configuration passed to `vault agent` -- will be converted to JSON.\n    # This is where your `vault`, `auto_auth`, `template_config`, etc., configuration should go.\n  };\n\n  detsys.vaultAgent.systemd.services.\"service-name\" = {\n    enable = true;\n\n    agentConfig = {\n      # Overrides the entirety of `detsys.vaultAgent.defaultAgentConfig`.\n    };\n\n    environment = {\n      changeAction = \"restart\";\n\n      templateFiles = {\n        \"example-a\".file = ./example-a.ctmpl;\n        \"example-b\".file = ./example-b.ctmpl;\n      };\n\n      template = ''\n        EXAMPLE_C={{ with secret \"secret/super_secret\" }}{{ .Data.c }}{{ end }}\n        EXAMPLE_D={{ with secret \"secret/super_secret\" }}{{ .Data.d }}{{ end }}\n      '';\n    };\n\n    secretFiles = {\n      defaultChangeAction = \"restart\";\n\n      files.\"example-e\" = {\n        changeAction = \"reload\";\n        perms = \"0440\";\n\n        # NOTE: You can only use either:\n        templateFile = ./example-e.ctmpl;\n        # or:\n        template = ''\n          {{ with secret \"secret/super_secret\" }}{{ .Data.e }}{{ end }}\n        '';\n        # but not both.\n      };\n\n      files.\"example-f\".template = ''\n        {{ with secret \"secret/super_secret\" }}{{ .Data.f }}{{ end }}\n      '';\n    };\n  };\n}\n```\n\n#### Default Vault Agent configuration\n\nYou can set the default `agentConfig` for all units by using the `detsys.vaultAgent.defaultAgentConfig` interface.\n\n\u003e **NOTE**: Manually-specified unit `agentConfig`s will override _**all**_ of the the settings specified in the `detsys.vaultAgent.defaultAgentConfig` option.\n\n\u003e **NOTE**: Some of these options _must_ be wrapped in a list (e.g. see `auto_auth`) in order for the generated JSON to be valid. Wrapping them all in a list doesn't hurt.\n\n```nix\n{\n  detsys.vaultAgent.defaultAgentConfig = {\n    vault = { address = \"http://127.0.0.1:8200\"; };\n    auto_auth = {\n      method = [{\n        type = \"approle\";\n        config = {\n          remove_secret_id_file_after_reading = false;\n          role_id_file_path = \"/role_id\";\n          secret_id_file_path = \"/secret_id\";\n        };\n      }];\n    };\n    template_config = {\n      static_secret_render_interval = \"5s\";\n    };\n  };\n}\n```\n\n#### Accessing the path of a file in `secretFiles`\n\nAll `secretFiles.files.\u003cNAME\u003e` expose a `path` attribute, so you don't need to memorize where the secrets are written to:\n\n```nix\n{ config, ... }:\n{\n  detsys.vaultAgent.systemd.services.prometheus = {\n    enable = true;\n\n    secretFiles.files.\"vault.token\".template = ''\n      {{ with secret \"secrets/nginx-basic-auth\"}}\n      {{ .Data.data.htpasswd }}\n      {{ end }}\n    '';\n  };\n}\n```\n\nYou can then access the path to the above `vault.token` secret file via `config.detsys.vaultAgent.systemd.services.prometheus.secretFiles.files.\"vault.token\".path`.\n\n### How to override systemd service configuration\n\nBy using the NixOS module system, it is possible to override the sidecar's systemd service configuration (e.g. to tune how often the service is allowed to restart):\nSidecar unit names follow the pattern of `detsys-vaultAgent-${service-name}`.\n\n```nix\n{\n  detsys.vaultAgent.systemd.services.prometheus = {\n    enable = true;\n\n    secretFiles = {\n      defaultChangeAction = \"none\";\n      files.\"vault.token\".templateFile = ./vault-token.ctmpl;\n    };\n  };\n\n  systemd.services.detsys-vaultAgent-prometheus = {\n    unitConfig = {\n      StartLimitIntervalSec = 300;\n      StartLimitBurst = 10;\n    };\n\n    serviceConfig = {\n      RestartSec = 30;\n      Restart = \"always\";\n    };\n  };\n}\n```\n\n## Running tests\n\nWe have tests for the module's definition, helpers, and implementation. These can be run like so:\n\n```bash\nnix-instantiate --strict --eval --json ./default.nix -A checks.definition\nnix-instantiate --strict --eval --json ./default.nix -A checks.helpers\nnix-build ./default.nix -A checks.implementation\n```\n\n### Tips for writing tests\n\nTo read the secret file (e.g. to verify the contents), you will need to join the namespace of the sidecar vaultAgent unit:\n\n```bash\nsystemd-run -p JoinsNamespaceOf=detsys-vaultAgent-serviceName.service -p PrivateTmp=true cat /tmp/detsys-vault/some-secret-file\n```\n\n# License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeterminatesystems%2Fnixos-vault-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeterminatesystems%2Fnixos-vault-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeterminatesystems%2Fnixos-vault-service/lists"}