diff --git a/.env b/.env index 7394c189..7b16c12e 100644 --- a/.env +++ b/.env @@ -1,3 +1,6 @@ #HONEYCOMB_API_KEY= +#HONEYCOMB_KEY_ID= +#HONEYCOMB_KEY_SECRET= +#HONEYCOMB_API_ENDPOINT= #HONEYCOMB_DATASET= -TF_ACC=1 \ No newline at end of file +TF_ACC=1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 653e9307..edf993d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,9 @@ All contributions are welcome, whether they are technical in nature or not. -Feel free to open a new issue to ask questions, discuss issues or propose enhancements. You can also chat with us on the **Honeycomb Pollinators** Slack in the **#terraform-provider** channel, you can find a direct link to request an invite in [Spread the Love: Appreciating Our Pollinators Community](https://www.honeycomb.io/blog/spread-the-love-appreciating-our-pollinators-community/). +Feel free to open a new issue to ask questions, discuss bugs, or propose enhancements. + +You can also chat with us on the **Honeycomb Pollinators** Slack in the **#discuss-api-and-terraform** channel. The rest of this document describes how to get started developing on this repository. @@ -10,115 +12,107 @@ The rest of this document describes how to get started developing on this reposi ### Relevant documentation -Hashicorp has a lot of documentation on creating custom Terraform providers categorized under [Extending Terraform](https://www.terraform.io/docs/extend/index.html). This might help when getting started, but are not a pre-requisite to contribute. Feel free to just open an issue and we can guide you along the way. +Hashicorp has a lot of documentation on creating Terraform providers categorized under [Plugin Development](https://developer.hashicorp.com/terraform/plugin). +This might help when getting started, but are not a pre-requisite to contribute. +Feel free to just open an issue and we can guide you along the way. -### What's in progress and what's next? +## Contributing changes -We maintain [an activity board](https://github.com/honeycombio/terraform-provider-honeycombio/projects/1) with all the work that is currently being worked on and/or considered. Hopefully this can give a sense of what is next to come. The board is intended to create overview across the project, it's not a strict plan of action. +As there are currently no Honeycomb SDKs, this repostiory contains an embedded API Client for the [Honeycomb API](https://docs.honeycomb.io/api) +in the `client/` directory in the root of the repository. -## Contributing changes +The provider currently has a mix of the older [Plugin SDKv2](https://developer.hashicorp.com/terraform/plugin/sdkv2) +and newer [Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework) resources and data sources. +Any new additions should be built with the Plugin Framework. -### Preview document changes + * The Plugin SDK-based code is contained in the `honeycombio/` directory in the root of the repository. + * The Plugin Framework-based code is contained in the `internal/provider` directory. + +Any PRs reimplmenting Plugin SDKv2 resources or datasources in the Plugin Framework with be enthusiastically accepted. 🙏 -Hashicorp has a tool to preview documentation. Visit [registry.terraform.io/tools/doc-preview](https://registry.terraform.io/tools/doc-preview). +### Preview document changes -### Running the test +Hashicorp has a tool to preview documentation. +Visit [registry.terraform.io/tools/doc-preview](https://registry.terraform.io/tools/doc-preview). -Most of the tests are acceptance tests, which will call real APIs. To run the tests you'll need to have access to a Honeycomb account/team. If not, you can create a new free team to run the majority of the tests. +### Running the tests -Some tests, such as those for SLOs and those for the Query Data API require an Enterprise team. +Most of the tests are live integration tests against the [Honeycomb API](https://docs.honeycomb.io/api). +To run the tests you'll need to have access to a Honeycomb account and both a [Configuration Key](https://docs.honeycomb.io/get-started/best-practices/api-keys/#configuration-keys) +and a [Management Key](https://docs.honeycomb.io/get-started/best-practices/api-keys/#management-keys) with all permissions and scopes granted. -Additionally, the test for a Slack recipient requires that the Slack authorization be [set up with the team ahead of time](https://docs.honeycomb.io/working-with-your-data/triggers/#slack) +Some tests, such as those for SLOs and those for the Query Data API require access to a Pro or Enterprise team. -First, **create an API key**. This key should have the following permissions: -- Create Datasets -- Manage Queries and Columns -- Run Queries -- Manage Public Boards -- Manage SLOs -- Manage Triggers -- Manage Recipients -- Manage Markers +Additionally, tests for Slack recipients requires that the Slack authorization be [set up with the team ahead of time](https://docs.honeycomb.io/working-with-your-data/triggers/#slack) -Next, **initialize the dataset**. The helper script [setup-testsuite-dataset](scripts/setup-testsuite-dataset) will create the dataset and required columns that are used in the tests. +Next, some of the embedded client tests require that you **initialize the dataset**. +The helper script [setup-testsuite-dataset](scripts/setup-testsuite-dataset) will create the dataset and required columns that are used in the tests. You will need to use Bash 4+ to run this script. ```sh HONEYCOMB_API_KEY= HONEYCOMB_DATASET= ./scripts/setup-testsuite-dataset ``` -Finally, **run the acceptance tests** by passing the API key and dataset as environment variables: +Finally, **run the full testsuite**! +There is a `.env` file checked into the root of the repostiory which can be used to store the relevant environment variables required for the tests: + +- `HONEYCOMB_API_KEY`: a Configuration Key for a Honeycomb Team +- `HONEYCOMB_DATASET`: name of the test dataset to run tests against +- `HONEYCOMB_KEY_ID` and `HONEYCOMB_KEY_SECRET`: the v2 Management API Key pair for a Honeycomb Team + +Or alternatively, you can set them directly and run the `testacc` make target: ```sh -HONEYCOMB_API_KEY= HONEYCOMB_DATASET= make testacc +HONEYCOMB_API_KEY= HONEYCOMB_KEY_ID= HONEYCOMB_KEY_SECRET= HONEYCOMB_DATASET= make testacc ``` ### Using a locally built version of the provider -It can be handy to run terraform with a local version of the honeycombio provider. - -With **Terraform 0.12** this is very straightforward: - -- build the provider with `go build` -- copy the executable (named `terraform-provider-honeycombio`) into your working directory -- run `terraform init` +It can be handy to run terraform with a local version of the provider during development. -This is a bit more involved with **Terraform 0.13**: the provider has to be installed in one of the [local mirror directories](https://www.terraform.io/docs/commands/cli-config.html#implied-local-mirror-directories) using the [new filesysem structure](https://www.terraform.io/upgrade-guides/0-13.html#new-filesystem-layout-for-local-copies-of-providers). Additinally, the provider should have a version. - -For macOS, I've added the `install_macos` target in [`Makefile`](Makefile). Other OS's should be similar, feel free to add an additional target. +The best way to do this is with a [Development Override](https://developer.hashicorp.com/terraform/cli/config/config-file#development-overrides-for-provider-developers). +There is already a `.terraformrc.local` file checked into the root of the repostiory which may be a helpful starting point. ### Enabling log output To print logs (including full dumps of requests and their responses), you have to set `TF_LOG` to at least `debug` when running Terraform: -```sh -TF_LOG=debug HONEYCOMBIO_DEBUG=true terraform apply -``` - A handy one-liner to simultaneously write the output to a file: ```sh TF_LOG=debug terraform apply 2>&1 | tee output.log ``` -For more information, see [Debugging Terraform](https://www.terraform.io/docs/internals/debugging.html). - -### Style convention +For more information, see [Debugging Terraform](https://developer.hashicorp.com/terraform/internals/debugging). -CI will run the following tools to style code: +### Lints and Style -```sh -goimports -l -w . -go mod tidy -``` - -`goimports` will format the code like `gofmt` but will also fix imports. It can be installed with `go get golang.org/x/tools/cmd/goimports`. +This project uses `golangci-lint` with the configuration at `.golangci.yml` in the root of the repository. -Both commands should create no changes before a pull request can be merged. - -### Run GitHub Actions in your fork +### Run GitHub Actions on your fork If you fork the repository, you can also run the tests on GitHub Actions (for free since it's a public repository). Unfortunatly there is no mechanism to share secrets, so all runs will fail until the necessary secrets are configured. To properly setup the GitHub Actions, add the following secrets: -- `HONEYCOMB_API_KEY`: an API key for Honeycombio -- `HONEYCOMB_DATASET`: name of the test dataset +- `HONEYCOMB_API_KEY`: a Configuration Key for a Honeycomb Team +- `HONEYCOMB_DATASET`: name of the test dataset to run tests against +- `HONEYCOMB_KEY_ID` and `HONEYCOMB_KEY_SECRET`: the v2 Management API Key pair for a Honeycomb Team ## Release procedure -To release a new version of the Terraform provider a binary has to be built for a list of platforms ([more information](https://www.terraform.io/docs/registry/providers/publishing.html#creating-a-github-release)). This process is automated with GoReleaser and GitHub Actions. +To release a new version of the Terraform provider a binary has to be built for a list of platforms ([more information](https://developer.hashicorp.com/terraform/registry/providers/publishing#creating-a-github-release)). +This process is largely automated with GoReleaser and GitHub Actions. -- Create [a new release](https://github.com/honeycombio/terraform-provider-honeycombio/releases/new) -- The tag and release title should be a semantic version -- To follow convention of other Terraform providers the description has the following sections (each section can be omitted if empty): +The unautomated part is creating a "releast commit" which updates `CHANGELOG.md` in the root of the repository as well as the references to the build version in the various examples. -```text -NOTES: -FEATURES: -ENHANCEMENTS: -BUG FIXES: -``` +Once the release commit has landed on the `main` branch: -- After that tag has been created a GitHub Actions workflow Release will run and add binaries to the release (this workflow can run over 5 minutes) -- Once the tag is created, the [Terraform Registry](https://registry.terraform.io/providers/honeycombio/honeycombio/latest) should also list the new version +- Create a tag following semantic convention prefixed with a `v` (i.e. `v0.83.0`) + - this will start the "release" workflow which builds various versions of the provider for target platforms and architectures. + This can take up to 10 minutes to complete. +- When the release workflow compltes, go to [releases](https://github.com/honeycombio/terraform-provider-honeycombio/releases/) and you'll find a draft release with the build artifacts attached. +- Update the release name to match the release tag (i.e. `v0.83.0`) +- Copy the section from `CHANGELOG.md` for this release into the release description. +- Publish the release. +- Within a few minutes, the [Terraform Registry](https://registry.terraform.io/providers/honeycombio/honeycombio/latest) should have picked up and published the new version. diff --git a/README.md b/README.md index d4961e73..20dd9ff0 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,33 @@ terraform { } ``` -Set the API key used by Terraform setting the `HONEYCOMB_API_KEY` environment variable. You can override the default API Endpoint (`https://api.honeycomb.io`) by setting the `HONEYCOMB_API_ENDPOINT` environment variable. +The Honeycomb provider requires an API key to communicate with the Honeycomb APIs. +The provider can make calls to v1 and v2 APIs and requires specific key configurations for each. +For more information about API Keys, check out [Best Practices for API Keys](https://docs.honeycomb.io/get-started/best-practices/api-keys/). + +A single instance of the provider can be configured with both key types. +At least one of the v1 or v2 API key configuration is required. + +### v1 APIs + +v1 APIs require Configuration Keys. +Their permissions can be managed in _Environment settings_. +Most resources and data sources call v1 APIs today. + +The key can be set with the `api_key` argument or via the `HONEYCOMB_API_KEY` or `HONEYCOMBIO_APIKEY` environment variable. + +`HONEYCOMB_API_KEY` environment variable will take priority over the `HONEYCOMBIO_APIKEY` environment variable. + +### v2 APIs + +v2 APIs require a Mangement Key. +Their permissions can be managed in _Team settings_. +Resources and data sources that call v2 APIs will be noted along with the scope required to use the resource or data source. + +The key pair can be set with the `api_key_id` and `api_key_secret` arguments, or via the `HONEYCOMB_KEY_ID` and `HONEYCOMB_KEY_SECRET` environment variables. + ### Configuring the provider for Honeycomb EU If you are a Honeycomb EU customer, to use the provider you must override the default API host.