BastionZero Terraform Provider

terraform-provider-bastionzero is a Terraform provider for BastionZero.

Please see the documentation on the Terraform registry to learn more.

Requirements

Terraform v1.x
Go 1.20 (to build the provider plugin)
GNU Make (to run the GNUmakefile)
Bash (to run certain scripts referenced by the GNUmakefile)

Development

This section discusses how to develop the provider.

Building

git clone this repository and cd into its directory
Run make to install the provider into ${GOBIN} (defaults to ${GOPATH}/bin or ${HOME}/go/bin if ${GOPATH} is not set)

Testing

In order to test the provider, you can run

make test to run unit tests
make testacc to run unit tests and provider acceptance tests

To run the acceptance tests successfully, you must first set the following environment variables:

BASTIONZERO_API_SECRET=<insert-api-key-here>
BASTIONZERO_HOST=https://cloud.bastionzero.com/

Note: When running the acceptance tests, real API resources are created at BastionZero in the organization corresponding to the specified API key; all resources created start with the prefix tf-acc-test-. Under normal conditions, the testing framework should automatically delete the resources after they're no longer needed. If resources still remain after running the tests, you can run make sweep to delete the leftover resources.

The Terraform testing framework will spawn terraform and the provider plugin during acceptance tests. Refer to HashiCorp's developer documentation to learn more about how tests work.

The AWS Terraform provider repo has a useful guide on writing acceptance tests. HashiCorp also provides a testing patterns guide.

We also utilize the rapid library to incorporate property based testing (PBT) in some of the unit tests.

Generating documentation

Documentation is generated by using the terraform-plugin-docs library. Generated docs are stored in the docs/ directory and ingested by the Terraform Registry when a release is published. Read more about how this works on HashiCorp's provider docs page.

Note: You must publish another release (please increment version to prevent checksum errors for users) in order for the Terraform Registry to receive the updated documentation; merging to master is not sufficient.

Use make generate to generate the documentation.

The provider docs are made up of three components: schema, non-schema, and examples.

Schema To update documentation related to the schema attributes of resources and data sources, find the schema definition in the bastionzero/ source code folder and modify the Description field accordingly.

Non-schema To update the surrounding documentation such as introduction paragraphs, sub-sections, standouts/notes/highlights, subcategories, user guides, and the index page, please modify the documentation in the templates/ folder.

Examples To update the Terraform examples, please modify the corresponding *.tf file in the examples/ folder. These examples are automatically formatted when you run make generate.

Never update files in the docs/ folder directly; the CI process will complain if you do. Always run make generate before committing.

You can preview the documentation by copying the raw markdown (found in docs/) to your clipboard and pasting it here.

Example (on macOS):

cat docs/guides/ec2-bzero-deployment-guide.md | pbcopy

See .docs-links.txt for a list of links to https://docs.bastionzero.com as parsed from the provider docs. This file is automatically generated after running make generate.

Using a development build

You can use configuration file development overrides in order to test a local Terraform configuration using a dev build of the provider.

provider_installation {
  dev_overrides {
      "registry.terraform.io/bastionzero/bastionzero" = "<REPLACE_WITH_GOPATH>/bin"
  }

  # 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 {}
}

Do not run terraform init as it will fail; skip directly to terraform plan or terraform apply after modifying your dev_overrides block and running make build. You must run make build every time you make changes to the provider locally.

Also, please note that your Terraform configuration file cannot include any other provider that results in downloading from the Terraform Registry. If you want to test a local build of this provider with another provider (e.g. the aws provider), you must clone and compile the respective provider and add it to the dev_overrides block. See here for more information. You can still reference third-party modules in your Terraform configuration; running terraform init may fail, but the module should still be downloaded and you can continue with terraform apply.

Releasing

The release process is a semi-automated process powered by two GitHub Actions: release.yml and gen-release-pr.yml.

See CONTRIBUTING.md to learn more.

License

This provider is distributed under the Apache License 2.0 license found in the LICENSE file and includes open source software under a variety of other licenses.

bastionzero/terraform-provider-bastionzero