diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d1cc71c88..8189a755f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,9 +1,10 @@ repos: - repo: git://github.com/antonbabenko/pre-commit-terraform - sha: v1.4.0 + rev: v1.7.0 hooks: - id: terraform_fmt + - id: terraform_docs - repo: git://github.com/pre-commit/pre-commit-hooks - sha: v1.2.0 + rev: v1.2.3 hooks: - id: check-merge-conflict diff --git a/README.md b/README.md index 61610c6d0..2bfe36bb1 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -AWS VPC Terraform module -======================== +# AWS VPC Terraform module [![Help Contribute to Open Source](https://www.codetriage.com/terraform-aws-modules/terraform-aws-vpc/badges/users.svg)](https://www.codetriage.com/terraform-aws-modules/terraform-aws-vpc) @@ -21,8 +20,7 @@ These types of resources are supported: * [DHCP Options Set](https://www.terraform.io/docs/providers/aws/r/vpc_dhcp_options.html) * [Default VPC](https://www.terraform.io/docs/providers/aws/r/default_vpc.html) -Usage ------ +## Usage ```hcl module "vpc" { @@ -45,8 +43,7 @@ module "vpc" { } ``` -External NAT Gateway IPs ------------------------- +## External NAT Gateway IPs By default this module will provision new Elastic IPs for the VPC's NAT Gateways. This means that when creating a new VPC, new IPs are allocated, and when that VPC is destroyed those IPs are released. @@ -81,8 +78,7 @@ Note that in the example we allocate 3 IPs because we will be provisioning 3 NAT If, on the other hand, `single_nat_gateway = true`, then `aws_eip.nat` would only need to allocate 1 IP. Passing the IPs into the module is done by setting two variables `reuse_nat_ips = true` and `external_nat_ip_ids = ["${aws_eip.nat.*.id}"]`. -Conditional creation --------------------- +## Conditional creation Sometimes you need to have a way to create VPC resources conditionally but Terraform does not allow to use `count` inside `module` block, so the solution is to specify argument `create_vpc`. @@ -96,22 +92,122 @@ module "vpc" { } ``` -Terraform version ------------------ +## Terraform version Terraform version 0.10.3 or newer is required for this module to work. -Examples --------- +## Examples * [Simple VPC](https://github.com/terraform-aws-modules/terraform-aws-vpc/tree/master/examples/simple-vpc) * [Complete VPC](https://github.com/terraform-aws-modules/terraform-aws-vpc/tree/master/examples/complete-vpc) * [Manage Default VPC](https://github.com/terraform-aws-modules/terraform-aws-vpc/tree/master/examples/manage-default-vpc) * Few tests and edge cases examples: [#46](https://github.com/terraform-aws-modules/terraform-aws-vpc/tree/master/examples/issue-46-no-private-subnets), [#44](https://github.com/terraform-aws-modules/terraform-aws-vpc/tree/master/examples/issue-44-asymmetric-private-subnets), [#108](https://github.com/terraform-aws-modules/terraform-aws-vpc/tree/master/examples/issue-108-route-already-exists) - -Tests -------- + + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|:----:|:-----:|:-----:| +| azs | A list of availability zones in the region | string | `` | no | +| cidr | The CIDR block for the VPC. Default value is a valid CIDR, but not acceptable by AWS and should be overriden | string | `0.0.0.0/0` | no | +| create_database_subnet_group | Controls if database subnet group should be created | string | `true` | no | +| create_vpc | Controls if VPC should be created (it affects almost all resources) | string | `true` | no | +| database_subnet_tags | Additional tags for the database subnets | string | `` | no | +| database_subnets | A list of database subnets | list | `` | no | +| default_route_table_tags | Additional tags for the default route table | string | `` | no | +| default_vpc_enable_classiclink | Should be true to enable ClassicLink in the Default VPC | string | `false` | no | +| default_vpc_enable_dns_hostnames | Should be true to enable DNS hostnames in the Default VPC | string | `false` | no | +| default_vpc_enable_dns_support | Should be true to enable DNS support in the Default VPC | string | `true` | no | +| default_vpc_name | Name to be used on the Default VPC | string | `` | no | +| default_vpc_tags | Additional tags for the Default VPC | string | `` | no | +| dhcp_options_domain_name | Specifies DNS name for DHCP options set | string | `` | no | +| dhcp_options_domain_name_servers | Specify a list of DNS server addresses for DHCP options set, default to AWS provided | list | `` | no | +| dhcp_options_netbios_name_servers | Specify a list of netbios servers for DHCP options set | list | `` | no | +| dhcp_options_netbios_node_type | Specify netbios node_type for DHCP options set | string | `` | no | +| dhcp_options_ntp_servers | Specify a list of NTP servers for DHCP options set | list | `` | no | +| dhcp_options_tags | Additional tags for the DHCP option set | string | `` | no | +| elasticache_subnet_tags | Additional tags for the elasticache subnets | string | `` | no | +| elasticache_subnets | A list of elasticache subnets | list | `` | no | +| enable_dhcp_options | Should be true if you want to specify a DHCP options set with a custom domain name, DNS servers, NTP servers, netbios servers, and/or netbios server type | string | `false` | no | +| enable_dns_hostnames | Should be true to enable DNS hostnames in the VPC | string | `false` | no | +| enable_dns_support | Should be true to enable DNS support in the VPC | string | `true` | no | +| enable_dynamodb_endpoint | Should be true if you want to provision a DynamoDB endpoint to the VPC | string | `false` | no | +| enable_nat_gateway | Should be true if you want to provision NAT Gateways for each of your private networks | string | `false` | no | +| enable_s3_endpoint | Should be true if you want to provision an S3 endpoint to the VPC | string | `false` | no | +| enable_vpn_gateway | Should be true if you want to create a new VPN Gateway resource and attach it to the VPC | string | `false` | no | +| external_nat_ip_ids | List of EIP IDs to be assigned to the NAT Gateways (used in combination with reuse_nat_ips) | list | `` | no | +| instance_tenancy | A tenancy option for instances launched into the VPC | string | `default` | no | +| manage_default_vpc | Should be true to adopt and manage Default VPC | string | `false` | no | +| map_public_ip_on_launch | Should be false if you do not want to auto-assign public IP on launch | string | `true` | no | +| name | Name to be used on all the resources as identifier | string | `` | no | +| private_route_table_tags | Additional tags for the private route tables | string | `` | no | +| private_subnet_tags | Additional tags for the private subnets | string | `` | no | +| private_subnets | A list of private subnets inside the VPC | string | `` | no | +| propagate_private_route_tables_vgw | Should be true if you want route table propagation | string | `false` | no | +| propagate_public_route_tables_vgw | Should be true if you want route table propagation | string | `false` | no | +| public_route_table_tags | Additional tags for the public route tables | string | `` | no | +| public_subnet_tags | Additional tags for the public subnets | string | `` | no | +| public_subnets | A list of public subnets inside the VPC | string | `` | no | +| redshift_subnet_tags | Additional tags for the redshift subnets | string | `` | no | +| redshift_subnets | A list of redshift subnets | list | `` | no | +| reuse_nat_ips | Should be true if you don't want EIPs to be created for your NAT Gateways and will instead pass them in via the 'external_nat_ip_ids' variable | string | `false` | no | +| single_nat_gateway | Should be true if you want to provision a single shared NAT Gateway across all of your private networks | string | `false` | no | +| tags | A map of tags to add to all resources | string | `` | no | +| vpc_tags | Additional tags for the VPC | string | `` | no | +| vpn_gateway_id | ID of VPN Gateway to attach to the VPC | string | `` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| database_subnet_group | ID of database subnet group | +| database_subnets | List of IDs of database subnets | +| database_subnets_cidr_blocks | List of cidr_blocks of database subnets | +| default_network_acl_id | The ID of the default network ACL | +| default_route_table_id | The ID of the default route table | +| default_security_group_id | The ID of the security group created by default on VPC creation | +| default_vpc_cidr_block | The CIDR block of the VPC | +| default_vpc_default_network_acl_id | The ID of the default network ACL | +| default_vpc_default_route_table_id | The ID of the default route table | +| default_vpc_default_security_group_id | The ID of the security group created by default on VPC creation | +| default_vpc_enable_dns_hostnames | Whether or not the VPC has DNS hostname support | +| default_vpc_enable_dns_support | Whether or not the VPC has DNS support | +| default_vpc_id | Default VPC | +| default_vpc_instance_tenancy | Tenancy of instances spin up within VPC | +| default_vpc_main_route_table_id | The ID of the main route table associated with this VPC | +| elasticache_subnet_group | ID of elasticache subnet group | +| elasticache_subnet_group_name | Name of elasticache subnet group | +| elasticache_subnets | List of IDs of elasticache subnets | +| elasticache_subnets_cidr_blocks | List of cidr_blocks of elasticache subnets | +| igw_id | Internet Gateway | +| nat_ids | List of allocation ID of Elastic IPs created for AWS NAT Gateway | +| nat_public_ips | List of public Elastic IPs created for AWS NAT Gateway | +| natgw_ids | List of NAT Gateway IDs | +| private_route_table_ids | List of IDs of private route tables | +| private_subnets | Subnets | +| private_subnets_cidr_blocks | List of cidr_blocks of private subnets | +| public_route_table_ids | Route tables | +| public_subnets | List of IDs of public subnets | +| public_subnets_cidr_blocks | List of cidr_blocks of public subnets | +| redshift_subnet_group | ID of redshift subnet group | +| redshift_subnets | List of IDs of redshift subnets | +| redshift_subnets_cidr_blocks | List of cidr_blocks of redshift subnets | +| vgw_id | VPN Gateway | +| vpc_cidr_block | The CIDR block of the VPC | +| vpc_enable_dns_hostnames | Whether or not the VPC has DNS hostname support | +| vpc_enable_dns_support | Whether or not the VPC has DNS support | +| vpc_endpoint_dynamodb_id | The ID of VPC endpoint for DynamoDB | +| vpc_endpoint_dynamodb_pl_id | The prefix list for the DynamoDB VPC endpoint. | +| vpc_endpoint_s3_id | VPC Endpoints | +| vpc_endpoint_s3_pl_id | The prefix list for the S3 VPC endpoint. | +| vpc_id | VPC | +| vpc_instance_tenancy | Tenancy of instances spin up within VPC | +| vpc_main_route_table_id | The ID of the main route table associated with this VPC | + + + +## Tests This module has been packaged with [awspec](https://github.com/k1LoW/awspec) tests through test kitchen. To run them: @@ -123,13 +219,11 @@ gem install bundler; bundle install 3. Test using `bundle exec kitchen test` from the root of the repo. -Authors -------- +## Authors Migrated from `terraform-community-modules/tf_aws_vpc`, where it was maintained by [these awesome contributors](https://github.com/terraform-community-modules/tf_aws_vpc/graphs/contributors). Module managed by [Anton Babenko](https://github.com/antonbabenko). -License -------- +## License Apache 2 Licensed. See LICENSE for full details. diff --git a/examples/complete-vpc/README.md b/examples/complete-vpc/README.md index a8b98a37d..3a5397480 100644 --- a/examples/complete-vpc/README.md +++ b/examples/complete-vpc/README.md @@ -1,12 +1,10 @@ -Complete VPC -============ +# Complete VPC Configuration in this directory creates set of VPC resources which may be sufficient for staging or production environment (look into [simple-vpc](../simple-vpc) for more simplified setup). There are public, private, database, ElastiCache subnets, NAT Gateways created in each availability zone. -Usage -===== +## Usage To run this example you need to execute: @@ -17,3 +15,19 @@ $ terraform apply ``` Note that this example may create resources which can cost money (AWS Elastic IP, for example). Run `terraform destroy` when you don't need these resources. + + + +## Outputs + +| Name | Description | +|------|-------------| +| database_subnets | List of IDs of database subnets | +| elasticache_subnets | List of IDs of elasticache subnets | +| nat_public_ips | NAT gateways | +| private_subnets | Subnets | +| public_subnets | List of IDs of public subnets | +| redshift_subnets | List of IDs of redshift subnets | +| vpc_id | VPC | + + diff --git a/examples/issue-108-route-already-exists/README.md b/examples/issue-108-route-already-exists/README.md index cc5a0814c..bd2c57560 100644 --- a/examples/issue-108-route-already-exists/README.md +++ b/examples/issue-108-route-already-exists/README.md @@ -1,5 +1,4 @@ -Issue 108 - VPC -============== +# Issue 108 - VPC Configuration in this directory creates set of VPC resources to cover issues reported on GitHub: @@ -7,8 +6,7 @@ Configuration in this directory creates set of VPC resources to cover issues rep * https://github.com/terraform-aws-modules/terraform-aws-vpc/issues/102#issuecomment-374877706 * https://github.com/terraform-aws-modules/terraform-aws-vpc/issues/44#issuecomment-378679404 -Usage -===== +## Usage To run this example you need to execute: @@ -19,3 +17,18 @@ $ terraform apply ``` Note that this example may create resources which can cost money (AWS Elastic IP, for example). Run `terraform destroy` when you don't need these resources. + + + +## Outputs + +| Name | Description | +|------|-------------| +| database_subnets | List of IDs of database subnets | +| elasticache_subnets | List of IDs of elasticache subnets | +| nat_public_ips | NAT gateways | +| private_subnets | Subnets | +| public_subnets | List of IDs of public subnets | +| vpc_id | VPC | + + diff --git a/examples/issue-44-asymmetric-private-subnets/README.md b/examples/issue-44-asymmetric-private-subnets/README.md index 59f9ce78d..24c4db444 100644 --- a/examples/issue-44-asymmetric-private-subnets/README.md +++ b/examples/issue-44-asymmetric-private-subnets/README.md @@ -1,12 +1,10 @@ -Issue 44 - VPC -============== +# Issue 44 - VPC Configuration in this directory creates set of VPC resources to cover issues reported on GitHub: * https://github.com/terraform-aws-modules/terraform-aws-vpc/issues/44 -Usage -===== +## Usage To run this example you need to execute: @@ -17,3 +15,18 @@ $ terraform apply ``` Note that this example may create resources which can cost money (AWS Elastic IP, for example). Run `terraform destroy` when you don't need these resources. + + + +## Outputs + +| Name | Description | +|------|-------------| +| database_subnets | List of IDs of database subnets | +| elasticache_subnets | List of IDs of elasticache subnets | +| nat_public_ips | NAT gateways | +| private_subnets | Subnets | +| public_subnets | List of IDs of public subnets | +| vpc_id | VPC | + + diff --git a/examples/issue-46-no-private-subnets/README.md b/examples/issue-46-no-private-subnets/README.md index 08e8d8a33..958b13289 100644 --- a/examples/issue-46-no-private-subnets/README.md +++ b/examples/issue-46-no-private-subnets/README.md @@ -1,12 +1,10 @@ -Issue 46 - VPC -============== +# Issue 46 - VPC Configuration in this directory creates set of VPC resources to cover issues reported on GitHub: * https://github.com/terraform-aws-modules/terraform-aws-vpc/issues/46 -Usage -===== +## Usage To run this example you need to execute: @@ -17,3 +15,18 @@ $ terraform apply ``` Note that this example may create resources which can cost money (AWS Elastic IP, for example). Run `terraform destroy` when you don't need these resources. + + + +## Outputs + +| Name | Description | +|------|-------------| +| database_subnets | List of IDs of database subnets | +| elasticache_subnets | List of IDs of elasticache subnets | +| nat_public_ips | NAT gateways | +| private_subnets | Subnets | +| public_subnets | List of IDs of public subnets | +| vpc_id | VPC | + + diff --git a/examples/manage-default-vpc/README.md b/examples/manage-default-vpc/README.md index 4da44eb30..6c509e6ea 100644 --- a/examples/manage-default-vpc/README.md +++ b/examples/manage-default-vpc/README.md @@ -1,12 +1,10 @@ -Manage Default VPC -================== +# Manage Default VPC Configuration in this directory does not create new VPC resources, but it adopts [Default VPC](https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html) created by AWS to allow management of it using Terraform. This is not usual type of resource in Terraform, so use it carefully. More information is [here](https://www.terraform.io/docs/providers/aws/r/default_vpc.html). -Usage -===== +## Usage To run this example you need to execute: @@ -17,3 +15,14 @@ $ terraform apply ``` Run `terraform destroy` when you don't need these resources. + + + +## Outputs + +| Name | Description | +|------|-------------| +| default_vpc_cidr_block | The CIDR block of the VPC | +| default_vpc_id | Default VPC | + + diff --git a/examples/simple-vpc/README.md b/examples/simple-vpc/README.md index 2042d2810..891ae91b7 100644 --- a/examples/simple-vpc/README.md +++ b/examples/simple-vpc/README.md @@ -1,12 +1,10 @@ -Simple VPC -========== +# Simple VPC Configuration in this directory creates set of VPC resources which may be sufficient for development environment. There is a public and private subnet created per availability zone in addition to single NAT Gateway shared between all 3 availability zones. -Usage -===== +## Usage To run this example you need to execute: @@ -17,3 +15,16 @@ $ terraform apply ``` Note that this example may create resources which can cost money (AWS Elastic IP, for example). Run `terraform destroy` when you don't need these resources. + + + +## Outputs + +| Name | Description | +|------|-------------| +| nat_public_ips | NAT gateways | +| private_subnets | Subnets | +| public_subnets | List of IDs of public subnets | +| vpc_id | VPC | + + diff --git a/examples/test_fixture/README.md b/examples/test_fixture/README.md index b0b7231dd..fc2ab69bd 100644 --- a/examples/test_fixture/README.md +++ b/examples/test_fixture/README.md @@ -19,3 +19,19 @@ Finished in 4.25 seconds (files took 2.75 seconds to load) ``` This will destroy any existing test resources, create the resources afresh, run the tests, report back, and destroy the resources. + + + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|:----:|:-----:|:-----:| +| region | | string | `eu-west-1` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| region | Region we created the resources in. | + +