Developing

Developing the Provider

Planning & Design

When creating a new resource, datasource or changing a current schema please document the changes, including example plans, and create an github issue for review and approval before coding.

Consider writing documents for the project-docs/decisions folder.

New resources and datasources will require import and use example documents.

Coding

If you wish to work on the provider, you'll first need Go installed on your machine (see Requirements).

See also Building The Provider

Note: Commits provided as part of a PR must be signed via git for the PR to merge.

Note: All commit messages must be meaningful and include why the change is being made. They must follow the Juju conventional commits guidelines.

Docs

The docs/resources/*.md and docs/data-sources/*.md files are generated with make docs from the

• Terraform schema descriptions
• The import.sh and resource.tf files in examples/resources/juju_*/ and examples/data-sources/juju_*/directories

Writing Juju client Unit Tests

We are in the process of creating unit tests for the internal/juju code. All new code is required to have them.

These test use the github.com/stretchr/testify/suite and are mocked using the go.uber.org/mock package. Please see https://github.com/juju/terraform-provider-juju/pull/433 for examples.

The go generate lines should be added to the package_test.go file.

Writing Acceptance Tests

Acceptance tests usually require Terraform plans to be included to the various steps of the test. This plans can be generated with help of testing/plangenerator package. You may use GetStringFromTemplateWithData function to generate a plan from a template. This function will replace the placeholders in the template with the data.

The example can be found in the comments to GetStringFromTemplateWithData function.

Running Acceptance Tests

Prior to running the tests locally, ensure you have the following environmental variables set:

• JUJU_AGENT_VERSION
• JUJU_CONTROLLER_ADDRESSES
• JUJU_USERNAME
• JUJU_PASSWORD
• JUJU_CA_CERT

For example, here they are set using the currently active controller:

export CONTROLLER=$(juju whoami | yq .Controller)
export JUJU_AGENT_VERSION="$(juju show-controller | yq '.[$CONTROLLER]'.details.\"agent-version\"|tr -d '"')"
export JUJU_CONTROLLER_ADDRESSES=$(juju show-controller | yq .$CONTROLLER.details.api-endpoints | yq -r '. | join(",")')
export JUJU_USERNAME="$(cat ~/.local/share/juju/accounts.yaml | yq .controllers.$CONTROLLER.user|tr -d '"')"
export JUJU_PASSWORD="$(cat ~/.local/share/juju/accounts.yaml | yq .controllers.$CONTROLLER.password|tr -d '"')"
export JUJU_CA_CERT="$(juju show-controller $(echo $CONTROLLER|tr -d '"') | yq '.[$CONTROLLER]'.details.\"ca-cert\"|tr -d '"'|sed 's/\\n/\n/g')"

Then, finally, run the Acceptance tests:

make testlxd

And

make testmicrok8s

Note: Acceptance tests create real resources.

Staying in sync

To simplify staying in sync with upstream, give it a "remote" name:

git remote add upstream https://github.com/juju/terraform-provider-juju.git

Make sure your local copy and GitHub fork stay in sync with upstream:

git pull upstream/main --rebase

Merge commits for sync actions will be rejected.

Adding Dependencies

This provider uses Go modules. Please see the Go documentation for the most up to date information about using Go modules.

To add a new dependency github.com/author/dependency to your Terraform provider:

go get github.com/author/dependency
go mod tidy

Then commit the changes to go.mod and go.sum.

Debugging

See the Debugging section of the README.md

Troubleshooting failures while developing

model "\"tf-secret-test\"" not found

A double quotes string as not found is usually caused by using types.String.String() rather than types.String.StringValue(). The String() method returns the string with fmt.Sprintf("%q", s.value) while StringValue() returns return s.value. The juju provider also used %q to print what was not found, thus the double quotes.