Add example usage (#4)

README.md

@@ -8,7 +8,7 @@
  [![Build Status](https://travis-ci.org/cloudposse/terraform-aws-vpc-peering-multi-account.svg?branch=master)](https://travis-ci.org/cloudposse/terraform-aws-vpc-peering-multi-account) [![Latest Release](https://img.shields.io/github/release/cloudposse/terraform-aws-vpc-peering-multi-account.svg)](https://github.com/cloudposse/terraform-aws-vpc-peering-multi-account/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)
 
 
-Terraform module to create a peering connection between any two VPCs existing in different AWS accounts. 
+Terraform module to create a peering connection between any two VPCs existing in different AWS accounts.
 
 This module supports performing this action from a 3rd account (e.g. a "root" account) by specifying the roles to assume for each member account.
 
@@ -54,14 +54,27 @@ We literally have [*hundreds of terraform modules*][terraform_modules] that are
 
 ## Usage
 
+
+**IMPORTANT:** Do not pin to `master` because there may be breaking changes between releases. Instead pin to the release tag (e.g. `?ref=tags/x.y.z`) of one of our [latest releases](https://github.com/cloudposse/terraform-aws-vpc-peering-multi-account/releases).
+
+For a complete example, see [examples/complete](examples/complete)
+
 ```hcl
-module "vpc_peering" {
+module "vpc_peering_cross_account" {
  source = "git::https://github.com/cloudposse/terraform-aws-vpc-peering-multi-account.git?ref=master"
  namespace = "eg"
  stage = "dev"
  name = "cluster"
- requester_vpc_id = "vpc-XXXXXXXX"
- accepter_vpc_id = "vpc-YYYYYYYY"
+
+ requester_aws_assume_role_arn = "arn:aws:iam::XXXXXXXX:role/cross-account-vpc-peering-test"
+ requester_region = "us-west-2"
+ requester_vpc_id = "vpc-XXXXXXXX"
+ requester_allow_remote_vpc_dns_resolution = "true"
+
+ accepter_aws_assume_role_arn = "arn:aws:iam::YYYYYYYY:role/cross-account-vpc-peering-test"
+ accepter_region = "us-east-1"
+ accepter_vpc_id = "vpc-YYYYYYYY"
+ accepter_allow_remote_vpc_dns_resolution = "true"
 }
 ```
 

README.yaml

@@ -59,22 +59,35 @@ related:
 
 # Short description of this project
 description: |-
- Terraform module to create a peering connection between any two VPCs existing in different AWS accounts. 
+ Terraform module to create a peering connection between any two VPCs existing in different AWS accounts.
 
  This module supports performing this action from a 3rd account (e.g. a "root" account) by specifying the roles to assume for each member account.
- 
+
  **IMPORTANT:** AWS allows a multi-account VPC Peering Connection to be deleted from either the requester's or accepter's side. However, Terraform only allows the VPC Peering Connection to be deleted from the requester's side by removing the corresponding `aws_vpc_peering_connection` resource from your configuration. [Read more about this](https://www.terraform.io/docs/providers/aws/r/vpc_peering_accepter.html) on Terraform's documentation portal.
 
 # How to use this project
 usage: |-
+
+ **IMPORTANT:** Do not pin to `master` because there may be breaking changes between releases. Instead pin to the release tag (e.g. `?ref=tags/x.y.z`) of one of our [latest releases](https://github.com/cloudposse/terraform-aws-vpc-peering-multi-account/releases).
+
+ For a complete example, see [examples/complete](examples/complete)
+
  ```hcl
- module "vpc_peering" {
+ module "vpc_peering_cross_account" {
  source = "git::https://github.com/cloudposse/terraform-aws-vpc-peering-multi-account.git?ref=master"
  namespace = "eg"
  stage = "dev"
  name = "cluster"
- requester_vpc_id = "vpc-XXXXXXXX"
- accepter_vpc_id = "vpc-YYYYYYYY"
+
+ requester_aws_assume_role_arn = "arn:aws:iam::XXXXXXXX:role/cross-account-vpc-peering-test"
+ requester_region = "us-west-2"
+ requester_vpc_id = "vpc-XXXXXXXX"
+ requester_allow_remote_vpc_dns_resolution = "true"
+
+ accepter_aws_assume_role_arn = "arn:aws:iam::YYYYYYYY:role/cross-account-vpc-peering-test"
+ accepter_region = "us-east-1"
+ accepter_vpc_id = "vpc-YYYYYYYY"
+ accepter_allow_remote_vpc_dns_resolution = "true"
  }
  ```
 

examples/complete/main.tf

@@ -0,0 +1,20 @@
+provider "aws" {
+ region = "${var.region}"
+}
+
+module "vpc_peering_cross_account" {
+ source = "../../"
+ namespace = "${var.namespace}"
+ stage = "${var.stage}"
+ name = "${var.name}"
+
+ requester_aws_assume_role_arn = "${var.requester_aws_assume_role_arn}"
+ requester_region = "${var.requester_region}"
+ requester_vpc_id = "${var.requester_vpc_id}"
+ requester_allow_remote_vpc_dns_resolution = "${var.requester_allow_remote_vpc_dns_resolution}"
+
+ accepter_aws_assume_role_arn = "${var.accepter_aws_assume_role_arn}"
+ accepter_region = "${var.accepter_region}"
+ accepter_vpc_id = "${var.accepter_vpc_id}"
+ accepter_allow_remote_vpc_dns_resolution = "${var.accepter_allow_remote_vpc_dns_resolution}"
+}

examples/complete/outputs.tf

@@ -0,0 +1,19 @@
+output "requester_connection_id" {
+ value = "${module.vpc_peering_cross_account.requester_connection_id}"
+ description = "Requester VPC peering connection ID"
+}
+
+output "requester_accept_status" {
+ value = "${module.vpc_peering_cross_account.requester_accept_status}"
+ description = "Requester VPC peering connection request status"
+}
+
+output "accepter_connection_id" {
+ value = "${module.vpc_peering_cross_account.accepter_connection_id}"
+ description = "Accepter VPC peering connection ID"
+}
+
+output "accepter_accept_status" {
+ value = "${module.vpc_peering_cross_account.accepter_accept_status}"
+ description = "Accepter VPC peering connection request status"
+}

examples/complete/variables.tf

@@ -0,0 +1,67 @@
+variable "region" {
+ type = "string"
+ description = "AWS Region"
+ default = "us-east-1"
+}
+
+variable "namespace" {
+ type = "string"
+ description = "Namespace (e.g. `eg` or `cp`)"
+ default = "eg"
+}
+
+variable "stage" {
+ type = "string"
+ description = "Stage (e.g. `prod`, `dev`, `staging`)"
+ default = "testing"
+}
+
+variable "name" {
+ type = "string"
+ description = "Name of the application"
+ default = "vpc-peering"
+}
+
+variable "requester_aws_assume_role_arn" {
+ type = "string"
+ description = "Requester AWS Assume Role ARN"
+}
+
+variable "requester_region" {
+ type = "string"
+ description = "Requester AWS region"
+ default = "us-west-2"
+}
+
+variable "requester_vpc_id" {
+ type = "string"
+ description = "Requester VPC ID filter"
+}
+
+variable "requester_allow_remote_vpc_dns_resolution" {
+ type = "string"
+ description = "Allow requester VPC to resolve public DNS hostnames to private IP addresses when queried from instances in the accepter VPC"
+ default = "true"
+}
+
+variable "accepter_aws_assume_role_arn" {
+ type = "string"
+ description = "Accepter AWS Assume Role ARN"
+}
+
+variable "accepter_region" {
+ type = "string"
+ description = "Accepter AWS region"
+ default = "us-east-1"
+}
+
+variable "accepter_vpc_id" {
+ type = "string"
+ description = "Accepter VPC ID filter"
+}
+
+variable "accepter_allow_remote_vpc_dns_resolution" {
+ type = "string"
+ description = "Allow accepter VPC to resolve public DNS hostnames to private IP addresses when queried from instances in the requester VPC"
+ default = "true"
+}