README.yaml

#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-aws-vpc-peering-multi-account

# Tags of this project
tags:
  - aws
  - terraform
  - terraform-modules
  - platform
  - vpc
  - peering
  - vpc-peering
  - vpn
  - multi-account
  - multi-provider

# Categories of this project
categories:
  - terraform-modules/networking
# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-vpc-peering-multi-account

# Badges to display
badges:
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-vpc-peering-multi-account.svg"
    url: "https://github.com/cloudposse/terraform-aws-vpc-peering-multi-account/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

related:
  - name: "terraform-aws-vpc"
    description: "Terraform Module that defines a VPC with public/private subnets across multiple AZs with Internet Gateways"
    url: "https://github.com/cloudposse/terraform-aws-vpc"
  - name: "terraform-aws-vpc-peering"
    description: "Terraform module to create a peering connection between two VPCs in the same AWS account"
    url: "https://github.com/cloudposse/terraform-aws-vpc-peering"
  - name: "terraform-aws-kops-vpc-peering"
    description: "Terraform module to create a peering connection between a backing services VPC and a VPC created by Kops"
    url: "https://github.com/cloudposse/terraform-aws-kops-vpc-peering"

# Short description of this project
description: |-
  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: |2-

  **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_cross_account" {
    source = "cloudposse/vpc-peering-multi-account/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"
    namespace        = "eg"
    stage            = "dev"
    name             = "cluster"

    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
  }
  ```

  The `arn:aws:iam::XXXXXXXX:role/cross-account-vpc-peering-test` requester IAM Role should have the following Trust Policy:

  <details><summary>Show Trust Policy</summary>

  ```js
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::XXXXXXXX:root"
        },
        "Action": "sts:AssumeRole",
        "Condition": {}
      }
    ]
  }
  ```

  </details>
  <br/>

  and the following IAM Policy attached to it:

  __NOTE:__ the policy specifies the permissions to create (with `terraform plan/apply`) and delete (with `terraform destroy`) all the required resources in the requester AWS account

  <details><summary>Show IAM Policy</summary>

  ```js
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "ec2:CreateRoute",
          "ec2:DeleteRoute"
        ],
        "Resource": "arn:aws:ec2:*:XXXXXXXX:route-table/*"
      },
      {
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeVpcPeeringConnections",
          "ec2:DescribeVpcs",
          "ec2:ModifyVpcPeeringConnectionOptions",
          "ec2:DescribeSubnets",
          "ec2:DescribeVpcAttribute",
          "ec2:DescribeRouteTables"
        ],
        "Resource": "*"
      },
      {
        "Effect": "Allow",
        "Action": [
          "ec2:AcceptVpcPeeringConnection",
          "ec2:DeleteVpcPeeringConnection",
          "ec2:CreateVpcPeeringConnection",
          "ec2:RejectVpcPeeringConnection"
        ],
        "Resource": [
          "arn:aws:ec2:*:XXXXXXXX:vpc-peering-connection/*",
          "arn:aws:ec2:*:XXXXXXXX:vpc/*"
        ]
      },
      {
        "Effect": "Allow",
        "Action": [
          "ec2:DeleteTags",
          "ec2:CreateTags"
        ],
        "Resource": "arn:aws:ec2:*:XXXXXXXX:vpc-peering-connection/*"
      }
    ]
  }
  ```

  </details>

  where `XXXXXXXX` is the requester AWS account ID.

  <br/>

  The `arn:aws:iam::YYYYYYYY:role/cross-account-vpc-peering-test` accepter IAM Role should have the following Trust Policy:

  <details><summary>Show Trust Policy</summary>

  ```js
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::XXXXXXXX:root"
        },
        "Action": "sts:AssumeRole",
        "Condition": {}
      }
    ]
  }
  ```

  </details>

  __NOTE__: The accepter Trust Policy is the same as the requester Trust Policy since it defines who can assume the IAM Role.
  In the requester case, the requester account ID itself is the trusted entity.
  For the accepter, the Trust Policy specifies that the requester account ID `XXXXXXXX` can assume the role in the accepter AWS account `YYYYYYYY`.

  and the following IAM Policy attached to it:

  __NOTE:__ the policy specifies the permissions to create (with `terraform plan/apply`) and delete (with `terraform destroy`) all the required resources in the accepter AWS account

  <details><summary>Show IAM Policy</summary>

  ```js
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "ec2:CreateRoute",
          "ec2:DeleteRoute"
        ],
        "Resource": "arn:aws:ec2:*:YYYYYYYY:route-table/*"
      },
      {
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeVpcPeeringConnections",
          "ec2:DescribeVpcs",
          "ec2:ModifyVpcPeeringConnectionOptions",
          "ec2:DescribeSubnets",
          "ec2:DescribeVpcAttribute",
          "ec2:DescribeRouteTables"
        ],
        "Resource": "*"
      },
      {
        "Effect": "Allow",
        "Action": [
          "ec2:AcceptVpcPeeringConnection",
          "ec2:DeleteVpcPeeringConnection",
          "ec2:CreateVpcPeeringConnection",
          "ec2:RejectVpcPeeringConnection"
        ],
        "Resource": [
          "arn:aws:ec2:*:YYYYYYYY:vpc-peering-connection/*",
          "arn:aws:ec2:*:YYYYYYYY:vpc/*"
        ]
      },
      {
        "Effect": "Allow",
        "Action": [
          "ec2:DeleteTags",
          "ec2:CreateTags"
        ],
        "Resource": "arn:aws:ec2:*:YYYYYYYY:vpc-peering-connection/*"
      }
    ]
  }
  ```

  </details>

  where `YYYYYYYY` is the accepter AWS account ID.

  For more information on IAM policies and permissions for VPC peering, see [Creating and managing VPC peering connections](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_IAM.html#vpcpeeringiam).
references:
  - name: "What is VPC Peering?"
    description: "VPC peering connection is a networking connection between two VPCs that enables you to route traffic between them using private IPv4 addresses or IPv6 addresses."
    url: "https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html"

screenshots:
  - name: "vpc-peering"
    description: "VPC Peering Connection in the AWS Web Console"
    url: "images/vpc-peering.png"

include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors:
  - name: "Andriy Knysh"
    github: "aknysh"
  - name: "Erik Osterman"
    github: "osterman"