-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
11 changed files
with
514 additions
and
300 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,56 +2,14 @@ | |
|
|
||
| ## Overview | ||
|
|
||
| This provider defines a Terraform resource that allows one to manage Consul ACL tokens with Terraform. | ||
| This provider defines Terraform resources and data sources related to Consul ACL subsystem that are missing from the official one. | ||
| *PLEASE NOTE THAT USING THIS PROVIDER WOULD EXPOSE SENSITIVE TOKEN ID VALUES IN YOUR STATE.* | ||
|
|
||
| ## Resources | ||
| This plugin defines following resources: | ||
| * [resource "consulacl_token"](./docs/resource_consulacl_token.md) - manages a single Consul ACL token (legacy API, pre Consul 1.4) | ||
|
|
||
| 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. | ||
| This plugin defines following data sources: | ||
| * [data "consulacl_token"](./docs/data_source_consulacl_token.md) - retrieves post-Consul 1.4 ACL token's secret ID by its accessor ID | ||
|
|
||
| ## Installation | ||
|
|
||
|
|
@@ -70,257 +28,53 @@ Currently Terraform is able to automatically download only | |
| 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](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins). | ||
|
|
||
| ## Usage | ||
|
|
||
| ### main.tf | ||
| ```hcl | ||
| 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 | ||
| The simplest way to get started is: | ||
| ```bash | ||
| $ wget "https://github.com/ashald/terraform-provider-consulacl/releases/download/v1.1.1/terraform-provider-consulacl_v1.1.1-$(uname -s | tr '[:upper:]' '[:lower:]')-amd64" | ||
| $ chmod +x ./terraform-provider-transform* | ||
| ``` | ||
|
|
||
| ### Init | ||
| ```bash | ||
| $ ls -1 | ||
| main.tf | ||
| terraform-provider-consulacl_v1.1.1-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 | ||
| ```bash | ||
| $ 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 | ||
| ## Configuration | ||
|
|
||
| ```bash | ||
| $ 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. | ||
| ``` | ||
| Provider is configurable with number of parameters: | ||
|
|
||
| ```hcl | ||
| provider "consulacl" { | ||
| // Host and port used to connect to Consul. | ||
| // Can be set via environment variables `CONSUL_ADDRESS` or `CONSUL_HTTP_ADDR`. | ||
| address = "localhost:8500" | ||
| // ACL token to use for API calls to Consul. Must be a `management` token to manage ACLs. | ||
| // Can be set via environment variables `CONSUL_TOKEN` or `CONSUL_HTTP_TOKEN`. | ||
| token = "" | ||
| // Scheme to use to connect to Consul. | ||
| // Can be set via environment variables `CONSUL_SCHEME` or `CONSUL_HTTP_SCHEME`. | ||
| scheme = "http" // Only "http" and "https" are supported. | ||
| // 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. | ||
| // Can be set via environment variable `CONSUL_CA_FILE`. | ||
| ca_file = "" // Empty value means use system bundle. | ||
| // Path to a client certificate for client-side TLS authentication, if enabled in Consul. | ||
| // Can be set via environment variable `CONSUL_CERT_FILE`. | ||
| cert_file = "" | ||
| // Path to a private key for client certificate provided in `cert_file`. | ||
| // Can be set via environment variable `CONSUL_KEY_FILE`. | ||
| key_file = "" | ||
| // Whether to skip verification of Consul's TLS certificate. | ||
| // Can be set via environment variable `CONSUL_TLS_SKIP_VERIFY`. | ||
| tls_skip_verify = false | ||
| } | ||
| ``` | ||
|
|
||
| ## Development | ||
|
|
||
| ### Go | ||
| In order to work on the provider, [Go](http://www.golang.org) should be installed first (version 1.8+ is *required*). | ||
| [goenv](https://github.com/syndbg/goenv) and [gvm](https://github.com/moovweb/gvm) are great utilities that can help a | ||
| lot with that and simplify setup tremendously. | ||
| [GOPATH](http://golang.org/doc/code.html#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` | ||
| ```bash | ||
| $ go get -u -d github.com/ashald/terraform-provider-consulacl | ||
| ``` | ||
| or with `git` | ||
| ```bash | ||
| $ mkdir -p ${GOPATH}/src/github.com/ashald/terraform-provider-consulacl | ||
| $ cd ${GOPATH}/src/github.com/ashald/terraform-provider-consulacl | ||
| $ git clone [email protected]:ashald/terraform-provider-consulacl.git . | ||
| ``` | ||
| ### Dependencies | ||
| This project uses `govendor` to manage its dependencies. When adding a dependency on a new package it should be fetched | ||
| with: | ||
| ```bash | ||
| $ govendor fetch +o | ||
| ``` | ||
| ### Test | ||
| #### Unit Tests | ||
| ```bash | ||
| $ 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. | ||
| ```bash | ||
| $ 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](https://docs.docker.com/install/) installed, you can run Consul with the following command: | ||
| ```bash | ||
| $ 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](https://hub.docker.com/_/consul/). | ||
| You can specify a version using `CONSUL_VERSION` environment variable: | ||
| ```bash | ||
| $ 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: | ||
| ```bash | ||
| $ make build | ||
| go build -o terraform-provider-consulacl_v1.1.1 | ||
|
|
||
| ``` | ||
| 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: | ||
| ```bash | ||
| $ make release | ||
| GOOS=darwin GOARCH=amd64 go build -o './release/terraform-provider-consulacl_v1.1.1-darwin-amd64' | ||
| GOOS=linux GOARCH=amd64 go build -o './release/terraform-provider-consulacl_v1.1.1-linux-amd64' | ||
| ``` | ||
| ### Versioning | ||
| This project follow [Semantic Versioning](https://semver.org/) | ||
| ### Changelog | ||
| This project follows [keep a changelog](https://keepachangelog.com/en/1.0.0/) guidelines for changelog. | ||
| ### Contributors | ||
| Please see [CONTRIBUTORS.md](./CONTRIBUTORS.md) | ||
| **terraform-provider-consulacl** is written and maintained by [Borys Pierov](https://github.com/Ashald). | ||
| Contributions are welcome and should follow [development guidelines](./docs/development.md) and are reflected in [CONTRIBUTORS.md](./CONTRIBUTORS.md). | ||
|
|
||
| ## License | ||
|
|
||
|
|
||
Oops, something went wrong.