Skip to content

Latest commit

 

History

History
183 lines (128 loc) · 8.31 KB

README.md

File metadata and controls

183 lines (128 loc) · 8.31 KB
Raw

Triton Terraform Provider

Requirements

  • Terraform 0.12.x
  • Go 1.11 (to build the provider plugin)
  • Dep for dependency management

Building The Provider

Clone repository to: $GOPATH/src/github.com/joyent/terraform-provider-triton

$ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers
$ git clone [email protected]:terraform-providers/terraform-provider-triton

Enter the provider directory and build the provider

$ cd $GOPATH/src/github.com/joyent/terraform-provider-triton
$ make build

Initialize your Terraform project by passing in the directory that contains your custom built provider binary, terraform-provider-triton. This is typically $GOPATH/bin.

$ terraform version
Terraform v0.12.10

$ terraform init --plugin-dir=$GOPATH/bin

Using the provider

If you haven't already done so, create a Triton account and read the getting started guide to complete the account setup and get your environment configured.

Setup

The provider takes many configuration arguments for setting up your Triton account within Terraform. The following example shows you how to explicitly configure the provider using your account information.

provider "triton" {
  account = "AccountName"
  key_id  = "25:d4:a9:fe:ef:e6:c0:bf:b4:4b:4b:d4:a8:8f:01:0f"

  # If using a private installation of Triton, specify the URL, otherwise
  # set the URL to the CloudAPI endpoint of the region you wish to provision.
  url = "https://us-west-1.api.joyentcloud.com"
}

The following arguments are supported.

  • account - (Required) This is the name of the Triton account. It can also be provided via the SDC_ACCOUNT environment variable.
  • key_material - (Optional) This is the private key of an SSH key associated with the Triton account to be used. If this is not set, the private key corresponding to the fingerprint in key_id must be available via an SSH Agent.
  • key_id - (Required) This is the fingerprint of the public key matching the key specified in key_path. It can be obtained via the command ssh-keygen -l -E md5 -f /path/to/key
  • url - (Optional) This is the URL to the Triton API endpoint. It is required if using a private installation of Triton. The default is to use the Joyent public cloud us-west-1 endpoint. Valid public cloud endpoints include: us-east-1, us-east-2, us-east-3, us-sw-1, us-west-1, eu-ams-1
  • insecure_skip_tls_verify (Optional - defaults to false) This allows skipping TLS verification of the Triton endpoint. It is useful when connecting to a temporary or development Triton installation.

Another option is to pass in account information through Triton's commonly used environment variables. The provider takes the following environment variables...

  • TRITON_ACCOUNT or SDC_ACCOUNT with your Triton account name.
  • TRITON_KEY_MATERIAL or SDC_KEY_MATERIAL with the contents of your private key attached to your Triton account.
  • TRITON_KEY_ID or SDC_KEY_ID with a key id used to reference your Triton account's SSH key.
  • TRITON_URL or SDC_URL with the URL to your CloudAPI endpoint, handy if using Terraform with a private Triton installation.
  • TRITON_SKIP_TLS_VERIFY to skip TLS verification when connecting to TRITON_URL.

Finally, the provider will automatically pick up your Triton SSH key if you do not set key_material but are using ssh-agent.

Resources and Data Providers

There are a wide range of Triton resources and data providers available when building with the Triton Terraform Provider.

Example

The following example shows you how to configure a LX branded zone running Ubuntu.

# use env vars and SSH agent to configure the provider
provider "triton" {}

data "triton_image" "lx-ubuntu" {
    name = "ubuntu-16.04"
    version = "20170403"
}

resource "triton_machine" "test-cns" {
    name    = "test-cns"
    package = "g4-highcpu-256M"
    image   = "${data.triton_image.lx-ubuntu.id}"

    cns {
        services = ["frontend", "app"]
    }
}

Visit Terraform's website for official Triton Provider documentation.

Developing the Provider

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

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

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

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

The acceptance tests will pick up basic triton account configuration from your environment as the provider itself does. You can set this using the node-triton CLI tool in your shell:

$ eval "$(triton env)"
$ make testacc
...

The acceptance tests are configured, by default, to run against the Joyent Public Cloud. You can adjust the parameters used during test provisions by setting the configuration keys below to be appropriate to your environment. The tests expect the deployment to support fabric overlay networks - if these arent't set-up then the tests will fail. They also expect a version of the [email protected] image to be available.

The default values for these parameters are specified in triton/provider_test.go and can be overridden by setting environment variables with the name prefixed with testacc_

  • dc_name The datacenter name reported by CloudAPI

  • test_package_name The name of a simple package that is used in the bulk of test provisions - this can be the lowest resource package available on your platform.

  • test_network_name The name of a network that is available to the test user that the vast majority of test machines will be provisioned into.

  • public_network_name The name of a public network that is available to the test user

  • package_query_name, package_query_memory, package_query_result These three values are used to test the package lookup - the package_query_name and package_query_memory should resolve to a single package with the name specified in package_query_result

You can also use the following environment variables to assist in debugging:

  • TRITON_TRACE_HTTP when set this will print the HTTP requests and responses to stderr.

Publishing

Follow the instructions here for publishing to the Terraform registry: https://www.terraform.io/docs/registry/providers/publishing.html