This is a collection of reusable Terraform "root modules" invocations for CloudPosse AWS accounts.
Terraform defines a "root module" as the current working directory holding the Terraform configuration files where the terraform apply or terraform get is run.
This project is part of our comprehensive "SweetOps" approach towards DevOps.
It's 100% Open Source and licensed under the APACHE2.
In this repo you'll find real-world examples of how we've implemented various common patterns using our terraform modules for our customers.
The "root modules" form the module catalog of your organization. It's from this catalog that other developers in your organization will pick and choose from anytime they need to deploy some new capability.
Normally, a company should build up their own service catalog of terraform modules like this one, which is just a collection of terraform modules that capture the business logic, opinions, "best practices" and non-functional requirements of the organization.
No two companies will ever have the same assembly of terraform-root-modules.
The root modules are the most opinionated incarnations of modules that seldom translate verbatim across organizations. This is your secret sauce. We could never implement this in a sufficiently generic way without creating crazy bloat and complexity. Therefore treat the terraform-root-modules in this repository as your “starting off point” where you hardfork/diverge. These modules are very specific to how we do things in our environment, so they might not "drop in" smoothly in other environments as they make a lot of assumptions on how things are organized.
A company writes their own root modules. It’s their flavor of how to leverage the generic building blocks to achieve the specific customizations that are required without needing to write everything from the ground up because they are leveraging our general purpose modules.
The idea is to write all of the terraform-aws-* type modules very generically so they are easily composable inside of other modules.
These terraform-root-modules make a lot of assumptions about how we've configured our environments. That said, they can still serve as an excellent reference for others.
We recommend that you start with your clean terraform-root-module repo. Then start by creating a new project in there to describe the infrastructure that you want.
- Every "root module" should include a
Makefilethat definesinit,plan, andapplytargets. This establishes a common interface for interacting with terraform without the need of a wrapper liketerragrunt. - Never compose "root modules" inside of other root modules. If or when this is desired, then the module should be split off into a new repository and versioned independently as a standalone module.
Here's a good example of a Makefile for a terraform project:
## Initialize terraform remote state
init:
[ -f .terraform/terraform.tfstate ] || terraform $@
## Clean up the project
clean:
rm -rf .terraform *.tfstate*
## Pass arguments through to terraform which require remote state
apply console destroy graph plan output providers show: init
terraform $@
## Pass arguments through to terraform which do not require remote state
get fmt validate version:
terraform $@
As of this writing, our terraform-root-modules and nearly all of our Terraform modules only work
with Terraform v0.11. Terraform v0.12 uses a major redesign
of HCL, the language in which Terraform modules are written, and is not compatible with the language used in v0.11.
It is expected that this will result in a strong split between how v0.11 is used and how v0.12 is used in the
future. Theses instructions are for environments exclusively using Terraform v0.11.
With the CloudPosse reference architecture, each environment (e.g. staging and prod) has its own, customized version of Geodesic. The process for using one of these Terraform root modules is one of further customizing the environment's Geodesic as follows:
- Create a directory under
/confto contain the files related to the root module. Normally the directory has the same name as the root module. - Copy the
.envrc,Makefile.tasks, andterraform.envrcfiles fromcloudposse/reference-architectures/templates/conf/kopsinto the new directory. The.envrcandMakefile.tasksfiles are boilerplate and do not need to be changed. - Edit the
terraform.envrcfile so that theTF_CLI_INIT_FROM_MODULEpoints to the desired Terraform root module. Be sure to pin it to a specific version. Add additional environment variable settings if desired. - Add a
terraform.tfvarsfile that sets the values of all the inputs to your Terraform root module that need to be set (i.e. that do not have acceptable defaults).
Then build, install, and run your Geodesic shell.
Then, from within the Geodesic shell, after going through the authorization steps such as assume-role, cd to the
new folder. The built-in envrc hook will configure the shell for Terraform automatically as a result of the cd.
Then, make deps will download the Terraform modules and initialze the Terraform state.
Then you can use terraform plan and terraform apply to preview and apply the changes dictated by the module.
For example usage, refer to the "Related Projects" section. This is were we use terraform-root-modules to provision essential account-level infrastructure, among other services.
Available targets:
help Help screen
help/all Display help for all targets
help/short This help short screen
Like this project? Please give it a ★ on our GitHub! (it helps us a lot)
Are you using this project or any of our other projects? Consider leaving a testimonial. =)
Check out these related projects.
- reference-architectures - Get up and running quickly with one of our reference architecture using our fully automated cold-start process.
- audit.cloudposse.co - Example Terraform Reference Architecture of a Geodesic Module for an Audit Logs Organization in AWS.
- prod.cloudposse.co - Example Terraform Reference Architecture of a Geodesic Module for a Production Organization in AWS.
- staging.cloudposse.co - Example Terraform Reference Architecture of a Geodesic Module for a Staging Organization in AWS.
- dev.cloudposse.co - Example Terraform Reference Architecture of a Geodesic Module for a Development Sandbox Organization in AWS.
For additional context, refer to some of these links.
- Cloud Posse Documentation - Complete documentation for the Cloud Posse solution
Got a question?
File a GitHub issue, send us an email or join our Slack Community.
Work directly with our team of DevOps experts via email, slack, and video conferencing.
We provide commercial support for all of our Open Source projects. As a Dedicated Support customer, you have access to our team of subject matter experts at a fraction of the cost of a full-time engineer.
- 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.
Join our Open Source Community on Slack. It's FREE 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 totally sweet infrastructure.
Signup for our newsletter that covers everything on our technology radar. Receive updates on what we're up to on GitHub as well as awesome new projects we discover.
Please use the issue tracker to report any bugs or file feature requests.
If you are interested in being a contributor and want to get involved in developing this project or help out with our other projects, we would love to hear from you! Shoot us an email.
In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- 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 © 2017-2019 Cloud Posse, LLC
See LICENSE for full details.
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
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
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
All other trademarks referenced herein are the property of their respective owners.
This project is maintained and funded by Cloud Posse, LLC. Like it? Please let us know by leaving a testimonial!
We're a DevOps Professional Services company based in Los Angeles, CA. We ❤️ Open Source Software.
We offer paid support on all of our projects.
Check out our other projects, follow us on twitter, apply for a job, or hire us to help with your cloud strategy and implementation.
 Erik Osterman |
 Igor Rodionov |
 Andriy Knysh |
|---|