Skip to content

DEVELOPING.md

Latest commit

 

History

History
209 lines (145 loc) · 6.19 KB

DEVELOPING.md

File metadata and controls

209 lines (145 loc) · 6.19 KB

Developing the Provider

Requirements

Get the provider source code:

git clone git@github.com:UpCloudLtd/terraform-provider-upcloud.git
cd terraform-provider-upcloud

To compile the provider, run go build. This will build the provider and put the provider binary in the current directory.

go build

In the majority of cases the make command will be executed to build the binary in the correct directory.

make

The UpCloud provider will be built and placed in the following location under the ~/.terraform.d/plugins directory. The version number will match the value specified in the makefile and in this case the version is 2.0.0.

~/.terraform.d/plugins
└── registry.upcloud.com
    └── upcloud
        └── upcloud
            └── 2.0.0
                └── darwin_amd64
                    └── terraform-provider-upcloud_v2.0.0

After the provider has been built you can then use standard terraform commands.

Use this provider config with the local version:

terraform {
  required_providers {
    upcloud = {
      source = "registry.upcloud.com/upcloud/upcloud"
      version = "~> 2.1"
    }
  }
}

Update database properties

Prerequisites:

  • Set your credentials to UPCLOUD_USERNAME and UPCLOUD_PASSWORD environment variables.
  • Ensure you have jq and upctl installed.

Run make generate to update database properties schemas.

make generate

Testing

To lint the providers source-code, run golangci-lint run. See golangci-lint docs for installation instructions.

golangci-lint run

In order to test the provider, you can simply run make test.

make test

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.

make testacc

In 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 'TestUpcloudServer_basic'.

make testacc TESTARGS='-run=TestUpcloudServer_basic'

The following example uses a regular expression to execute a grouping of basic acceptance tests.

make testacc TESTARGS='-run=TestUpcloudServer_*'

In order to view the documentation change rendering visite the terraform documentation preview.

End-to-end tests

While the focus of the tests in this repository is to test the provider's functionality, there are some cases when it makes sense to also validate the target resource or system. For example, ephemeral Kubernetes cluster resource can be tested by using the resource to configure Kubernetes provider. These tests that do end-to-end validations are prefixed with TestEndToEnd and are executed as a part of the acceptance test suite.

To run the end-to-end tests, use the following command:

make testacc TESTARGS='-run=TestEndToEnd'

You can use TF_VAR_basename and TF_VAR_zone environment variables to set the basename and zone for the end-to-end tests. For example:

TF_VAR_basename="test-pl-waw1-" TF_VAR_zone="pl-waw1" make testacc TESTARGS='-run=TestEndToEnd'

The end-to-end testcases should:

  • Have a name starting with TestEndToEnd.
  • Use basename and zone variables in configuration. The basename variable should have a default value of tf-acc-test-.
  • Document the test with t.Log function in the beginning of the test function.

Debugging

To print UpCloud API requests and responses, set Terraform log level to debug or lower. For example, when running an apply:

TF_LOG=debug terraform apply

Generating documentation

The documentation in docs directory is generated with tfplugindocs. This is done automatically when changes are merged to the main branch. If there are documentation changes, actions will create a new pull request for documentation changes. Review and merge this pull-request.

To generate the docs locally, run make docs. This installs the tool and builds the docs.

make docs

Go version upgrades

Upgrading Go version for the project requires the following changes:

After updating those files, make sure that you can still build the project (make build) and that docker image builds without any errors (docker image build ./release).

Once that is done it should be safe to release a new version of the provider.

Developing in Docker

You can also develop/build/test in Docker. After you've cloned the repository:

Create a docker container with golang as base:

docker run -it -v `pwd`:/work -w /work golang bash

Install Terraform:

cd /tmp
git clone https://github.com/hashicorp/terraform.git
cd terraform
go install

Build the UpCloud provider:

cd /work
make build

Run Terraform files, e.g. the examples:

cd /tmp
cp /work/examples/server.tf .
# change the provider source in server.tf to "registry.upcloud.com/upcloud/upcloud"
export UPCLOUD_USERNAME="upcloud-api-access-enabled-user"
export UPCLOUD_PASSWORD="verysecretpassword"
terraform init
terraform apply

After exiting the container, you can connect back to the container:

docker start -ai <container ID here>

Debugging

UpCloud provider can be run in debug mode using a debugger such as Delve.
For more information, see Terraform docs

Environment variables UPCLOUD_DEBUG_API_BASE_URL and UPCLOUD_DEBUG_SKIP_CERTIFICATE_VERIFY can be used for HTTP client debugging purposes. More information can be found in the client's README file.