Merge pull request #1 from jackivanov/docs

Docs & tests

.github/workflows/lint.yml

@@ -5,6 +5,9 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -16,13 +19,15 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v5
       with:
-        go-version: 1.20
+        go-version: "1.20"
 
     - name: Install Make
       run: sudo apt-get install make
 
-    - name: Run make lint
-      run: make lint
+    - name: golangci-lint
+      uses: golangci/golangci-lint-action@v3
+      with:
+        version: "v1.55"
 
     - name: Run make testacc
       run: make testacc

GNUmakefile

@@ -4,3 +4,14 @@ default: testacc
 .PHONY: testacc
 testacc:
 	TF_ACC=1 go test ./... -v $(TESTARGS) -timeout 120m
+
+# Generate docs
+generate:
+	cd tools; go generate ./..
+
+# See https://golangci-lint.run/
+lint:
+	golangci-lint run
+
+fmt:
+	go fmt ./...

README.md

@@ -0,0 +1,88 @@
+# Terraform Provider: x25519
+
+The x25519 provider offers functionalities for handling Curve25519 keys, specifically for generating private and public keys. It facilitates the creation of private x25519 keys and the corresponding public keys, primarily designed for use in scenarios like generating WireGuard VPN keys.
+
+It provides resources that enable the seamless integration of private x25519 keys and the associated public keys into your Terraform deployments.
+
+## Documentation, questions and discussions
+
+Official documentation on how to use this provider can be found on the
+[Terraform Registry](https://registry.terraform.io/providers/jackivanov/x25519/latest/docs).
+
+## Requirements
+
+* [Terraform](https://www.terraform.io/downloads)
+* [Go](https://go.dev/doc/install) (1.20)
+* [GNU Make](https://www.gnu.org/software/make/)
+
+## Development
+
+### Building
+
+1. `git clone` this repository and `cd` into its directory
+2. `make` will trigger the Golang build
+
+The provided `GNUmakefile` defines additional commands generally useful during development,
+like for running tests, generating documentation, code formatting and linting.
+Taking a look at it's content is recommended.
+
+### Testing
+
+In order to test the provider, you can run
+
+* `make testacc` to run provider acceptance tests
+
+It's important to note that acceptance tests (`testacc`) will actually spawn
+`terraform` and the provider. Read more about they work on the
+[official page](https://www.terraform.io/plugin/sdkv2/testing/acceptance-tests).
+
+### Generating documentation
+
+This provider uses [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs/)
+to generate documentation and store it in the `docs/` directory.
+Once a release is cut, the Terraform Registry will download the documentation from `docs/`
+and associate it with the release version. Read more about how this works on the
+[official page](https://www.terraform.io/registry/providers/docs).
+
+Use `make generate` to ensure the documentation is regenerated with any changes.
+
+### Using a development build
+
+If [running tests and acceptance tests](#testing) isn't enough, it's possible to set up a local terraform configuration
+to use a development builds of the provider. This can be achieved by leveraging the Terraform CLI
+[configuration file development overrides](https://www.terraform.io/cli/config/config-file#development-overrides-for-provider-developers).
+
+First, use `make install` to place a fresh development build of the provider in your
+[`${GOBIN}`](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies)
+(defaults to `${GOPATH}/bin` or `${HOME}/go/bin` if `${GOPATH}` is not set). Repeat
+this every time you make changes to the provider locally.
+
+Then, setup your environment following [these instructions](https://www.terraform.io/plugin/debugging#terraform-cli-development-overrides)
+to make your local terraform use your local build.
+
+### Testing GitHub Actions
+
+This project uses [GitHub Actions](https://docs.github.com/en/actions/automating-builds-and-tests) to realize its CI.
+
+Sometimes it might be helpful to locally reproduce the behaviour of those actions,
+and for this we use [act](https://github.com/nektos/act). Once installed, you can *simulate* the actions executed
+when opening a PR with:
+
+```shell
+# List of workflows for the 'pull_request' action
+$ act -l pull_request
+
+# Execute the workflows associated with the `pull_request' action
+$ act pull_request
+```
+
+## Releasing
+
+The release process is automated via GitHub Actions, and it's defined in the Workflow
+[release.yml](./.github/workflows/release.yml).
+
+Each release is cut by pushing a [semantically versioned](https://semver.org/) tag to the default branch.
+
+## License
+
+[Mozilla Public License v2.0](./LICENSE)

docs/data-sources/public_key.md

@@ -0,0 +1,40 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "x25519_public_key Data Source - terraform-provider-x25519"
+subcategory: ""
+description: |-
+  Get a public key from a base64-encoded private key for Curve25519. (RFC 7748) https://datatracker.ietf.org/doc/html/rfc7748#section-5.
+  This resource is primarily intended for easily bootstrapping throwaway development environments.
+---
+
+# x25519_public_key (Data Source)
+
+Get a public key from a base64-encoded private key for Curve25519. [(RFC 7748)](https://datatracker.ietf.org/doc/html/rfc7748#section-5).
+
+This resource is primarily intended for easily bootstrapping throwaway development environments.
+
+## Example Usage
+
+```terraform
+resource "x25519_private_key" "example" {}
+
+data "x25519_public_key" "example" {
+  private_key = x25519_private_key.example.private_key
+}
+
+output "x25519_public_key" {
+  value = data.x25519_public_key.example
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `private_key` (String, Sensitive) Base64 encoded private key data [(RFC 7748)](https://datatracker.ietf.org/doc/html/rfc7748#section-5) format.
+
+### Read-Only
+
+- `id` (String) Unique identifier for this resource: hexadecimal representation of the SHA1 checksum of the resource.
+- `public_key` (String) Base64 encoded public key data [(RFC 7748)](https://datatracker.ietf.org/doc/html/rfc7748#section-5) format.

docs/index.md

@@ -0,0 +1,46 @@
+---
+page_title: "Provider: x25519"
+description: |-
+  The x25519 provider offers utilities for working with Curve25519 keys.
+---
+
+# X25519 Provider
+
+The x25519 provider provides utilities for working with *Curve25519*
+keys. It offers resources that enable the creation of
+private keys and the corresponding public keys as part of a Terraform deployment.
+
+This provider, on its own, may not have extensive standalone utility,
+but it serves as a valuable tool for generating credentials.
+These can be subsequently utilized with other providers when configuring resources
+that expose x25519 services or when provisioning x25519 keys for specific use cases.
+
+Use the navigation on the left to explore the available resources.
+
+## Example Usage
+
+```terraform
+terraform {
+  required_providers {
+    x25519 = {
+      source = "jackivanov/x25519"
+    }
+  }
+}
+
+resource "x25519_private_key" "example" {}
+
+output "x25519_keys" {
+  value = {
+    private_key = x25519_private_key.example.private_key
+    public_key  = x25519_private_key.example.public_key
+  }
+}
+```
+
+### Secrets and Terraform state
+
+Some resources, such as `x25519_private_key`, are considered "secrets" and are marked as *sensitive*
+by this provider to prevent unintentional leakage in logs or other outputs. However, it's crucial to
+note that the values constituting the "state" of these resources will be stored in the
+[Terraform state](https://www.terraform.io/language/state) file, including the "secrets" in an *unencrypted* form.

docs/resources/private_key.md

@@ -0,0 +1,36 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "x25519_private_key Resource - terraform-provider-x25519"
+subcategory: ""
+description: |-
+  Generates a base64-encoded private key for Curve25519. (RFC 7748) https://datatracker.ietf.org/doc/html/rfc7748#section-5.
+  This resource is primarily intended for easily bootstrapping throwaway development environments.
+---
+
+# x25519_private_key (Resource)
+
+Generates a base64-encoded private key for Curve25519. [(RFC 7748)](https://datatracker.ietf.org/doc/html/rfc7748#section-5).
+
+This resource is primarily intended for easily bootstrapping throwaway development environments.
+
+## Example Usage
+
+```terraform
+resource "x25519_private_key" "example" {}
+
+output "x25519_keys" {
+  value = {
+    private_key = x25519_private_key.example.private_key
+    public_key  = x25519_private_key.example.public_key
+  }
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `id` (String) Unique identifier for this resource: hexadecimal representation of the SHA1 checksum of the resource.
+- `private_key` (String, Sensitive) Base64 encoded private key data [(RFC 7748)](https://datatracker.ietf.org/doc/html/rfc7748#section-5) format.
+- `public_key` (String) Base64 encoded public key data [(RFC 7748)](https://datatracker.ietf.org/doc/html/rfc7748#section-5) format.

examples/data-sources/x25519_public_key/data-source.tf

@@ -0,0 +1,9 @@
+resource "x25519_private_key" "example" {}
+
+data "x25519_public_key" "example" {
+  private_key = x25519_private_key.example.private_key
+}
+
+output "x25519_public_key" {
+  value = data.x25519_public_key.example
+}

examples/provider/provider.tf

@@ -0,0 +1,16 @@
+terraform {
+  required_providers {
+    x25519 = {
+      source = "jackivanov/x25519"
+    }
+  }
+}
+
+resource "x25519_private_key" "example" {}
+
+output "x25519_keys" {
+  value = {
+    private_key = x25519_private_key.example.private_key
+    public_key  = x25519_private_key.example.public_key
+  }
+}

examples/resources/x25519_private_key/resource.tf

@@ -0,0 +1,8 @@
+resource "x25519_private_key" "example" {}
+
+output "x25519_keys" {
+  value = {
+    private_key = x25519_private_key.example.private_key
+    public_key  = x25519_private_key.example.public_key
+  }
+}