Skip to content

Latest commit

 

History

History
139 lines (96 loc) · 6.97 KB

CONTRIBUTIONS.md

File metadata and controls

139 lines (96 loc) · 6.97 KB
Raw

Contribution Guide

Contributors

Pull requests, issues and comments are welcomed. For pull requests:

  • Add tests for new features and bug fixes
  • Follow the existing style
  • Separate unrelated changes into multiple pull requests

See the existing issues for things to start contributing.

For bigger changes, make sure you start a discussion first by creating an issue and explaining the intended change.

JFrog requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership).

Build the Provider

Simply run make install - this will compile the provider and install it to ~/terraform.d. When running this, it will take the current tag and bump it 1 minor version. It does not actually create a new tag (that is make release). If you wish to use the locally installed provider, make sure your TF script refers to the new version number.

Requirements:

  • Terraform 0.13
  • Go 1.18+ (to build the provider plugin)

Building on macOS

This provider uses GNU sed as part of the build toolchain, in both Linux and macOS. This provides consistency across OSes.

If you are building this on macOS, you have two options:

Using gnu-sed

After installing with brew, get the GNU sed information:

$ brew info gnu-sed

You should see something like:

GNU "sed" has been installed as "gsed".
If you need to use it as "sed", you can add a "gnubin" directory
to your PATH from your bashrc like:

     PATH="$(brew --prefix)/opt/gnu-sed/libexec/gnubin:$PATH"

Add the gnubin directory to your .bashrc or .zshrc per instruction so that sed command uses gnu-sed.

Testing

How to run the tests isn't obvious.

In order to test the provider with Artifactory and Xray you need a running instance of the JFrog platform. However, there is no currently supported Dockerized, local version. You can ask for an instance to test against in as part of your PR or by messaging the maintainer in gitter.

Alternatively, you can run the file scripts/run-artifactory.sh, which, if you have a license file in the same directory called artifactory.lic, you can start just an artifactory instance. The license is not supplied, but a 30 day trial license can be freely obtained and will allow local development. This however will not test any Xray functionality.

Then, you have to set some environment variables as this is how the acceptance tests pick up their config

PROJECT_URL=http://localhost:8081
PROJECT_ACCESS_TOKEN=...
TF_ACC=true

A crucial env var to set is TF_ACC=true - you can literally set TF_ACC to anything you want, so long as it's set. The acceptance tests use terraform testing libraries that, if this flag isn't set, will skip all tests. See Terraform doc.

You can then run the tests with:

$ go test -v ./pkg/...

DO NOT omit the -v - terraform testing needs this (don't ask me why). This will recursively run all tests, including acceptance tests.

We've found that it's very convenient to use Charles proxy to see the payload, generated by Terraform Provider during the testing process. You can also use any other network packet reader, like Wireshark and so on.

Debugging

Debugger-based debugging

Debugging a terraform provider is not straightforward. Terraform forks your provider as a separate process and then connects to it via RPC. Normally, when debugging, you would start the process to debug directly. However, with the terraform + go architecture, this isn't possible. So, you need to run terraform as you normally would and attach to the provider process by getting its pid. This would be really tricky considering how fast the process can come up and be down. So, you need to actually halt the provider and have it wait for your debugger to attach.

Having said all that, here are the steps:

  1. Install delve
  2. Keep in mind that terraform will parallel process if it can, and it will start new instances of the TF provider process when running apply between the plan and confirmation. Add a snippet of go code to the close to where you need to break where in you install a busy sleep loop:
	debug := true
	for debug {
		time.Sleep(time.Second) // set breakpoint here
	}

Then set a breakpoint inside the loop. Once you have attached to the process you can set the debug value to false, thus breaking the sleep loop and allow you to continue. 2. Compile the provider with debug symbology (go build -gcflags "all=-N -l") 3. Install the provider (change as needed for your version)

# this will bump your version by 1 so it doesn't download from TF. Make sure you update any test scripts accordingly
make install
  1. Run your provider: terraform init && terraform plan - it will start in this busy sleep loop.
  2. In a separate shell, find the PID of the provider that got forked pgrep terraform-provider-projects
  3. Then, attach the debugger to that pid: dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient attach $pid A 1-liner for this whole process is: dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient attach $(pgrep terraform-provider-projects)
  4. In intellij, setup a remote go debugging session (the default port is 2345, but make sure it's set.) And click the debug button
  5. Your editor should immediately break at the breakpoint from step 2. At this point, in the watch window, edit the debug value and set it to false, and allow the debugger to continue. Be ready for your debugging as this will release the provider and continue executing normally.

You will need to repeat steps 4-8 every time you want to debug

Log-based debugging

You can turn on logging for debug purpose by setting env var TF_LOG to DEBUG or TRACE, i.e.

export TF_LOG=DEBUG

Then use tflog.Debug() to print the data you want to the console.

Note that you must include the log level as the prefix to the log message, e.g.

tflog.Debug("some thing happened")

Registry documentation generation

All the registry documentation is generated using tfplugindocs. If you make any changes to the resource schemas, you will need to re-generate documentation.

Install tfplugindocs, then run:

$ make doc