docs: Update documentation to show reference usage

Author: bryantbiggs

README.md

@@ -4,12 +4,124 @@ Terraform module which creates AWS App Runner resources.
 
 ## Usage
 
-See [`examples`](https://github.com/clowdhaus/terraform-aws-app-runner/tree/main/examples) directory for working examples to reference:
+### AppRunner Common/Shared Configurations
 
 ```hcl
-module "app_runner" {
+module "app_runner_shared_configs" {
   source = "clowdhaus/app-runner/aws"
 
+  # Disable service resources
+  create_service = false
+
+  connections = {
+    # The AWS Connector for GitHub connects to your GitHub account is a one-time setup,
+    # You can reuse the connection for creating multiple App Runner services based on repositories in this account.
+    # After creation, you must complete the authentication handshake using the App Runner console.
+    github = {
+      provider_type = "GITHUB"
+    }
+  }
+
+  auto_scaling_configurations = {
+    mini = {
+      name            = "mini"
+      max_concurrency = 20
+      max_size        = 5
+      min_size        = 1
+
+      tags = {
+        Type = "Mini"
+      }
+    }
+
+    mega = {
+      name            = "mega"
+      max_concurrency = 200
+      max_size        = 25
+      min_size        = 5
+
+      tags = {
+        Type = "MEGA"
+      }
+    }
+  }
+
+  tags = {
+    Terraform   = "true"
+    Environment = "dev"
+  }
+}
+```
+
+### Code Based AppRunner Service
+
+```hcl
+module "app_runner_code_base" {
+  source = "clowdhaus/app-runner/aws"
+
+  service_name = "example-code-base"
+
+  # From shared configs created above
+  auto_scaling_configuration_arn = module.app_runner_shared_configs.auto_scaling_configurations["mini"].arn
+
+  source_configuration = {
+    authentication_configuration = {
+      # From shared configs created above
+      connection_arn = module.app_runner_shared_configs.connections["github"].arn
+    }
+    auto_deployments_enabled = false
+    code_repository = {
+      code_configuration = {
+        configuration_source = "REPOSITORY"
+      }
+      repository_url = "https://github.com/aws-containers/hello-app-runner"
+      source_code_version = {
+        type  = "BRANCH"
+        value = "main"
+      }
+    }
+  }
+
+  tags = {
+    Terraform   = "true"
+    Environment = "dev"
+  }
+}
+```
+
+### Image Based AppRunner Service
+
+```hcl
+module "app_runner_image_base" {
+  source = "clowdhaus/app-runner/aws"
+
+  service_name = "example-image-base"
+
+  # From shared configs
+  auto_scaling_configuration_arn = module.app_runner_shared_configs.auto_scaling_configurations["mega"].arn
+
+  source_configuration = {
+    auto_deployments_enabled = false
+    image_repository = {
+      image_configuration = {
+        port = 8000
+      }
+      image_identifier      = "public.ecr.aws/aws-containers/hello-app-runner:latest"
+      image_repository_type = "ECR_PUBLIC"
+    }
+  }
+
+  create_vpc_connector          = true
+  vpc_connector_subnets         = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]
+  vpc_connector_security_groups = ["sg-12345678"]
+  network_configuration = {
+    egress_configuration = {
+      egress_type = "VPC"
+    }
+  }
+
+  enable_observability_configuration = true
+
   tags = {
     Terraform   = "true"
     Environment = "dev"
@@ -29,13 +141,13 @@ Examples codified under the [`examples`](https://github.com/clowdhaus/terraform-
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.22 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.22 |
 
 ## Modules
 
@@ -56,7 +168,7 @@ No modules.
 | [aws_iam_role.instance](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
 | [aws_iam_role_policy_attachment.access](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
 | [aws_iam_role_policy_attachment.access_additional](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
-| [aws_iam_role_policy_attachment.instance](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
+| [aws_iam_role_policy_attachment.instance_additional](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
 | [aws_iam_role_policy_attachment.instance_xray](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
 | [aws_iam_policy_document.access](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
 | [aws_iam_policy_document.access_assume_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |

examples/complete/README.md

@@ -2,18 +2,30 @@
 
 Configuration in this directory creates:
 
-- <XXX>
+- AppRunner shared configurations for:
+  - GitHub connection
+  - Autoscaling configuration for a "min" and "max" examples
+- A code based AppRunner service
+  - Utilizes "min" autoscaling configuration created in shared configs
+- An image based AppRunner service
+  - Utilizes "mega" autoscaling configuration created in shared configs
+  - Creates a VPC connector to the associated VPC private subnets
 
 ## Usage
 
 To run this example you need to execute:
 
+1. Fork [this repository](https://github.com/aws-containers/hello-app-runner) to the account/organization associated with the GitHub connection that will be created
+
+2.
 ```bash
 $ terraform init
 $ terraform plan
-$ terraform apply
+$ terraform apply -var="repository_url=<URL_TO_FORKED_REPOSITORY>"
 ```
 
+3. Once you have entered `yes` at the prompt, you will need to navigate to the AppRunner console -> GitHub connections -> Complete the handshake for the connection created by this example.
+
 Note that this example may create resources which will incur monetary charges on your AWS bill. Run `terraform destroy` when you no longer need these resources.
 
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
@@ -22,11 +34,13 @@ Note that this example may create resources which will incur monetary charges on
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.22 |
 
 ## Providers
 
-No providers.
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.22 |
 
 ## Modules
 
@@ -41,11 +55,15 @@ No providers.
 
 ## Resources
 
-No resources.
+| Name | Type |
+|------|------|
+| [aws_availability_zones.available](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/availability_zones) | data source |
 
 ## Inputs
 
-No inputs.
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_repository_url"></a> [repository\_url](#input\_repository\_url) | Location of the repository that contains the source code. Repository must be located in same scope as the GitHub connection (user's profile or organization) | `string` | `"https://github.com/aws-containers/hello-app-runner"` | no |
 
 ## Outputs
 

examples/complete/main.tf

@@ -76,7 +76,7 @@ module "app_runner_code_base" {
       code_configuration = {
         configuration_source = "REPOSITORY"
       }
-      repository_url = "https://github.com/clowdhaus/hello-app-runner"
+      repository_url = var.repository_url
       source_code_version = {
         type  = "BRANCH"
         value = "main"
@@ -108,9 +108,10 @@ module "app_runner_image_base" {
   }
 
   # # Requires manual intervention to validate records
+  # # https://github.com/hashicorp/terraform-provider-aws/issues/23460
   # create_custom_domain_association = true
-  # hosted_zone_id                   = "Z067530812I2IA0AIKZEV"
-  # domain_name                      = "apprunner.sharedservices.clowd.haus"
+  # hosted_zone_id                   = "<TODO>"
+  # domain_name                      = "<TODO>"
   # enable_www_subdomain             = true
 
   create_vpc_connector          = true
@@ -137,16 +138,23 @@ module "app_runner_disabled" {
 # Supporting Resources
 ################################################################################
 
+data "aws_availability_zones" "available" {}
+
+locals {
+  vpc_cidr = "10.0.0.0/16"
+  azs      = slice(data.aws_availability_zones.available.names, 0, 3)
+}
+
 module "vpc" {
   source  = "terraform-aws-modules/vpc/aws"
   version = "~> 3.0"
 
   name = local.name
-  cidr = "10.99.0.0/18"
+  cidr = local.vpc_cidr
 
-  azs             = ["${local.region}a", "${local.region}b", "${local.region}c"]
-  public_subnets  = ["10.99.0.0/24", "10.99.1.0/24", "10.99.2.0/24"]
-  private_subnets = ["10.99.3.0/24", "10.99.4.0/24", "10.99.5.0/24"]
+  azs             = local.azs
+  private_subnets = [for k, v in local.azs : cidrsubnet(local.vpc_cidr, 4, k)]
+  public_subnets  = [for k, v in local.azs : cidrsubnet(local.vpc_cidr, 8, k + 48)]
 
   enable_nat_gateway      = false
   single_nat_gateway      = true

examples/complete/variables.tf

@@ -0,0 +1,5 @@
+variable "repository_url" {
+  description = "Location of the repository that contains the source code. Repository must be located in same scope as the GitHub connection (user's profile or organization)"
+  type        = string
+  default     = "https://github.com/aws-containers/hello-app-runner" # clone to your account associated with the GitHub connection
+}

examples/complete/versions.tf

@@ -4,7 +4,7 @@ terraform {
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = ">= 4.0"
+      version = ">= 4.22"
     }
   }
 }

main.tf

@@ -4,8 +4,12 @@ data "aws_partition" "current" {}
 # Service
 ################################################################################
 
+locals {
+  create_service = var.create && var.create_service
+}
+
 resource "aws_apprunner_service" "this" {
-  count = var.create && var.create_service ? 1 : 0
+  count = local.create_service ? 1 : 0
 
   auto_scaling_configuration_arn = var.auto_scaling_configuration_arn
 
@@ -35,7 +39,7 @@ resource "aws_apprunner_service" "this" {
 
     content {
       cpu               = try(instance_configuration.value.cpu, null)
-      instance_role_arn = var.create_instance_iam_role ? aws_iam_role.instance[0].arn : try(instance_configuration.value.instance_role_arn, null)
+      instance_role_arn = var.create_instance_iam_role ? aws_iam_role.instance[0].arn : lookup(instance_configuration.value, "instance_role_arn", null)
       memory            = try(instance_configuration.value.memory, null)
     }
   }
@@ -149,9 +153,8 @@ resource "aws_apprunner_service" "this" {
 ################################################################################
 
 locals {
-  create_access_iam_role = var.create && var.create_service && var.create_access_iam_role
-
-  access_iam_role_name = try(coalesce(var.access_iam_role_name, "${var.service_name}-access"), "")
+  create_access_iam_role = local.create_service && var.create_access_iam_role
+  access_iam_role_name   = try(coalesce(var.access_iam_role_name, "${var.service_name}-access"), "")
 }
 
 data "aws_iam_policy_document" "access_assume_role" {
@@ -244,9 +247,8 @@ resource "aws_iam_role_policy_attachment" "access_additional" {
 ################################################################################
 
 locals {
-  create_instance_iam_role = var.create && var.create_service && var.create_instance_iam_role
-
-  instance_iam_role_name = try(coalesce(var.instance_iam_role_name, "${var.service_name}-instance"), "")
+  create_instance_iam_role = local.create_service && var.create_instance_iam_role
+  instance_iam_role_name   = try(coalesce(var.instance_iam_role_name, "${var.service_name}-instance"), "")
 }
 
 data "aws_iam_policy_document" "instance_assume_role" {
@@ -285,7 +287,7 @@ resource "aws_iam_role_policy_attachment" "instance_xray" {
   role       = aws_iam_role.instance[0].name
 }
 
-resource "aws_iam_role_policy_attachment" "instance" {
+resource "aws_iam_role_policy_attachment" "instance_additional" {
   for_each = { for k, v in var.instance_iam_role_policies : k => v if local.create_instance_iam_role }
 
   policy_arn = each.value
@@ -297,7 +299,7 @@ resource "aws_iam_role_policy_attachment" "instance" {
 ################################################################################
 
 locals {
-  create_custom_domain_association = var.create && var.create_service && var.create_custom_domain_association
+  create_custom_domain_association = local.create_service && var.create_custom_domain_association
 }
 
 resource "aws_apprunner_custom_domain_association" "this" {
@@ -309,6 +311,7 @@ resource "aws_apprunner_custom_domain_association" "this" {
 }
 
 # # Requires manual intervention to validate records
+# # https://github.com/hashicorp/terraform-provider-aws/issues/23460
 # resource "aws_route53_record" "validation" {
 #   count = length(aws_apprunner_custom_domain_association.this[0].certificate_validation_records)
 
@@ -367,9 +370,8 @@ resource "aws_apprunner_custom_domain_association" "this" {
 ################################################################################
 
 locals {
-  create_vpc_connector = var.create && var.create_service && var.create_vpc_connector
-
-  vpc_connector_name = try(coalesce(var.vpc_connector_name, var.service_name), "")
+  create_vpc_connector = local.create_service && var.create_vpc_connector
+  vpc_connector_name   = try(coalesce(var.vpc_connector_name, var.service_name), "")
 }
 
 resource "aws_apprunner_vpc_connector" "this" {
@@ -415,7 +417,7 @@ resource "aws_apprunner_auto_scaling_configuration_version" "this" {
 ################################################################################
 
 locals {
-  enable_observability_configuration = var.create && var.create_service && var.enable_observability_configuration
+  enable_observability_configuration = local.create_service && var.enable_observability_configuration
 }
 
 resource "aws_apprunner_observability_configuration" "this" {

versions.tf

@@ -4,7 +4,7 @@ terraform {
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = ">= 4.0"
+      version = ">= 4.22"
     }
   }
 }