Skip to content

Commit 8b601b7

Browse files
brikis98brikis98
committed
Auto-generate docs for release v0.0.7 [ci skip]
1 parent e869ac3 commit 8b601b7

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+1103
-0
lines changed

‎README.md

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/README.md>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
5+
6+
# VPC Modules
7+
8+
This repo contains modules for creating best-practices Virtual Private Clouds (VPCs) on AWS.
9+
10+
#### Main Modules
11+
12+
The two main modules are:
13+
14+
* [vpc-app](/modules/vpc-app): Launch a VPC meant to house applications. The VPC includes 3 "tiers" of subnets
15+
(public, private app, private persistence), routing rules, security groups, network ACLs, and NAT gateways.
16+
* [vpc-mgmt](/modules/vpc-mgmt): Launch a VPC meant to house DevOps and other management services. The VPC includes
17+
2 "tiers" of subnets (public, private), routing rules, security groups, network ACLs, and NAT gateways.
18+
19+
#### Supporting Modules
20+
21+
There are also several supporting modules that add extra functionality on top of vpc-app and vpc-mgmt:
22+
23+
* [vpc-peering](/modules/vpc-peering): Creating peering connections between VPCs. Normally, VPCs are completely
24+
isolated from each other, but sometimes, you want to allow traffic to flow between them, such as allowing DevOps
25+
tools running in a Mgmt VPC to talk to apps in a Stage or Prod VPC. This module can create peering connections and
26+
route table entries that make this sort of cross-VPC communication possible.
27+
* [vpc-app-network-acls](/modules/vpc-app-network-acls): Add a default set of Network ACLs to a VPC created using the
28+
[vpc-app](/modules/vpc-app) module that control what inbound and outbound network traffic is allowed in each subnet
29+
of that VPC.
30+
* [vpc-mgmt-network-acls](/modules/vpc-mgmt-network-acls): Add a default set of Network ACLs to a VPC created using the
31+
[vpc-mgmt](/modules/vpc-mgmt) module that control what inbound and outbound network traffic is allowed in each subnet
32+
of that VPC.
33+
* [network-acl-inbound](/modules/network-acl-inbound): A simple helper for adding inbound rules to a Network ACL, along
34+
with the corresponding outbound rules for return traffic .
35+
* [network-acl-outbound](/modules/network-acl-outbound): A simple helper for adding outbound rules to a Network ACL,
36+
along with the correspoding inbound rules for return traffic.
37+
38+
Click on each module above to see its documentation. Head over to the [examples folder](/examples) for examples.
39+
40+
## What is a module?
41+
42+
At [Gruntwork](http://www.gruntwork.io), we've taken the thousands of hours we spent building infrastructure on AWS and
43+
condensed all that experience and code into pre-built **packages** or **modules**. Each module is a battle-tested,
44+
best-practices definition of a piece of infrastructure, such as a VPC, ECS cluster, or an Auto Scaling Group. Modules
45+
are versioned using [Semantic Versioning](http://semver.org/) to allow Gruntwork clients to keep up to date with the
46+
latest infrastructure best practices in a systematic way.
47+
48+
## How do you use a module?
49+
50+
Most of our modules contain either:
51+
52+
1. [Terraform](https://www.terraform.io/) code
53+
1. Scripts & binaries
54+
55+
#### Using a Terraform Module
56+
57+
To use a module in your Terraform templates, create a `module` resource and set its `source` field to the Git URL of
58+
this repo. You should also set the `ref` parameter so you're fixed to a specific version of this repo, as the `master`
59+
branch may have backwards incompatible changes (see [module
60+
sources](https://www.terraform.io/docs/modules/sources.html)).
61+
62+
For example, to use `v1.0.8` of the vpc-app module, you would add the following:
63+
64+
```hcl
65+
module "ecs_cluster" {
66+
source = "git::[email protected]:gruntwork-io/module-vpc.git//modules/vpc-app?ref=v1.0.8"
67+
68+
// set the parameters for the vpc-app module
69+
}
70+
```
71+
72+
*Note: the double slash (`//`) is intentional and required. It's part of Terraform's Git syntax (see [module
73+
sources](https://www.terraform.io/docs/modules/sources.html)).*
74+
75+
See the module's documentation and `vars.tf` file for all the parameters you can set. Run `terraform get -update` to
76+
pull the latest version of this module from this repo before runnin gthe standard `terraform plan` and
77+
`terraform apply` commands.
78+
79+
#### Using scripts & binaries
80+
81+
You can install the scripts and binaries in the `modules` folder of any repo using the [Gruntwork
82+
Installer](https://github.com/gruntwork-io/gruntwork-installer). For example, if the scripts you want to install are
83+
in the `modules/ecs-scripts` folder of the https://github.com/gruntwork-io/module-ecs repo, you could install them
84+
as follows:
85+
86+
```bash
87+
gruntwork-install --module-name "ecs-scripts" --repo "https://github.com/gruntwork-io/module-ecs" --tag "0.0.1"
88+
```
89+
90+
See the docs for each script & binary for detailed instructions on how to use them.
91+
92+
## What's a VPC?
93+
94+
A [VPC](https://aws.amazon.com/vpc/) or Virtual Private Cloud is a logically isolated section of your AWS cloud. Each
95+
VPC defines a virtual network within which you run your AWS resources, as well as rules for what can go in and out of
96+
that network. This includes subnets, route tables that tell those subnets how to route inbound and outbound traffic,
97+
security groups, firewalls for the subnet (known as "Network ACLs"), and any other network components such as VPN connections.
98+
99+
#### Learn More about VPCs
100+
101+
See the READMEs for the [vpc-app](/modules/vpc-app) and [vpc-mgmt](/modules/vpc-mgmt) modules for detailed info on a VPC,
102+
along with best practices.
103+
104+
## Developing a module
105+
106+
#### Versioning
107+
108+
We are following the principles of [Semantic Versioning](http://semver.org/). During initial development, the major
109+
version is to 0 (e.g., `0.x.y`), which indicates the code does not yet have a stable API. Once we hit `1.0.0`, we will
110+
follow these rules:
111+
112+
1. Increment the patch version for backwards-compatible bug fixes (e.g., `v1.0.8 -> v1.0.9`).
113+
2. Increment the minor version for new features that are backwards-compatible (e.g., `v1.0.8 -> 1.1.0`).
114+
3. Increment the major version for any backwards-incompatible changes (e.g. `1.0.8 -> 2.0.0`).
115+
116+
The version is defined using Git tags. Use GitHub to create a release, which will have the effect of adding a git tag.
117+
118+
#### Tests
119+
120+
See the [test](/test) folder for details.

‎circle.yml

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/circle.yml>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎examples/vpc-app/README.md

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/examples/vpc-app/README.md>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
5+
6+
# App VPC Example
7+
8+
This shows an example of how to use the [vpc-app](/modules/vpc-app) module to launch a VPC that can be used as a
9+
production or staging environment for your apps.
10+
11+
For more information on the core concepts behind the VPC, see the [vpc-app](/modules/vpc-app) module. For common
12+
usage-patterns with vpc-app, such as running multiple VPCs, launching EC2 instances in a VPC, setting up Network ACLs,
13+
and more, see the [vpc-network-acls](../vpc-network-acls) and [vpc-peering](../vpc-peering) examples.
14+
15+
## Quick start
16+
17+
To try these templates out you must have Terraform installed (minimum version: `0.6.11`):
18+
19+
1. Open `vars.tf`, set the environment variables specified at the top of the file, and fill in any other variables that
20+
don't have a default.
21+
1. Run `terraform get`.
22+
1. Run `terraform plan`.
23+
1. If the plan looks good, run `terraform apply`.
24+
25+
## Our VPC Structure
26+
27+
Our canonical VPC setup, based on the blog post [A Reference VPC
28+
Architecture](https://www.whaletech.co/2014/10/02/reference-vpc-architecture.html), is to have three VPCs:
29+
30+
- **Prod VPC**: For production workloads. You can create this type of VPC using the [vpc-app](/modules/vpc-app) module,
31+
as shown in the templates in this example.
32+
- **Stage VPC**: For non-production workloads. You can create this type of VPC using the [vpc-app](/modules/vpc-app)
33+
module, as shown in the templates in this example.
34+
- **Mgmt VPC**: Where operators run DevOps tooling and login. You can create this type of VPC using the
35+
[vpc-mgmt](/modules/vpc-mgmt) module, as shown in the [vpc-mgmt](../vpc-mgmt) example.
36+
37+
## Subnet Tiers
38+
39+
This VPC defines different "tiers" of private and public subnets that strictly control inbound and outbound access.
40+
See [vpc-app](/modules/vpc-app) and [vpc-network-acls](/examples/vpc-network-acls) for details.
41+
42+
## Known Errors
43+
44+
This terraform template may intermittently trigger certain non-critical errors caused by eventual consistency bugs in
45+
Terraform. These are usually harmless and all you need to do to get around them is to re-run `terraform apply`.

‎examples/vpc-app/main.tf

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/examples/vpc-app/main.tf>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎examples/vpc-app/outputs.tf

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/examples/vpc-app/outputs.tf>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎examples/vpc-app/vars.tf

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/examples/vpc-app/vars.tf>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎examples/vpc-mgmt/README.md

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/examples/vpc-mgmt/README.md>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
5+
6+
# Management VPC Example
7+
8+
This shows an example of how to use the [vpc-mgmt](/modules/vpc-mgmt) module to launch a VPC that can be used as a
9+
management and DevOps-tooling environment.
10+
11+
For more information on the core concepts behind the VPC, see the [vpc-mgmt](/modules/vpc-mgmt) module. For common
12+
usage-patterns with vpc-app, such as running multiple VPCs, launching EC2 instances in a VPC, setting up Network ACLs,
13+
and more, see the [vpc-network-acls](../vpc-network-acls) and [vpc-peering](../vpc-peering) examples.
14+
15+
## Quick start
16+
17+
To try these templates out you must have Terraform installed (minimum version: `0.6.11`):
18+
19+
1. Open `vars.tf`, set the environment variables specified at the top of the file, and fill in any other variables that
20+
don't have a default.
21+
1. Run `terraform get`.
22+
1. Run `terraform plan`.
23+
1. If the plan looks good, run `terraform apply`.
24+
25+
## Our VPC Structure
26+
27+
Our canonical VPC setup, based on the blog post [A Reference VPC
28+
Architecture](https://www.whaletech.co/2014/10/02/reference-vpc-architecture.html), is to have three VPCs:
29+
30+
- **Prod VPC**: For production workloads. You can create this type of VPC using the [vpc-app](/modules/vpc-app) module,
31+
as shown in the [vpc-app](../vpc-app) example.
32+
- **Stage VPC**: For non-production workloads. You can create this type of VPC using the [vpc-app](/modules/vpc-app)
33+
module, as shown in the [vpc-app](../vpc-app) example.
34+
- **Mgmt VPC**: Where operators run DevOps tooling and login. You can create this type of VPC using the
35+
[vpc-mgmt](/modules/vpc-mgmt) module, as shown in the templates in this example.
36+
37+
## Subnet Tiers
38+
39+
This VPC defines different "tiers" of private and public subnets that strictly control inbound and outbound access.
40+
See [vpc-app](/modules/vpc-app) and [vpc-network-acls](/examples/vpc-network-acls) for details.
41+
42+
## Known Errors
43+
44+
This terraform template may intermittently trigger certain non-critical errors caused by eventual consistency bugs in
45+
Terraform. These are usually harmless and all you need to do to get around them is to re-run `terraform apply`.

‎examples/vpc-mgmt/main.tf

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/examples/vpc-mgmt/main.tf>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎examples/vpc-mgmt/outputs.tf

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/examples/vpc-mgmt/outputs.tf>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎examples/vpc-mgmt/vars.tf

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-vpc>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-vpc/blob/master/examples/vpc-mgmt/vars.tf>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

0 commit comments

Comments
 (0)