github/wp-opentofu
0
0
Fork 0
mirror of https://github.com/thegeeklab/wp-opentofu.git synced 2024-11-22 10:40:39 +00:00
Code Issues Releases Activity

Update DOCS for plugin registry

Browse Source
This commit is contained in:
Jacob McCann 2016-12-23 09:47:33 -06:00
parent 7e298aaf16
commit 025e5067e7
1 changed files with 134 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

270
DOCS.md
View File

@ -1,201 +1,162 @@
Use the Terraform plugin to apply the infrastructure configuration contained within the repository. The following parameters are used to configure this plugin: ---
date: 2016-01-01T00:00:00+00:00
title: Terraform
author: jmccann
tags: [ infrastructure, build tool ]
repo: jmccann/drone-terraform
logo: terraform.svg
image: jmccann/drone-terraform
---
* `plan` - if true, calculates a plan but does __NOT__ apply it. The Terraform plugin applies the infrastructure configuration contained within the repository. The below pipeline configuration demonstrates simple usage:
* `remote` - contains the configuration for the Terraform remote state tracking.
* `backend` - the Terraform remote state backend to use.
* `config` - a map of configuration parameters for the remote state backend. Each value is passed as a `-backend-config=<key>=<value>` option.
* `vars` - a map of variables to pass to the Terraform `plan` and `apply` commands. Each value is passed as a `-var
<key>=<value>` option.
* `secrets` - a map of variables to pass to the Terraform `plan` and `apply` commands. Each value is passed as a `-var
<key>=<ENVVAR>` option. The `ENVVAR` is read as the key/pair value.
* `ca_cert` - ca cert to add to your environment to allow terraform to use internal/private resources
* `sensitive` (default: `false`) - Whether or not to suppress terraform commands to stdout.
* `role_arn_to_assume` - A role to assume before running the terraform commands.
* `root_dir` - The root directory where the terraform files live. When unset, the top level directory will be assumed.
* `parallelism` - The number of concurrent operations as Terraform walks its graph.
The following is a sample Terraform configuration in your .drone.yml file:
```yaml ```yaml
pipeline: pipeline:
terraform: terraform:
image: jmccann/drone-terraform:1 image: jmccann/drone-terraform:1
plan: false plan: false
remote:
backend: S3
config:
bucket: my-terraform-config-bucket
key: tf-states/my-project
region: us-east-1
vars:
app_name: my-project
app_version: 1.0.0
secrets:
my_secret: TERRAFORM_SECRET
``` ```
# Advanced Configuration Example configuration passing `vars` to terraform commands:
## CA Certs ```diff
You may want to run terraform against internal resources, like an internal
OpenStack deployment. Usually these resources are signed by an internal
CA Certificate. You can inject your CA Certificate into the plugin by using
`ca_certs` key as described above. Below is an example.
```yaml
pipeline: pipeline:
terraform: terraform:
image: jmccann/drone-terraform:1 image: jmccann/drone-terraform:1
plan: false plan: false
remote: + vars:
backend: swift + app_name: my-project
config: + app_version: 1.0.0
path: drone/terraform ```
vars:
app_name: my-project Example configuration passing secrets to terraform via `vars`. The following
app_version: 1.0.0 example will call `terraform apply -var my_secret=${TERRAFORM_SECRET}`:
ca_cert: |
-----BEGIN CERTIFICATE----- ```diff
asdfsadf pipeline:
asdfsadf terraform:
-----END CERTIFICATE------- image: jmccann/drone-terraform:1
plan: false
+ secrets:
+ my_secret: TERRAFORM_SECRET
``` ```
## Suppress Sensitive Output
You may be passing sensitive vars to your terraform commands. If you do not want You may be passing sensitive vars to your terraform commands. If you do not want
the terraform commands to display in your drone logs then set `sensitive` to `true`. the terraform commands to display in your drone logs then set `sensitive` to `true`.
The output from the commands themselves will still display, it just won't show The output from the commands themselves will still display, it just won't show
want command is actually being ran. what command is actually being ran.
```yaml ```diff
pipeline: pipeline:
terraform: terraform:
image: jmccann/drone-terraform:1 image: jmccann/drone-terraform:1
plan: false plan: false
sensitive: true + sensitive: true
remote:
backend: S3
config:
bucket: my-terraform-config-bucket
key: tf-states/my-project
region: us-east-1
vars:
app_name: my-project
app_version: 1.0.0
``` ```
## Assume Role ARN Example configuration with state tracked via remote:
You may want to assume another role before running the terraform commands. This is useful for cross account access, where a central account ahs privileges to assume roles in other accounts. Using the current credentials, this role will be assumed and exported to environment variables. See [the discussion](https://github.com/hashicorp/terraform/issues/1275) in the Terraform issues.
```yaml ```diff
pipeline: pipeline:
terraform: terraform:
image: jmccann/drone-terraform:1 image: jmccann/drone-terraform:1
plan: false plan: false
remote: + remote:
backend: S3 + backend: S3
config: + config:
bucket: my-terraform-config-bucket + bucket: my-terraform-config-bucket
key: tf-states/my-project + key: tf-states/my-project
region: us-east-1 + region: us-east-1
vars:
app_name: my-project
app_version: 1.0.0
role_arn_to_assume: arn:aws:iam::account-of-role-to-assume:role/name-of-role
``` ```
## Root dir You may want to run terraform against internal resources, like an internal
You may want to change directories before applying the terraform commands. This parameter is useful if you have multiple environments in different folders and you want to use different drone configurations to apply different environments. OpenStack deployment. Sometimes these resources are signed by an internal
CA Certificate. You can inject your CA Certificate into the plugin by using
`ca_certs` key as described above. Below is an example.
```yaml ```diff
pipeline: pipeline:
terraform: terraform:
image: jmccann/drone-terraform:1 image: jmccann/drone-terraform:1
plan: false plan: false
remote: + ca_cert: |
backend: S3 + -----BEGIN CERTIFICATE-----
config: + asdfsadf
bucket: my-terraform-config-bucket + asdfsadf
key: tf-states/my-project + -----END CERTIFICATE-------
region: us-east-1
vars:
app_name: my-project
app_version: 1.0.0
root_dir: some/path/here
``` ```
## Targets You may want to assume another role before running the terraform commands.
You may want to only target a specific list of resources within your terraform code. To achieve this you can specify the `targets` parameter. If left undefined all resources will be planned/applied against as the default behavior. This is useful for cross account access, where a central account has privileges
to assume roles in other accounts. Using the current credentials, this role will
be assumed and exported to environment variables.
See [the discussion](https://github.com/hashicorp/terraform/issues/1275) in the Terraform issues.
Single target: ```diff
```yaml
pipeline: pipeline:
terraform: terraform:
image: jmccann/drone-terraform:1 image: jmccann/drone-terraform:1
plan: false plan: false
targets: aws_security_group.generic_sg + role_arn_to_assume: arn:aws:iam::account-of-role-to-assume:role/name-of-role
remote:
backend: S3
config:
bucket: my-terraform-config-bucket
key: tf-states/my-project
region: us-east-1
vars:
app_name: my-project
app_version: 1.0.0
``` ```
Multiple targets: You may want to change directories before applying the terraform commands.
This parameter is useful if you have multiple environments in different folders
and you want to use different drone configurations to apply different environments.
```yaml ```diff
pipeline: pipeline:
terraform: terraform:
image: jmccann/drone-terraform:1 image: jmccann/drone-terraform:1
plan: false plan: false
targets: + root_dir: some/path/here
- aws_security_group.generic_sg ```
- aws_security_group.app_sg
remote: You may want to only target a specific list of resources within your terraform
backend: S3 code. To achieve this you can specify the `targets` parameter. If left undefined
config: all resources will be planned/applied against as the default behavior.
bucket: my-terraform-config-bucket
key: tf-states/my-project ```diff
region: us-east-1 pipeline:
vars: terraform:
app_name: my-project image: jmccann/drone-terraform:1
app_version: 1.0.0 plan: false
+ targets:
+ - aws_security_group.generic_sg
+ - aws_security_group.app_sg
``` ```
## Parallelism
You may want to limit the number of concurrent operations as Terraform walks its graph. You may want to limit the number of concurrent operations as Terraform walks its graph.
If you want to change Terraform's default parallelism (currently equal to 10) then set the `parallelism` parameter. If you want to change Terraform's default parallelism (currently equal to 10) then set the `parallelism` parameter.
```yaml ```diff
pipeline: pipeline:
terraform: terraform:
image: jmccann/drone-terraform:1 image: jmccann/drone-terraform:1
plan: false plan: false
+ parallelism: 2
```
If you need to set different ENV secrets for multiple `terraform` steps you can utilize `secrets`.
The following example shows using different remotes secrets each step.
```yaml
pipeline:
dev_terraform:
image: jmccann/drone-terraform:1
plan: false
remote: remote:
backend: S3 backend: S3
config: config:
bucket: my-terraform-config-bucket bucket: my-terraform-config-bucket
key: tf-states/my-project key: tf-states/my-project
region: us-east-1 region: us-east-1
vars: + secrets:
app_name: my-project + AWS_ACCESS_KEY_ID: DEV_AWS_ACCESS_KEY_ID
app_version: 1.0.0 + AWS_SECRET_ACCESS_KEY: DEV_AWS_SECRET_ACCESS_KEY
parallelism: 2
```
## Remote configuration prod_terraform:
image: jmccann/drone-terraform:1
If you are configuring an s3 remote state and require S3 environment secrets you add the secrets "FOO" and "BAR" to your drone environment and reference the secrets as follows. These will not be outputted to stdout.
```yaml
pipeline:
terraform:
image: jmccann/drone-terraform:0.5
plan: false plan: false
remote: remote:
backend: S3 backend: S3
@ -203,10 +164,47 @@ pipeline:
bucket: my-terraform-config-bucket bucket: my-terraform-config-bucket
key: tf-states/my-project key: tf-states/my-project
region: us-east-1 region: us-east-1
vars: + secrets:
app_name: my-project + AWS_ACCESS_KEY_ID: PROD_AWS_ACCESS_KEY_ID
app_version: 1.0.0 + AWS_SECRET_ACCESS_KEY: PROD_AWS_SECRET_ACCESS_KEY
secrets:
AWS_ACCESS_KEY_ID: FOO
AWS_SECRET_ACCESS_KEY: BAR
``` ```
# Parameter Reference
plan
: if true, calculates a plan but does __NOT__ apply it.
remote
: contains the configuration for the Terraform remote state tracking.
remote.backend
: the Terraform remote state backend to use.
remote.config
: a map of configuration parameters for the remote state backend.
Each value is passed as a `-backend-config=<key>=<value>` option.
vars
: a map of variables to pass to the Terraform `plan` and `apply` commands.
Each value is passed as a `-var <key>=<value>` option.
secrets
: a map of variables to pass to the Terraform `plan` and `apply` commands as well as setting envvars.
The `key` is the var and ENV to set. The `value` is the ENV to read the value from.
* Each entry generate a terraform var as follows: `-var <key>=$<value>`
* Additionally each entry generate sets and envvar as follows: `key=$value`
ca_cert
: ca cert to add to your environment to allow terraform to use internal/private resources
sensitive
: (default: `false`) - Whether or not to suppress terraform commands to stdout.
role_arn_to_assume
: A role to assume before running the terraform commands.
root_dir
: The root directory where the terraform files live. When unset, the top level directory will be assumed.
parallelism
: The number of concurrent operations as Terraform walks its graph.