Thank you for your interest in contributing to the Cozystack Terraform provider!
Be respectful and constructive in all interactions. Contributors of all experience levels are welcome.
- Search existing issues before creating a new one.
- Use the issue templates for bug reports and feature requests.
- Provide as much detail as possible (provider/Terraform/Cozystack versions, configuration, plan output). Redact tokens and private infrastructure details.
- Fork the repository.
- Create a feature branch from
master. - Make your changes (add or update tests and examples).
- Ensure tests, linting, and docs generation are clean.
- Submit a pull request and fill out the template.
git clone https://github.com/cozystack/terraform-provider-cozystack.git
cd terraform-provider-cozystack
make build # build the provider binary
make test # run unit tests with the race detector
make lint # run golangci-lint
make docs # regenerate registry docs from schema + examplesRun make help to see all available targets.
To exercise the provider with a real tofu/terraform configuration before it is published, install it into your GOBIN and point a CLI config at it:
make installThen add a dev_overrides block to ~/.terraformrc (or a TF_CLI_CONFIG_FILE) mapping registry.opentofu.org/cozystack/cozystack to your GOBIN. With an override in place, run tofu plan directly — no tofu init is needed.
Acceptance tests run real CRUD against a live Cozystack cluster and are gated behind TF_ACC:
KUBECONFIG=/path/to/kubeconfig KUBE_CTX=your-context make testaccThese create and destroy real objects. Point them at a disposable test cluster, never production. The cluster name is never hard-coded — it is read from the KUBECONFIG/KUBE_CTX environment.
Most kinds are wired through the generic appResource / newClusterResource factories. When adding a kind:
- Add the
client.Resourceconstructor (GVR, scope) underinternal/client/. - Register the resource and data source in
internal/provider/provider.go. - Add a typed model only when the spec benefits from it; otherwise use the raw-JSON spec passthrough.
- Add a unit test, including the reflection spec-coverage guard where a typed model is used.
- Add
examples/resources/andexamples/data-sources/entries, then runmake docs.
This project uses Conventional Commits:
type(scope): brief description
Optional longer explanation.
| Type | Description |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation changes |
refactor |
Code refactoring |
test |
Adding or updating tests |
chore |
Maintenance tasks |
ci |
CI/CD changes |
feat(provider): add cozystack_backup_strategy resource
fix(client): retry update on resource-version conflict
docs(examples): add a kubernetes tenant example
- Follow standard Go conventions; format with
make fmt. - Lint with
golangci-lint(config in.golangci.yaml);make lintmust pass with zero errors. - If you must disable a linter, add a
//nolint:<linter> // reasondirective with a justification. - Add godoc comments to exported types and functions.
- Registry docs under
docs/are generated — do not edit them by hand. Edit the schema descriptions orexamples/, then runmake docs. - A pull request must not leave
make docsproducing a diff.
Releases are tag-driven and automated via GoReleaser in GitHub Actions: pushing a signed vX.Y.Z tag builds the multi-platform archives, signs the checksums, and publishes a GitHub Release that the Terraform Registry picks up. The provider version tracks the Cozystack API version it is built against.
By contributing, you agree that your contributions will be licensed under the BSD 3-Clause License.