Skip to content

Commit

Permalink
Migrate readme yaml (#6)
Browse files Browse the repository at this point in the history
  • Loading branch information
@vadim-gleif
vadim-gleif authored Jul 11, 2018
1 parent 855c618 commit 766e5c1
Show file tree
Hide file tree
Showing 7 changed files with 290 additions and 52 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,6 @@
.terraform/
.idea
terraform-aws-tfstate-backend.iml

.build-harness
build-harness
6 changes: 5 additions & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
SHELL := /bin/bash

# List of targets the `readme` target should call before generating the readme
export README_DEPS ?= docs/targets.md docs/terraform.md

-include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)

## Lint terraform code
lint:
$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate
$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate
164 changes: 119 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
# terraform-aws-tfstate-backend [![Build Status](https://travis-ci.org/cloudposse/terraform-aws-tfstate-backend.svg?branch=master)](https://travis-ci.org/cloudposse/terraform-aws-tfstate-backend)
<!-- This file was automatically generated by the `build-harness`. Make all changes to `README.yaml` and run `make readme` to rebuild this file. -->

[![Cloud Posse](https://cloudposse.com/logo-300x69.svg)](https://cloudposse.com)

# terraform-aws-tfstate-backend [![Build Status](https://travis-ci.org/cloudposse/terraform-aws-tfstate-backend.svg?branch=master)](https://travis-ci.org/cloudposse/terraform-aws-tfstate-backend) [![Latest Release](https://img.shields.io/github/release/cloudposse/terraform-aws-tfstate-backend.svg)](https://github.com/cloudposse/terraform-aws-tfstate-backend/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)


Terraform module to provision an S3 bucket to store `terraform.tfstate` file and a DynamoDB table to lock the state file
to prevent concurrent modifications and state corruption.
Expand All @@ -16,6 +21,17 @@ https://www.terraform.io/docs/backends/types/s3.html
__NOTE:__ The operators of the module (IAM Users) must have permissions to create S3 buckets and DynamoDB tables when performing `terraform plan` and `terraform apply`


---

This project is part of our comprehensive ["SweetOps"](https://docs.cloudposse.com) approach towards DevOps.


It's 100% Open Source and licensed under the [APACHE2](LICENSE).





## Usage

```hcl
Expand Down Expand Up @@ -66,42 +82,86 @@ and the DynamoDB table will be used to lock the state to prevent concurrent modi
![s3-bucket-with-terraform-state](images/s3-bucket-with-terraform-state.png)


## Variables

| Name | Default | Description | Required |
|:---------------------------------|:-------------|:----------------------------------------------------------------------------------|:--------:|
| `namespace` | `` | Namespace (_e.g._ `cp` or `cloudposse`) | Yes |
| `stage` | `` | Stage (_e.g._ `prod`, `dev`, `staging`) | Yes |
| `region` | `` | AWS Region the S3 bucket should reside in | Yes |
| `name` | `terraform` | Name (_e.g._ `app`, `cluster`, or `terraform`) | No |
| `attributes` | `["state"]` | Additional attributes (_e.g._ `state`) | No |
| `tags` | `{}` | Additional tags (_e.g._ `map("BusinessUnit","XYZ")` | No |
| `delimiter` | `-` | Delimiter to be used between `namespace`, `stage`, `name`, and `attributes` | No |
| `acl` | `private` | The canned ACL to apply to the S3 bucket | No |
| `read_capacity` | `5` | DynamoDB read capacity units | No |
| `write_capacity` | `5` | DynamoDB write capacity units | No |
| `force_destroy` | `false` | A boolean that indicates the S3 bucket can be destroyed even if it contains objects. These objects are not recoverable | No |
| `enable_server_side_encryption` | `true` | Enable DynamoDB server-side encryption | No |



## Makefile Targets
```
Available targets:
help This help screen
help/all Display help for all targets
lint Lint terraform code
```

## Inputs

| Name | Description | Type | Default | Required |
|------|-------------|:----:|:-----:|:-----:|
| acl | The canned ACL to apply to the S3 bucket | string | `private` | no |
| attributes | Additional attributes (e.g. `state`) | list | `<list>` | no |
| delimiter | Delimiter to be used between `namespace`, `stage`, `name`, and `attributes` | string | `-` | no |
| enable_server_side_encryption | Enable DynamoDB server-side encryption | string | `true` | no |
| force_destroy | A boolean that indicates the S3 bucket can be destroyed even if it contains objects. These objects are not recoverable | string | `false` | no |
| name | Name (e.g. `app` or `cluster`) | string | `terraform` | no |
| namespace | Namespace (e.g. `cp` or `cloudposse`) | string | - | yes |
| read_capacity | DynamoDB read capacity units | string | `5` | no |
| region | AWS Region the S3 bucket should reside in | string | - | yes |
| stage | Stage (e.g. `prod`, `dev`, `staging`) | string | - | yes |
| tags | Additional tags (e.g. map(`BusinessUnit`,`XYZ`) | map | `<map>` | no |
| write_capacity | DynamoDB write capacity units | string | `5` | no |

## Outputs

| Name | Description |
|:-------------------------|:-----------------------------|
| `s3_bucket_domain_name` | S3 bucket domain name |
| `s3_bucket_id` | S3 bucket ID |
| `s3_bucket_arn` | S3 bucket ARN |
| `dynamodb_table_id` | DynamoDB table ID |
| `dynamodb_table_arn` | DynamoDB table ARN |
| `dynamodb_table_name` | DynamoDB table name |
| Name | Description |
|------|-------------|
| dynamodb_table_arn | DynamoDB table ARN |
| dynamodb_table_id | DynamoDB table ID |
| dynamodb_table_name | DynamoDB table name |
| s3_bucket_arn | S3 bucket ARN |
| s3_bucket_domain_name | S3 bucket domain name |
| s3_bucket_id | S3 bucket ID |




## Related Projects

Check out these related projects.

- [terraform-aws-dynamodb](https://github.com/cloudposse/terraform-aws-dynamodb) - Terraform module that implements AWS DynamoDB with support for AutoScaling
- [terraform-aws-dynamodb-autoscaler](https://github.com/cloudposse/terraform-aws-dynamodb-autoscaler) - Terraform module to provision DynamoDB autoscaler



## Help

**Got a question?**

File a GitHub [issue](https://github.com/cloudposse/terraform-aws-tfstate-backend/issues), send us an [email](mailto:[email protected]) or reach out to us on [Gitter](https://gitter.im/cloudposse/).
File a GitHub [issue](https://github.com/cloudposse/terraform-aws-tfstate-backend/issues), send us an [email][email] or join our [Slack Community][slack].

## Commerical Support

Work directly with our team of DevOps experts via email, slack, and video conferencing.

We provide *commercial support* for all of our [Open Source][github] projects. As a *Dedicated Support* customer, you have access to our team of subject matter experts at a fraction of the cost of a fulltime engineer.

[![E-Mail](https://img.shields.io/badge/[email protected])](mailto:[email protected])

- **Questions.** We'll use a Shared Slack channel between your team and ours.
- **Troubleshooting.** We'll help you triage why things aren't working.
- **Code Reviews.** We'll review your Pull Requests and provide constructive feedback.
- **Bug Fixes.** We'll rapidly work to fix any bugs in our projects.
- **Build New Terraform Modules.** We'll develop original modules to provision infrastructure.
- **Cloud Architecture.** We'll assist with your cloud strategy and design.
- **Implementation.** We'll provide hands on support to implement our reference architectures.


## Community Forum

Get access to our [Open Source Community Forum][slack] on Slack. It's **FREE** to join for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build *sweet* infrastructure.

## Contributing

Expand All @@ -111,22 +171,28 @@ Please use the [issue tracker](https://github.com/cloudposse/terraform-aws-tfsta

### Developing

If you are interested in being a contributor and want to get involved in developing `terraform-aws-tfstate-backend`, we would love to hear from you! Shoot us an [email](mailto:[email protected]).
If you are interested in being a contributor and want to get involved in developing this project or [help out](https://github.com/orgs/cloudposse/projects/3) with our other projects, we would love to hear from you! Shoot us an [email](mailto:[email protected]).

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

1. **Fork** the repo on GitHub
2. **Clone** the project to your own machine
3. **Commit** changes to your own branch
4. **Push** your work back up to your fork
5. Submit a **Pull request** so that we can review your changes
5. Submit a **Pull Request** so that we can review your changes

**NOTE:** Be sure to merge the latest changes from "upstream" before making a pull request!


## Copyright

Copyright © 2017-2018 [Cloud Posse, LLC](https://cloudposse.com)

**NOTE:** Be sure to merge the latest from "upstream" before making a pull request!


## License
## License

[APACHE 2.0](LICENSE) © 2018 [Cloud Posse, LLC](https://cloudposse.com)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

See [LICENSE](LICENSE) for full details.

Expand All @@ -138,7 +204,7 @@ See [LICENSE](LICENSE) for full details.
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
Expand All @@ -148,31 +214,39 @@ See [LICENSE](LICENSE) for full details.
under the License.


## About
## Trademarks

All other trademarks referenced herein are the property of their respective owners.

`terraform-aws-tfstate-backend` is maintained and funded by [Cloud Posse, LLC][website].
## About

![Cloud Posse](https://cloudposse.com/logo-300x69.png)
This project is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at <hello@cloudposse.com>

[![Cloud Posse](https://cloudposse.com/logo-300x69.svg)](https://cloudposse.com)

Like it? Please let us know at <hello@cloudposse.com>
We're a [DevOps Professional Services][hire] company based in Los Angeles, CA. We love [Open Source Software](https://github.com/cloudposse/)!

We love [Open Source Software](https://github.com/cloudposse/)!
We offer paid support on all of our projects.

See [our other projects][community]
or [hire us][hire] to help build your next cloud platform.
Check out [our other projects][github], [apply for a job][jobs], or [hire us][hire] to help with your cloud strategy and implementation.

[docs]: https://docs.cloudposse.com/
[website]: https://cloudposse.com/
[community]: https://github.com/cloudposse/
[github]: https://github.com/cloudposse/
[jobs]: https://cloudposse.com/jobs/
[hire]: https://cloudposse.com/contact/
[slack]: https://slack.cloudposse.com/
[linkedin]: https://www.linkedin.com/company/cloudposse
[twitter]: https://twitter.com/cloudposse/
[email]: mailto:[email protected]


### Contributors

| [![Erik Osterman][erik_img]][erik_web]<br/>[Erik Osterman][erik_web] | [![Andriy Knysh][andriy_img]][andriy_web]<br/>[Andriy Knysh][andriy_web] |
|-------------------------------------------------------|------------------------------------------------------------------|
| [![Andriy Knysh][aknysh_avatar]][aknysh_homepage]<br/>[Andriy Knysh][aknysh_homepage] |
|---|

[aknysh_homepage]: https://github.com/aknysh
[aknysh_avatar]: https://github.com/aknysh.png?size=150


[erik_img]: http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144
[erik_web]: https://github.com/osterman/
[andriy_img]: https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144
[andriy_web]: https://github.com/aknysh/
113 changes: 113 additions & 0 deletions README.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
---
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-aws-tfstate-backend

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-tfstate-backend

# Badges to display
badges:
- name: "Build Status"
image: "https://travis-ci.org/cloudposse/terraform-aws-tfstate-backend.svg?branch=master"
url: "https://travis-ci.org/cloudposse/terraform-aws-tfstate-backend"
- name: "Latest Release"
image: "https://img.shields.io/github/release/cloudposse/terraform-aws-tfstate-backend.svg"
url: "https://github.com/cloudposse/terraform-aws-tfstate-backend/releases/latest"
- name: "Slack Community"
image: "https://slack.cloudposse.com/badge.svg"
url: "https://slack.cloudposse.com"

related:
- name: "terraform-aws-dynamodb"
description: "Terraform module that implements AWS DynamoDB with support for AutoScaling"
url: "https://github.com/cloudposse/terraform-aws-dynamodb"
- name: "terraform-aws-dynamodb-autoscaler"
description: "Terraform module to provision DynamoDB autoscaler"
url: "https://github.com/cloudposse/terraform-aws-dynamodb-autoscaler"

# Short description of this project
description: |-
Terraform module to provision an S3 bucket to store `terraform.tfstate` file and a DynamoDB table to lock the state file
to prevent concurrent modifications and state corruption.
The module supports the following:
1. Forced server-side encryption at rest for the S3 bucket
2. S3 bucket versioning to allow for Terraform state recovery in the case of accidental deletions and human errors
3. State locking and consistency checking via DynamoDB table to prevent concurrent operations
4. DynamoDB server-side encryption
https://www.terraform.io/docs/backends/types/s3.html
__NOTE:__ The operators of the module (IAM Users) must have permissions to create S3 buckets and DynamoDB tables when performing `terraform plan` and `terraform apply`
# How to use this project
usage: |-
```hcl
terraform {
required_version = ">= 0.11.3"
}
module "terraform_state_backend" {
source = "git::https://github.com/cloudposse/terraform-aws-tfstate-backend.git?ref=master"
namespace = "cp"
stage = "prod"
name = "terraform"
attributes = ["state"]
region = "us-east-1"
}
```
__NOTE:__ First create the bucket and table without any state enabled (Terraform will use the local file system to store state).
You can then import the bucket and table by using [`terraform import`](https://www.terraform.io/docs/import/index.html) and store the state file into the bucket.
Once the bucket and table have been created, configure the [backend](https://www.terraform.io/docs/backends/types/s3.html)
```hcl
terraform {
required_version = ">= 0.11.3"
backend "s3" {
region = "us-east-1"
bucket = "< the name of the S3 bucket >"
key = "terraform.tfstate"
dynamodb_table = "< the name of the DynamoDB table >"
encrypt = true
}
}
module "another_module" {
source = "....."
}
```
Initialize the backend with `terraform init`.
After `terraform apply`, `terraform.tfstate` file will be stored in the bucket,
and the DynamoDB table will be used to lock the state to prevent concurrent modifications.
<br/>
![s3-bucket-with-terraform-state](images/s3-bucket-with-terraform-state.png)
include:
- "docs/targets.md"
- "docs/terraform.md"

# Contributors to this project
contributors:
- name: "Andriy Knysh"
github: "aknysh"
9 changes: 9 additions & 0 deletions docs/targets.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
## Makefile Targets
```
Available targets:
help This help screen
help/all Display help for all targets
lint Lint terraform code
```
Loading

0 comments on commit 766e5c1

Please sign in to comment.