From 1506d9a610dd31276324174ea9ce5518ff9fe99d Mon Sep 17 00:00:00 2001 From: Dustin Strobel Date: Sun, 20 Oct 2024 09:49:33 +0200 Subject: [PATCH 1/3] docs: update readme --- README.md | 86 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 5f976d5..12b8bdd 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,17 @@ # Terraform Provider Windows + [![Build][build badge]][build page] [![GoReport][goreport badge]][goreport page] [![Conventional Commits][convention badge]][convention page] -Terraform provider to manage Windows based resources. - -## Requirements - -- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0 -- [Go](https://golang.org/doc/install) >= 1.22 - -## Building The Provider - -1. Clone the repository -1. Enter the repository directory -1. Build the provider using the Go `install` command: - -```shell -go install -``` - -## Adding Dependencies - -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. +This Terraform provider enables the management of Windows-based resources within your infrastructure. -To add a new dependency `github.com/author/dependency` to your Terraform provider: - -```shell -go get github.com/author/dependency -go mod tidy -``` +It is built on top of the [gowindows](https://github.com/d-strobel/gowindows) SDK, +which acts as the underlying interface for interacting with Windows environments. -Then commit the changes to `go.mod` and `go.sum`. +To introduce new features or enhancements to this provider, the corresponding functionality must first be implemented in the gowindows library. +Contributions or feature requests should therefore begin with updates to the GoWindows SDK before being integrated into the provider. ## Using the provider @@ -69,20 +47,62 @@ resource "windows_local_user" "this" { ## Developing the Provider -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). +### Pre-commit + +To ensure smooth execution in the pipeline and eliminate potential linting errors, +it's highly advisable to integrate pre-commit hooks. These hooks can be effortlessly +installed to streamline the process and maintain code quality standards. + +You can find more details about pre-commit hooks on their official website: [pre-commit](https://pre-commit.com/). + +### Conventional Commits -To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. +This Terraform provider follows the conventional commit guidelines. For more information, see [conventionalcommits.org](https://www.conventionalcommits.org/). -To generate or update documentation, run `go generate`. +### Acceptance test -In order to run the full suite of Acceptance tests, run `make testacc`. +> The acceptance tests are currently not available via Github action. -*Note:* Acceptance tests create real resources, and often cost money to run. +#### Prerequisites + +* [Terraform](https://developer.hashicorp.com/terraform/downloads) +* [OpenTofu](https://opentofu.org/docs/intro/install) +* [Go](https://golang.org/doc/install) +* [Hashicorp Vagrant](https://www.vagrantup.com/) +* [Oracle VirtualBox](https://www.virtualbox.org/) + +#### Usage + +Boot the Vagrant machines: + +```shell +make vagrant-up +``` + +Run acceptance tests for terraform and opentofu: ```shell make testacc ``` +Destroy the Vagrant machines: + +```shell +make vagrant-down +``` + +### + +## Inspirations + +* [hashicorp - terraform-provider-ad](https://github.com/hashicorp/terraform-provider-ad):
+ +Hashicorp made a great start with the terraform-provider-ad. Currently, it seems that the provider is not actively maintained.
+Beyond that, my goal is to split the terraform-provider into a library and a provider and extend its functionality with non Active-Directory systems. + +## License +This project is licensed under the [Mozilla Public License Version 2.0](LICENSE). + [goreport badge]: https://goreportcard.com/badge/github.com/d-strobel/terraform-provider-windows [goreport page]: https://goreportcard.com/report/github.com/d-strobel/terraform-provider-windows From 88d7a2f8c41c275fe1221ec0470af9a79c05d85f Mon Sep 17 00:00:00 2001 From: Dustin Strobel Date: Sun, 20 Oct 2024 11:19:17 +0200 Subject: [PATCH 2/3] docs: update readme with code generating section --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 12b8bdd..c9fbad8 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ This Terraform provider follows the conventional commit guidelines. For more inf * [Hashicorp Vagrant](https://www.vagrantup.com/) * [Oracle VirtualBox](https://www.virtualbox.org/) -#### Usage +#### Run tests Boot the Vagrant machines: @@ -91,7 +91,46 @@ Destroy the Vagrant machines: make vagrant-down ``` -### +### Code Generation + +Some parts of this provider are automatically generated using the [terraform-plugin-codegen-framework](https://github.com/hashicorp/terraform-plugin-codegen-framework). + +#### Schema + +The schemas for providers, resources, and data sources are defined as JSON files located in the [internal/schema](./internal/schema) directory. + +To generate the corresponding code, simply run `go generate`.
+This will execute all commands in the [main.go](./main.go) file that are prefixed with the following syntax: `//go:generate `. + +If you are adding a new resource within an existing subpackage, update the JSON schema in the respective subpackage file. + +For a new subpackage, you’ll need to create a new file for the resources and data sources.
+Additionally, you'll also need to add the appropriate code generation commands in the [main.go](./main.go) file. + +#### Scaffolding + +Once the schema code is generated, you may want to create the data source or resource files that utilize the generated code. + +To help with this, you can use the scaffold command from the terraform-plugin-codegen-framework to initially generate these files.
+Since the scaffolded files require manual modification, you only need to generate them once. + +* Create a Resource + +```shell +tfplugingen-framework scaffold resource --name subpackage_resource_name --output-dir internal/provider/subpackage --package subpackage +``` + +* Create a Datasources + +```shell +tfplugingen-framework scaffold data-source --name subpackage_datasource_name --output-dir internal/provider/subpackage --package subpackage +``` + +After generating the files, update them as needed. +Review the existing resources and data sources for guidance on what changes to make initially. + +Finally, implement the CRUD operation logic in the corresponding functions, +and don’t forget to add acceptance tests to validate the functionality (see [Acceptance tests](#Acceptance test) ## Inspirations From 215ad5f72a9ed1f92fe612daf2833e6cd9ab2a88 Mon Sep 17 00:00:00 2001 From: Dustin Strobel Date: Sun, 20 Oct 2024 11:38:53 +0200 Subject: [PATCH 3/3] docs: update readme --- README.md | 71 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 37 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index c9fbad8..0898ca2 100644 --- a/README.md +++ b/README.md @@ -59,38 +59,6 @@ You can find more details about pre-commit hooks on their official website: [pre This Terraform provider follows the conventional commit guidelines. For more information, see [conventionalcommits.org](https://www.conventionalcommits.org/). -### Acceptance test - -> The acceptance tests are currently not available via Github action. - -#### Prerequisites - -* [Terraform](https://developer.hashicorp.com/terraform/downloads) -* [OpenTofu](https://opentofu.org/docs/intro/install) -* [Go](https://golang.org/doc/install) -* [Hashicorp Vagrant](https://www.vagrantup.com/) -* [Oracle VirtualBox](https://www.virtualbox.org/) - -#### Run tests - -Boot the Vagrant machines: - -```shell -make vagrant-up -``` - -Run acceptance tests for terraform and opentofu: - -```shell -make testacc -``` - -Destroy the Vagrant machines: - -```shell -make vagrant-down -``` - ### Code Generation Some parts of this provider are automatically generated using the [terraform-plugin-codegen-framework](https://github.com/hashicorp/terraform-plugin-codegen-framework). @@ -129,8 +97,43 @@ tfplugingen-framework scaffold data-source --name subpackage_datasource_name --o After generating the files, update them as needed. Review the existing resources and data sources for guidance on what changes to make initially. -Finally, implement the CRUD operation logic in the corresponding functions, -and don’t forget to add acceptance tests to validate the functionality (see [Acceptance tests](#Acceptance test) +Once the CRUD operation logic is implemented in the corresponding functions, +ensure that the `New...Resource` or `New...DataSource` function is called in the [provider.go](./internal/provider/provider.go) +file under the appropriate `Resources` or `DataSources` function. + +Finally, don’t forget to add acceptance tests to validate the functionality (see section [Acceptance Test](#acceptance-test)). + +### Acceptance test + +> The acceptance tests are currently not available via Github action. + +#### Prerequisites + +* [Terraform](https://developer.hashicorp.com/terraform/downloads) +* [OpenTofu](https://opentofu.org/docs/intro/install) +* [Go](https://golang.org/doc/install) +* [Hashicorp Vagrant](https://www.vagrantup.com/) +* [Oracle VirtualBox](https://www.virtualbox.org/) + +#### Run tests + +Boot the Vagrant machines: + +```shell +make vagrant-up +``` + +Run acceptance tests for terraform and opentofu: + +```shell +make testacc +``` + +Destroy the Vagrant machines: + +```shell +make vagrant-down +``` ## Inspirations