- Website: https://www.terraform.io
- Documentation: https://registry.terraform.io/providers/fastly/fastly/latest/docs
- Mailing list: http://groups.google.com/group/terraform-tool
NOTE: the last version of the Fastly provider to support Terraform 0.11.x and below was v0.26.0
Clone repository to: $GOPATH/src/github.com/fastly/terraform-provider-fastly
$ mkdir -p $GOPATH/src/github.com/fastly; cd $GOPATH/src/github.com/fastly
$ git clone [email protected]:fastly/terraform-provider-fastlyEnter the provider directory and build the provider
$ cd $GOPATH/src/github.com/fastly/terraform-provider-fastly
$ make buildIf you wish to work on the provider, you'll first need Go installed on your machine (version 1.20+ is required).
To compile the provider, run make build. This will build the provider and put the provider binary in a local bin directory.
$ make build
...Alongside the newly built binary a file called developer_overrides.tfrc will be created. The make build target will communicate
back details for setting the TF_CLI_CONFIG_FILE environment variable that will enable Terraform to use your locally built provider binary.
- HashiCorp - Development Overrides for Provider developers.
NOTE: If you have issues seeing any behaviours from code changes you've made to the provider, then it might be the terraform CLI is getting confused by which provider binary it should be using. Check inside the
./bin/directory to see if there are multiple providers with different commit hashes (e.g.terraform-provider-fastly_v2.2.0-5-gfdc37cee) and delete them first before runningmake build. This should help the Terraform CLI resolve to the correct binary.
The previous method with dev_overrides should be sufficient for most development use including testing your local changes with actual Terraform code.
However, sometimes it can be helpful to run the provider in debug mode if you need to attach a debugger like delve to solve a particular issue.
The way Terraform normally works is that it starts the provider in a subprocess and connects to it using GRPC over a local socket. (For more information on this, see hashicorp/go-plugin). For debugging, it is possible to bypass this and execute the provider in a separate process, then tell Terraform how to communicate with it. The benefit of this is that the provider can be launched with a debugger attached in the same way that the debugger would attach to any normal executable.
There are a few ways to do this depending on which debugger is being used, but we will use delve here as the process should be pretty similar for other debuggers.
The two things that need to be configured are that the provider is compiled without optimisations, and the executable is run with the --debug flag.
Compiling without optimisations ensures that the debugger can access all of the symbols in the binary that it needs to, and the --debug flag tells the Terraform plugin SDK to expect to be run in its own process, and to display the instructions for connecting to it after it starts up.
With delve this can be done in a single command:
$ dlv debug . -- --debug
Type 'help' for list of commands.
(dlv) continue
{"@level":"debug","@message":"plugin address","@timestamp":"2021-03-26T12:10:13.320981Z","address":"/var/folders/qm/swg2hf4h5t8sdht8yhds4dg6m0000gn/T/plugin865249851","network":"unix"}
Provider started, to attach Terraform set the TF_REATTACH_PROVIDERS env var:
TF_REATTACH_PROVIDERS='{"fastly/fastly":{"Protocol":"grpc","Pid":54132,"Test":true,"Addr":{"Network":"unix","String":"/var/folders/qm/swg2hf4h5t8sdht8yhds4dg6m0000gn/T/plugin865249851"}}}'This can also be done in two separate steps. The -gcflags disables optimisations (-N) and inlining (-l).
$ go build -gcflags="all=-N -l" -o terraform-provider-fastly_debug
$ dlv exec terraform-provider-fastly_debug -- --debugAs the message instructs, go to another shell and export the TF_REATTACH_PROVIDERS environment variable.
Then use Terraform as usual, and it will automatically use the provider in the debugger.
$ export TF_REATTACH_PROVIDERS='{"fastly/fastly":{"Protocol":"grpc","Pid":54132,"Test":true,"Addr":{"Network":"unix","String":"/var/folders/qm/swg2hf4h5t8sdht8yhds4dg6m0000gn/T/plugin865249851"}}}'
$ terraform planYou will then be able to set breakpoints and trace the provider's execution using the debugger as you would expect.
The implementation for setting up debug mode presumes Terraform 0.13.x is being used. If you're using Terraform 0.12.x you'll need to manually modify the value assigned to TF_REATTACH_PROVIDERS so that the key "fastly/fastly" becomes "registry.terraform.io/-/fastly". See HashiCorp's "Support for Debuggable Provider Binaries" for more details.
(first shell) dlv debug . --headless -- --debug
(second shell) dlv connect <output from first shell>
continue
<Ctrl-c>
break fastly/block_fastly_service_package.go:123
(third shell) export TF_REATTACH_PROVIDERS="..."
terraform apply
(second shell) continue (do your step debugging)
<Ctrl-c> (then run another terraform command from third shell)
In order to test the provider, you can simply run make test.
$ make testIn order to run the full suite of Acceptance tests, run make testacc.
Note: Acceptance tests create real resources, and often cost money to run. You should expect that the full acceptance test suite will take hours to run.
$ make testaccIn order to run an individual acceptance test, the '-run' flag can be used together with a regular expression. The following example uses a regular expression matching single test called 'TestAccFastlyServiceVCL_basic'.
$ make testacc TESTARGS='-run=TestAccFastlyServiceVCL_basic'The following example uses a regular expression to execute a grouping of basic acceptance tests.
$ make testacc TESTARGS='-run=TestAccFastlyServiceVCL.*_basic'In order to run the tests with extra debugging context, prefix the make command with TF_LOG (see the terraform documentation for details).
$ TF_LOG=trace make testaccBy default, the tests run with a parallelism of 4.
This can be reduced if some tests are failing due to network-related issues, or increased if possible, to reduce the running time of the tests.
Prefix the make command with TEST_PARALLELISM, as in the following example, to configure this.
$ TEST_PARALLELISM=8 make testaccDepending on the Fastly account used, some features may not be enabled (e.g. Platform TLS).
This may result in some tests failing, potentially with 403 Unauthorised errors, when the full test suite is being run.
Check the Fastly API documentation to confirm if the failing tests use features in Limited Availability or only available to certain customers.
If this is the case, either use the TESTARGS regular expressions described above, or temporarily add t.SkipNow() to the top of any tests that should be excluded.
The documentation is built from components (go templates) stored in the templates folder.
Building the documentation copies the full markdown into the docs folder, ready for deployment to Hashicorp.
NOTE: you'll need the
tfplugindocstool for generating the Markdown to be deployed to Hashicorp. For more information on generating documentation, refer to https://www.terraform.io/docs/registry/providers/docs.html
- To validate the
/templatedirectory structure:
make validate-docs
- To build the
/docsdocumentation Markdown files:
make generate-docs
- To view the documentation:
Paste
/docsMarkdown file content into https://registry.terraform.io/tools/doc-preview
Refer to CONTRIBUTING.md
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent