-
Notifications
You must be signed in to change notification settings - Fork 138
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update the
README setup instructions and Make commands (#405)
* Simplify local setup * Add `make clean` to remove `~/.terraformrc` * Add missing phony commands to makefile * Rewrite README development/setup instructions --------- Co-authored-by: koushik-swaminathan <[email protected]>
- Loading branch information
1 parent
19c51f8
commit e59b44f
Showing
5 changed files
with
168 additions
and
112 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,100 +1,134 @@ | ||
|
|
||
| Terraform Provider | ||
| ================== | ||
| # Terraform Provider | ||
|
|
||
| - Website: https://www.terraform.io | ||
| - [](https://gitter.im/hashicorp-terraform/Lobby) | ||
| - Mailing list: [Google Groups](http://groups.google.com/group/terraform-tool) | ||
|
|
||
| <img src="https://www.datocms-assets.com/2885/1629941242-logo-terraform-main.svg" width="600px"> | ||
|
|
||
| Requirements | ||
| ------------ | ||
|
|
||
| - [Terraform](https://www.terraform.io/downloads.html) 0.12.x | ||
| - [Go](https://golang.org/doc/install) 1.14.2 (to build the provider plugin) | ||
| ## Development | ||
|
|
||
| Building The Provider | ||
| --------------------- | ||
| Everything needed to start local development and testing of the Provider plugin | ||
|
|
||
| Clone repository to: `$GOPATH/src/github.com/opsgenie/terraform-provider-opsgenie` | ||
| ### 1. Requirements | ||
|
|
||
| ```sh | ||
| $ mkdir -p $GOPATH/src/github.com/opsgenie; cd $GOPATH/src/github.com/opsgenie | ||
| $ git clone [email protected]:opsgenie/terraform-provider-opsgenie | ||
| ``` | ||
| - [Go](https://golang.org/doc/install) 1.18 (or higher, to build the provider plugin) | ||
| - [Terraform](https://www.terraform.io/downloads.html) 0.12.x (To test the plugin) | ||
|
|
||
| Enter the provider directory and build the provider | ||
|
|
||
| ```sh | ||
| $ cd $GOPATH/src/github.com/opsgenie/terraform-provider-opsgenie | ||
| $ make build | ||
| ``` | ||
| ### 2. Development Setup | ||
|
|
||
| Using the provider | ||
| ---------------------- | ||
| ## Fill in for each provider | ||
| #### Cloning the project | ||
|
|
||
| Developing the Provider | ||
| --------------------------- | ||
| ```bash | ||
| export GOPATH="${GOPATH:=$HOME/go}" | ||
|
|
||
| If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.8+ is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`. | ||
| mkdir -p "$GOPATH/src/github.com/opsgenie" | ||
|
|
||
| To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. | ||
| cd "$GOPATH/src/github.com/opsgenie" | ||
|
|
||
| ```sh | ||
| $ make build | ||
| ... | ||
| $ $GOPATH/bin/terraform-provider-opsgenie | ||
| ... | ||
| git clone [email protected]:opsgenie/terraform-provider-opsgenie | ||
| ``` | ||
|
|
||
| In order to test the provider, you can simply run `make test`. | ||
|
|
||
| ### 3. Compiling The Provider | ||
|
|
||
| ```sh | ||
| $ make test | ||
| export GOPATH="${GOPATH:=$HOME/go}" | ||
| cd "$GOPATH/src/github.com/opsgenie" | ||
|
|
||
| # Compile all versions of the provider and install it in GOPATH. | ||
| make build | ||
|
|
||
| # Only compile the local executable version (Faster) | ||
| make dev | ||
| ``` | ||
|
|
||
| In order to run the full suite of Acceptance tests, run `make testacc`. | ||
|
|
||
| *Note:* Acceptance tests create real resources, and often cost money to run. | ||
| #### Running tests on the Provider | ||
|
|
||
| Run all local unit tests. | ||
|
|
||
| ```sh | ||
| $ make testacc | ||
| make test | ||
| ``` | ||
|
|
||
| Testing the Provider from Local Registry Version | ||
| ------------------------------------------------ | ||
| * Create a `.terraformrc` file on your in your home folder using `vi ~/.terraformrc` | ||
| * Add the local provider registry conf in `.terraformrc` | ||
| ``` | ||
| provider_installation { | ||
| filesystem_mirror { | ||
| path = "~/terraform/providers" | ||
| include = ["test.local/*/*"] | ||
| } | ||
| direct { | ||
| exclude = ["test.local/*/*"] | ||
| } | ||
| } | ||
| ``` | ||
| * Run `make build` on local (it will internally trigger a hook to write to `test.local` registry located in your `~/terraform/providers` folder) | ||
| * You can create a terraform basic project of your own locally with `main.tf` file | ||
|
|
||
| ### 4. Using the Compiled Provider | ||
|
|
||
| #### Configure Terraform to use the compiled provider. | ||
|
|
||
| This configuration makes use of the [`dev_overrides`](https://developer.hashicorp.com/terraform/cli/config/config-file#development-overrides-for-provider-developers). | ||
|
|
||
| See the [Manual Setup][Manual Setup] for more details. | ||
|
|
||
| ```bash | ||
| # Creates $HOME/.terraformrc | ||
| make setup | ||
| ``` | ||
| terraform { | ||
| required_providers { | ||
| opsgenie = { | ||
| source = "test.local/opsgenie/opsgenie" | ||
| version = "<local_version>" | ||
|
|
||
| #### Manual setup | ||
|
|
||
| <details> | ||
| <summary>Click to expand</summary> | ||
|
|
||
| 1. Create the `.terraformrc` file on your in your home folder using `touch ~/.terraformrc` | ||
| 2. Configure [`dev_overrides`](https://developer.hashicorp.com/terraform/cli/config/config-file#development-overrides-for-provider-developers) in your `~/.terraformrc` as show below: | ||
| ```hcl | ||
| provider_installation { | ||
| dev_overrides { | ||
| # Remember to replace <home dir> with your username | ||
| "opsgenie/opsgenie" = "/home/<home dir>/go/bin" | ||
| } | ||
| direct {} | ||
| } | ||
| } | ||
| } | ||
| # Configure the Opsgenie Provider | ||
| provider "opsgenie" { | ||
| api_key = <api_key> | ||
| api_url = "api.opsgenie.com" # can be a stage instance url for devs | ||
| } | ||
| ``` | ||
| 3. Run `make build` | ||
| </details> | ||
| #### New OpsGenie Terraform project | ||
| 1. Create a basic terraform project locally with a `main.tf` file: | ||
| ```hcl | ||
| terraform { | ||
| required_providers { | ||
| opsgenie = { | ||
| source = "opsgenie/opsgenie" | ||
| version = ">=0.6.0" # version can be omitted | ||
| } | ||
| } | ||
| } | ||
| # Configure the Opsgenie Provider | ||
| provider "opsgenie" { | ||
| api_key = "<insert api_key>" # https://support.atlassian.com/opsgenie/docs/api-key-management/ | ||
| api_url = "api.opsgenie.com" # can be a stage instance url for devs | ||
| } | ||
| resource "opsgenie_team" { | ||
| name = "Dev-Provider test team" | ||
| description = "New team made using in-development OpsGenie provider" | ||
| } | ||
| ``` | ||
| 2. And, Add respective terraform change files which you want to apply on your OG instance | ||
| 3. Run respective terraform commands to test the provider as per your convenience | ||
| Install the currently available provider with `tf init` | ||
| `terraform plan` and `terraform init` will use providers from the configured paths in `$HOME/.terraformrc` | ||
| `terraform` will output an error if no provider is found in the `dev_overrides` path. (`make build`) | ||
| #### Removing the 'dev_override' again | ||
| This allows you to use the normal release versions of the `opsgenie/opsgenie` provider. | ||
| *Note* Removes `$HOME/.terraformrc` | ||
| ```bash | ||
| make clean | ||
| ``` | ||
| * And, Add respective terraform change files which you want to apply on your OG instance | ||
| * Run respective terraform commands to test the provider as per your convenience |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| #!/bin/sh | ||
|
|
||
| if [ -z "$GOPATH" ]; then | ||
| GOPATH="${GOPATH:-$HOME/go}" | ||
| fi | ||
|
|
||
| if [ ! -d "$GOPATH" ]; then | ||
| mkdir -p "$GOPATH/bin" | ||
| fi | ||
|
|
||
| cat >~/.terraformrc <<EOF | ||
| provider_installation { | ||
| dev_overrides { | ||
| "opsgenie/opsgenie" = "$GOPATH/bin" | ||
| } | ||
| direct {} | ||
| } | ||
| EOF |