terraform-provider-consulacl

README

Terraform Consul ACL Provider

Overview

This provider defines a Terraform resource that allows one to manage Consul ACL tokens with Terraform.

Resources

This plugin defines following resources:

• transform_group_by_value - manages a single Consul ACL token

Reference

Provider is configurable with number of parameters:

• address - String, host and port used to connect to Consul. Defaults to localhost:8500. Can be set via environment variables CONSUL_ADDRESS or CONSUL_HTTP_ADDR.
• token - String, ACL token to use for API calls to Consul. Must be a management token to manage ACLs. Defaults to empty value. Can be set via environment variables CONSUL_TOKEN or CONSUL_HTTP_TOKEN.
• scheme - String, scheme to use to connect to Consul. Defaults to http. Can be set via environment variables CONSUL_SCHEME or CONSUL_HTTP_SCHEME.
• ca_file - String, path to a certificate of a certification authority (CA) that was used to sign Consul's TLS certificate and therefore should be used for TLS validation. Defaults to system bundle if not specified. Can be set via environment variable CONSUL_CA_FILE.
• cert_file - String, path to a client certificate for client-side TLS authentication, if enabled in Consul. Can be set via environment variable CONSUL_CERT_FILE.
• key_file - String, path to a private key for client certificate provided in cert_file. Can be set via environment variable CONSUL_KEY_FILE.
• tls_skip_verify - Bool, whether to skip verification of Consul's TLS certificate. Defaults to false. Can be set via environment variable CONSUL_TLS_SKIP_VERIFY.

consulacl_token

Arguments

The following arguments are supported:

• name - (Required) String defining name for the token
• type - (Required) String defining type of the token - either client or management
• token - (Optional) If set, defines the token ID. If unset - a unique UUID will be generated by Consul and exported by the resource. It is a sensitive data.
• rule - (Optional) Set of rules to assign to the token. Each rule is defined as a map with following fields:
  • scope - (Required) String defining a scope of the rule. One of: agent, event, key, node, query, service, session, keyring and operator.
  • policy - (Required) String defining a policy of the rule. One of: read, write.
  • prefix - (Optional) String defining a prefix limiting the rule's effect. Not allowed for keyring and operator scopes.

Attributes

The following attribute is exported:

• token - String, the ACL token's value. Sensitive.
• id - String, SHA256 hash of token attribute.

Installation

Terraform automatically discovers the Providers when it parses configuration files. This only occurs when the init command is executed.

Currently Terraform is able to automatically download only official plugins distributed by HashiCorp.

All other plugins should be installed manually.

Terraform will search for matching Providers via a Discovery process, including the current local directory.

This means that the plugin should either be placed into current working directory where Terraform will be executed from or it can be installed system-wide.

Usage

main.tf

resource "consulacl_token" "token" {
  name  = "A demo token"
  token = "my-custom-token"
  type  = "client"

  rule { scope="key"      policy="write"  prefix="foo/bar/baz"  }
  rule { scope="service"  policy="read"   prefix=""             }
  rule { scope="operator" policy="read"                         }
}

Download

$ wget "https://github.com/ashald/terraform-provider-consulacl/releases/download/v1.1.0/terraform-provider-consulacl_v1.1.0-$(uname -s | tr '[:upper:]' '[:lower:]')-amd64"
$ chmod +x ./terraform-provider-transform*

Init

$ ls -1
  main.tf
  terraform-provider-consulacl_v1.1.0-linux-amd64

$ terraform init
  
  Initializing provider plugins...
  
  The following providers do not have any version constraints in configuration,
  so the latest version was installed.
  
  To prevent automatic upgrades to new major versions that may contain breaking
  changes, it is recommended to add version = "..." constraints to the
  corresponding provider blocks in configuration, with the constraint strings
  suggested below.
  
  * provider.consulacl: version = "~> 1.0"
  
  Terraform has been successfully initialized!
  
  You may now begin working with Terraform. Try running "terraform plan" to see
  any changes that are required for your infrastructure. All Terraform commands
  should now work.
  
  If you ever set or change modules or backend configuration for Terraform,
  rerun this command to reinitialize your working directory. If you forget, other
  commands will detect it and remind you to do so if necessary.

Apply

$ terraform apply
  
  An execution plan has been generated and is shown below.
  Resource actions are indicated with the following symbols:
    + create
  
  Terraform will perform the following actions:
  
    + consulacl_token.token
        id:                     <computed>
        name:                   "A demo token"
        rule.#:                 "3"
        rule.1495889372.policy: "write"
        rule.1495889372.prefix: "foo/bar/baz"
        rule.1495889372.scope:  "key"
        rule.2015766991.policy: "read"
        rule.2015766991.prefix: ""
        rule.2015766991.scope:  "service"
        rule.4269786272.policy: "read"
        rule.4269786272.prefix: ""
        rule.4269786272.scope:  "operator"
        token:                  <sensitive>
        type:                   "client"
  
  
  Plan: 1 to add, 0 to change, 0 to destroy.
  
  Do you want to perform these actions?
    Terraform will perform the actions described above.
    Only 'yes' will be accepted to approve.
  
    Enter a value: yes
  
  consulacl_token.token: Creating...
    name:                   "" => "A demo token"
    rule.#:                 "0" => "3"
    rule.1495889372.policy: "" => "write"
    rule.1495889372.prefix: "" => "foo/bar/baz"
    rule.1495889372.scope:  "" => "key"
    rule.2015766991.policy: "" => "read"
    rule.2015766991.prefix: "" => ""
    rule.2015766991.scope:  "" => "service"
    rule.4269786272.policy: "" => "read"
    rule.4269786272.prefix: "" => ""
    rule.4269786272.scope:  "" => "operator"
    token:                  "<sensitive>" => "<sensitive>"
    type:                   "" => "client"
  consulacl_token.token: Creation complete after 0s (ID: 929a4284c36bdaa9ba4a96dbbcfd9839160258643e4d1beb9a15fff6c6bcd027)
  
  Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Import

$ terraform import consulacl_token.token "a694f2c0-20c8-902c-7d57-be10bd3edb1b"
  consulacl_token.token: Importing from ID "a694f2c0-20c8-902c-7d57-be10bd3edb1b"...
  consulacl_token.token: Import complete!
    Imported consulacl_token (ID: 929a4284c36bdaa9ba4a96dbbcfd9839160258643e4d1beb9a15fff6c6bcd027)
  consulacl_token.token: Refreshing state... (ID: 929a4284c36bdaa9ba4a96dbbcfd9839160258643e4d1beb9a15fff6c6bcd027)
  
  Import successful!
  
  The resources that were imported are shown above. These resources are now in
  your Terraform state and will henceforth be managed by Terraform.

Development

Go

In order to work on the provider, Go should be installed first (version 1.8+ is required). goenv and gvm are great utilities that can help a lot with that and simplify setup tremendously. GOPATH should be setup correctly and as long as $GOPATH/bin should be added $PATH.

Source Code

Source code can be retrieved either with go get

$ go get -u -d github.com/ashald/terraform-provider-consulacl

or with git

$ mkdir -p ${GOPATH}/src/github.com/ashald/terraform-provider-consulacl
$ cd ${GOPATH}/src/github.com/ashald/terraform-provider-consulacl
$ git clone git@github.com:ashald/terraform-provider-consulacl.git .

Test

Unit Tests

$ make test
  go test -v ./...
  ?   	github.com/ashald/terraform-provider-consulacl	[no test files]
  === RUN   TestProvider
  --- PASS: TestProvider (0.00s)
  === RUN   TestIntegrationToken
  --- SKIP: TestIntegrationToken (0.00s)
  	testing.go:427: Acceptance tests skipped unless env 'TF_ACC' set
  === RUN   TestIntegrationTokenImport
  --- SKIP: TestIntegrationTokenImport (0.00s)
  	testing.go:427: Acceptance tests skipped unless env 'TF_ACC' set
  PASS
  ok  	github.com/ashald/terraform-provider-consulacl/consulacl	(cached)
  go vet ./...

Integration Tests

This requires a running Consul agent locally.

$ make test-integration
  TF_ACC=1 go test -v ./... -timeout 1m
  ?   	github.com/ashald/terraform-provider-consulacl	[no test files]
  === RUN   TestProvider
  --- PASS: TestProvider (0.00s)
  === RUN   TestIntegrationToken
  --- PASS: TestIntegrationToken (0.30s)
  === RUN   TestIntegrationTokenImport
  --- PASS: TestIntegrationTokenImport (0.06s)
  PASS
  ok  	github.com/ashald/terraform-provider-consulacl/consulacl	0.391s

If you have Docker installed, you can run Consul with the following command:

$ make test-server
  latest: Pulling from library/consul
  Digest: sha256:ae2c9409a77533485982c00f5c1eab89c090889318cb2f4276d64a7d125f83f8
  Status: Image is up to date for consul:latest
  docker run --rm -p 127.0.0.1:8500:8500 -e CONSUL_LOCAL_CONFIG='{"acl_datacenter": "dc1", "acl_master_token": "secret", "bootstrap_expect": 1, "server": true, "ui": true}' 'consul:latest'
  ...

By default, this will use the latest version of Consul based on the latest image in the Docker repository. You can specify a version using CONSUL_VERSION environment variable:

$ CONSUL_VERSION=1.2.0 make test-server

This command will run in foreground and will stop Consul when interrupted. Images will be cached locally by Docker so it is quick to restart the server as necessary. This will expose Consul on the default address 127.0.0.1:8500 but this can be changed with CONSUL_ADDRESS environment variable.

Build

In order to build plugin for the current platform use [GNU]make:

$ make build
  go build -o terraform-provider-consulacl_v1.1.0

it will build provider from sources and put it into current working directory.

If Terraform was installed (as a binary) or via go get -u github.com/hashicorp/terraform it'll pick up the plugin if executed against a configuration in the same directory.

Release

In order to prepare provider binaries for all platforms:

$ make release
  GOOS=darwin GOARCH=amd64 go build -o './release/terraform-provider-consulacl_v1.1.0-darwin-amd64'
  GOOS=linux GOARCH=amd64 go build -o './release/terraform-provider-consulacl_v1.1.0-linux-amd64'

Versioning

This project follow Semantic Versioning

Changelog

This project follows keep a changelog guidelines for changelog.

Contributors

Please see CONTRIBUTORS.md

License

This is free and unencumbered software released into the public domain. See LICENSE