From 43afaf9b27a314c0659ee1313a909a31219c589d Mon Sep 17 00:00:00 2001 From: Ott Ramst Date: Wed, 13 Nov 2024 11:10:01 +0200 Subject: [PATCH] Proper README --- README.md | 132 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 97 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 88a787f..82717ec 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,128 @@ # Terraform Provider Vaultwarden -![Build Status](https://github.com/ottramst/terraform-provider-vaultwarden/actions/workflows/WORKFLOW-FILE/badge.svg) +![Build Status](https://github.com/ottramst/terraform-provider-vaultwarden/actions/workflows/main.yml/badge.svg) -_This template repository is built on the [Terraform Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework). The template repository built on the [Terraform Plugin SDK](https://github.com/hashicorp/terraform-plugin-sdk) can be found at [terraform-provider-scaffolding](https://github.com/hashicorp/terraform-provider-scaffolding). See [Which SDK Should I Use?](https://developer.hashicorp.com/terraform/plugin/framework-benefits) in the Terraform documentation for additional information._ +## Use of the provider -This repository is a *template* for a [Terraform](https://www.terraform.io) provider. It is intended as a starting point for creating Terraform providers, containing: +The Vaultwarden provider allows you to manage and configure [Vaultwarden](https://github.com/dani-garcia/vaultwarden), a Bitwarden server API implementation in Rust, using Terraform. -- A resource and a data source (`internal/provider/`), -- Examples (`examples/`) and generated documentation (`docs/`), -- Miscellaneous meta files. +## Requirements -These files contain boilerplate code that you will need to edit to create your own Terraform provider. Tutorials for creating Terraform providers can be found on the [HashiCorp Developer](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework) platform. _Terraform Plugin Framework specific guides are titled accordingly._ +- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.8 +- [Go](https://golang.org/doc/install) >= 1.23 -Please see the [GitHub template repository documentation](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template) for how to create a new repository from this template on GitHub. +## Getting started + +The provider supports Vaultwarden versions: +* 1.32.x +* 1.32.x +* 1.31.x +* 1.30.x +* 1.29.x +* 1.28.x +* 1.27.x +* 1.26.x +* 1.25.x + +For proper provider functionality, your Vaultwarden instance must have admin access configured. See Vaultwarden's Admin Page documentation for setup instructions. +Access to the admin API is granted via passing the `admin_token` to the provider configuration. If this is not provided, the provider will not be able to manage the `/admin` endpoints. + +### Requiring the provider + +```hcl +terraform { + required_version = ">= 1.8" + + required_providers { + vaultwarden = { + source = "ottramst/vaultwarden" + version = "~> 0.1" + } + } +} +``` -Once you've written your provider, you'll want to [publish it on the Terraform Registry](https://developer.hashicorp.com/terraform/registry/providers/publishing) so that others can use it. +### Authentication -## Requirements +The Vaultwarden provider supports the following methods of authentication: -- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0 -- [Go](https://golang.org/doc/install) >= 1.23 +* Static credentials in the provider configuration +* Environment variables -## Building The Provider +#### Static credentials -1. Clone the repository -1. Enter the repository directory -1. Build the provider using the Go `install` command: - -```shell -go install +```hcl +provider "vaultwarden" { + endpoint = "https://vaultwarden.example.com" + admin_token = "your_admin_token" +} ``` -## Adding Dependencies +#### Environment variables + +You can provide your credentials via the `VAULTWARDEN_ENDPOINT` and `VAULTWARDEN_ADMIN_TOKEN` environment variables: + +```hcl +provider "vaultwarden" {} +``` -This provider uses [Go modules](https://github.com/golang/go/wiki/Modules). -Please see the Go documentation for the most up to date information about using Go modules. +## Developing the provider -To add a new dependency `github.com/author/dependency` to your Terraform provider: +1. Clone the repository +2. Enter the repository directory +3. Build the provider using the Go `install` command: ```shell -go get github.com/author/dependency -go mod tidy +go install . ``` -Then commit the changes to `go.mod` and `go.sum`. +4. Make sure you override your `.terraformrc` file with the following content: + +```hcl +provider_installation { -## Using the provider + dev_overrides { + "ottramst/vaultwarden" = "" + } -Fill this in for each provider + # For all other providers, install them directly from their origin provider + # registries as normal. If you omit this, Terraform will _only_ use + # the dev_overrides block, and so no other providers will be available. + direct {} +} +``` -## Developing the Provider +### Updating documentation and examples -If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above). +If adding a new resource, data source or a function, make sure to update the documentation and examples in the `examples` directory. -To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. +Generate the documentation using the following command: -To generate or update documentation, run `make generate`. +```shell +make generate +```` -In order to run the full suite of Acceptance tests, run `make testacc`. +### Running acceptance tests -*Note:* Acceptance tests create real resources, and often cost money to run. +Acceptance tests require Vaultwarden and an accompanying SMTP server to be running. +Makefile is provided to run the acceptance tests: ```shell -make testacc +make docker-testacc ``` + +## Support + +This provider is maintained by the community. Issues and feature requests can be filed on the [GitHub repository](https://github.com/ottramst/terraform-provider-vaultwarden/issues). + +### Support Scope + +While we welcome bug reports and feature requests, please note: + +* The provider is community-maintained +* We cannot guarantee immediate responses to issues or feature requests +* For urgent production issues, it's recommended to use the Vaultwarden web interface directly + +## Documentation + +Full provider documentation is available on the [Terraform Registry](TODO: Add registry link).