PacketFabric Terraform Provider

• Documentation: https://registry.terraform.io/providers/packetfabric/packetfabric/latest/docs

Requirements

• Terraform v1.2.2
• Go 1.18.2 (to build the provider plugin)

Standard Provider usage

See the PacketFabric Provider documentation for resource definition and data-source structure and examples.

Versioning policy

0.0.0
| | |
| | +-- backward compatible changes (bug fixes)
| +---- backward compatible changes (new features)
+------ backward incompatible changes

We are following a version numbering system (e.g. v1.2.4) and will not make breaking changes to major version (e.g. v1.0.0) except in exceptional circumstances. If a breaking change is necessary, we will release a new major version (e.g. v2.0.0) and provide at least three months of bug fixes for the previous major version to allow users time to make necessary changes to their code.

Building and installing the Provider locally

$ git clone [email protected]:packetfabric/terraform-provider-packetfabric
$ make install
go build -o terraform-provider-packetfabric
mkdir -p ~/.terraform.d/plugins/[YOURHOSTNAME]/packetfabric/packetfabric/0.0.1/linux_amd64
mv terraform-provider-packetfabric ~/.terraform.d/plugins/[YOURHOSTNAME]/packetfabric/packetfabric/0.0.1/linux_amd64

Using the local build/installed provider

terraform {
  required_providers {
    packetfabric = {
      source  = "[YOURHOSTNAME]/packetfabric/packetfabric"
      version = "~> 0.0.1"
    }
  }
}

Contributing Documentation

Markdown documents found in this repository are the source of the PacketFabric Provider documentation. These source documents are generated using the Terraform-Plugin-Docs Tools.

Data-Source and Resource field descriptions are pulled from the internal/provider source-code. It's organized based on the resource and data-source matching markdown template found in templates and merged with examples found in the examples

Updating the provider function field descriptions should be done in internal/provider code schema descriptions. Structural changes to the MD formating should be done in the templates tmpls files.

Caveat: As of tfplugindocs 0.10.1, Nested schema elements are not properly discovered and inserted at generation time. This means data-source function field descriptions must be manually managed in the templates tmpls files for data-sources.

Developing The Provider

To work on the provider, you'll need Go installed on your machine (version 1.11+ is required). You'll need to correctly setup a GOPATH, as well as adding $GOPATH/bin to your $PATH.

To compile, run make build. To compile and install, run make install . This will build (and install) the provider and put the provider binary in the $GOPATH/bin directory.

$ make build
...
$ $GOPATH/bin/terraform-provider-packetfabric
...

To test the provider, run make test.

$ make test

To check changes you made locally to the provider, you can use the binary you compiled by adding the following to your ~/.terraformrc file. This is valid for Terraform 0.14+. See Terraform's documentation for more details.

provider_installation {

  # Use /home/developer/go/bin as an overridden package directory
  # for the PacketFabric/packetfabric provider. This disables the version and checksum
  # verifications for this provider and forces Terraform to look for the
  # packetfabric provider plugin in the given directory.
  dev_overrides {
    "PacketFabric/packetfabric" = "/home/developer/go/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 {}
}

For information about writing acceptance tests, see the main Terraform contributing guide.

Acceptance Tests

To run acceptance tests on your local machine, you have to set the following environmental variables:

export PF_HOST="https://api.packetfabric.com"
export PF_TOKEN="api-secret"
export PF_ACCOUNT_ID="123456789"
export PF_USER_EMAIL="[email protected]"

Some tests require specific environment variables to be set. You can find examples of these variables in the source_env_var.sh.sample file.

Warning: Running below command will order various PacketFabric products, then delete them.

You can test the provider using different methods. Here are some common scenarios:

Running All Tests

To run all tests, you can use the all tag. Navigate to the internal/provider directory and run the following command:

$ cd internal/provider;  TF_ACC=1 go test -v -timeout 120m -tags=all

Warning: Add -parallel 1 if running the test in dev environement.

Running Tests with Specific Tags

If you want to run a subset of tests, you can do so by specifying the relevant tag. For example, to run tests that have been tagged with smoke, use the following command:

$ cd internal/provider;  TF_ACC=1 go test -v -timeout 120m -tags=smoke

Running Individual Tests

You can also run individual tests by specifying the test's function name with the -run flag. For example, to run the TestAccPort test, use the following command:

$ cd internal/provider; TF_ACC=1 go test -v -timeout 30m -tags=all -run=TestAccPort

Note: Setting the TF_ACC environment variable to 1 enables acceptance tests, which hit real APIs and can take a long time to run.

If you want to know the current list of acceptance tests available without executing them, run the following command:

cd internal/provider; go test -tags=all -cover -v | grep -v testutil.go | grep -v github.com

Releasing the Provider

This provider is published using GitHub Actions triggered by tagging a branch using semantic versioning with the pattern v*(Example: v1.5.3)

Once the branch is tagged the release is built and publish via the Terraform Registry.

Provider release candidates will be based on main-branch and be committed on their own, dedicated, dev branch. The release branch will be qualified and UAT then merged with main. A new Release branch will be created from main at the merge point. The Release branch will be tagged for publishing. This process allows us to support multiple versions of the provider simultaneously if desired.