diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d67a09a --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2022-present SPH Media + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 2854f8d..8c69880 100644 --- a/README.md +++ b/README.md @@ -1 +1,24 @@ -# Terraform Modules Template +# Observability Access Manager + +## Overview + +## What is OAM? + +**OAM is for centralized logging across accounts.** + +To set up OAM, we choose one or more AWS accounts as monitoring accounts and link them with multiple source accounts. A monitoring account is a central AWS account that can view and interact with observability data generated from source accounts. A source account is an individual AWS account that generates observability data for the resources that reside in it. Source accounts share their observability data with the monitoring account. + +The shared observability data can include metrics in Amazon CloudWatch, logs in Amazon CloudWatch Logs, and traces in AWS X-Ray. + +## OAM Components + +CloudWatch OAM consists of two major components which enable cross-account observability - + +### Sink + +A sink is a resource that represents an attachment point in a monitoring account. Source accounts can link to the sink to send observability data. After you create a sink, you must create a sink policy that allows source accounts to attach to it. + +### Link + +A link is a connection between a source account and a sink that you have created in a monitoring account. +Before you create a link, you must create a sink in the monitoring account and create a sink policy in that account. The sink policy must permit the source account to link to it. You can grant permission to source accounts by granting permission to an entire organization or to individual accounts. diff --git a/modules/.gitkeep b/modules/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/modules/link/README.md b/modules/link/README.md new file mode 100644 index 0000000..b28d699 --- /dev/null +++ b/modules/link/README.md @@ -0,0 +1,41 @@ + +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 1.5 | +| [aws](#requirement\_aws) | >= 5.15 | + +## Providers + +| Name | Version | +|------|---------| +| [aws](#provider\_aws) | >= 5.15 | + +## Modules + +No modules. + +## Resources + +| Name | Type | +|------|------| +| [aws_oam_link.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/oam_link) | resource | + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [account\_label](#input\_account\_label) | Specify a friendly human-readable name to use to identify this source account when you are viewing data from it in the monitoring account.
You can include the following variables in your template:
- `$AccountName` is the name of the account
- `$AccountEmail` is a globally-unique email address, which includes the email domain, such as mariagarcia@example.com
- `$AccountEmailNoDomain` is an email address without the domain name, such as mariagarcia | `string` | `"$AccountName"` | no | +| [resource\_types](#input\_resource\_types) | An array of strings that define which types of data that the source account shares with the monitoring account. | `list(string)` | 
[
  "AWS::CloudWatch::Metric",
  "AWS::Logs::LogGroup",
  "AWS::XRay::Trace"
]
| no | +| [sink\_identifier](#input\_sink\_identifier) | The ARN of the sink in the monitoring account that you want to link to. | `string` | n/a | yes | +| [tags](#input\_tags) | An array of key-value pairs to apply to the link. | `map(string)` | `{}` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| [arn](#output\_arn) | The ARN of the link. | +| [id](#output\_id) | The ID string that AWS generated as part of the link ARN. | +| [sink\_arn](#output\_sink\_arn) | ARN of the sink that is used for this link. | + diff --git a/modules/link/main.tf b/modules/link/main.tf new file mode 100644 index 0000000..efd6ea0 --- /dev/null +++ b/modules/link/main.tf @@ -0,0 +1,6 @@ +resource "aws_oam_link" "this" { + label_template = var.account_label + resource_types = var.resource_types + sink_identifier = var.sink_identifier + tags = var.tags +} diff --git a/modules/link/outputs.tf b/modules/link/outputs.tf new file mode 100644 index 0000000..3d390c0 --- /dev/null +++ b/modules/link/outputs.tf @@ -0,0 +1,14 @@ +output "arn" { + description = "The ARN of the link." + value = aws_oam_link.this.arn +} + +output "id" { + description = "The ID string that AWS generated as part of the link ARN." + value = aws_oam_link.this.link_id +} + +output "sink_arn" { + description = "ARN of the sink that is used for this link." + value = aws_oam_link.this.sink_arn +} diff --git a/modules/link/variables.tf b/modules/link/variables.tf new file mode 100644 index 0000000..5c42fec --- /dev/null +++ b/modules/link/variables.tf @@ -0,0 +1,46 @@ +variable "account_label" { + description = < +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 1.5 | +| [aws](#requirement\_aws) | >= 5.15 | + +## Providers + +| Name | Version | +|------|---------| +| [aws](#provider\_aws) | >= 5.15 | + +## Modules + +No modules. + +## Resources + +| Name | Type | +|------|------| +| [aws_oam_sink.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/oam_sink) | resource | +| [aws_oam_sink_policy.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/oam_sink_policy) | resource | + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [name](#input\_name) | Name of the OAM sink | `string` | `null` | no | +| [resource\_types](#input\_resource\_types) | Resource types to retrieve with OAM | `list(string)` | 
[
  "AWS::CloudWatch::Metric",
  "AWS::Logs::LogGroup",
  "AWS::XRay::Trace"
]
| no | +| [source\_account\_ids](#input\_source\_account\_ids) | List of source AWS account IDs for OAM | `list(string)` | `[]` | no | +| [source\_org\_ids](#input\_source\_org\_ids) | List of source Organisation ID's for OAM | `list(string)` | `[]` | no | +| [source\_org\_paths](#input\_source\_org\_paths) | List of source Organisation unit paths for OAM | `list(string)` | `[]` | no | +| [tags](#input\_tags) | An array of key-value pairs to apply to the sink. | `map(string)` | `{}` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| [arn](#output\_arn) | ARN of OAM sink | +| [id](#output\_id) | ID of OAM sink | + diff --git a/modules/sink/locals.tf b/modules/sink/locals.tf new file mode 100644 index 0000000..af954cb --- /dev/null +++ b/modules/sink/locals.tf @@ -0,0 +1,49 @@ +locals { + source_accounts_statement = { + Effect = "Allow" + Principal = { + "AWS" = var.source_account_ids + } + Action = ["oam:CreateLink", "oam:UpdateLink"] + Resource = "*" + Condition = { + "ForAllValues:StringEquals" = { + "oam:ResourceTypes" = var.resource_types + } + } + } + source_organizations_statement = { + Effect = "Allow" + Principal = "*" + Action = ["oam:CreateLink", "oam:UpdateLink"] + Resource = "*" + Condition = { + "ForAllValues:StringEquals" = { + "oam:ResourceTypes" = var.resource_types + } + "ForAnyValue:StringEquals" = { + "aws:PrincipalOrgID" = var.source_org_ids + } + } + } + source_organization_paths_statement = { + Effect = "Allow" + Principal = "*" + Action = ["oam:CreateLink", "oam:UpdateLink"] + Resource = "*" + Condition = { + "ForAllValues:StringEquals" = { + "oam:ResourceTypes" = var.resource_types + } + "ForAnyValue:StringLike" : { + "aws:PrincipalOrgPaths" : var.source_org_paths + } + } + } + + policy_required = length(concat( + var.source_account_ids, + var.source_org_ids, + var.source_org_paths, + )) > 0 +} diff --git a/modules/sink/main.tf b/modules/sink/main.tf new file mode 100644 index 0000000..59ac8e2 --- /dev/null +++ b/modules/sink/main.tf @@ -0,0 +1,19 @@ +resource "aws_oam_sink" "this" { + name = var.name + tags = var.tags +} + +resource "aws_oam_sink_policy" "this" { + count = local.policy_required ? 1 : 0 + + sink_identifier = aws_oam_sink.this.arn + + policy = jsonencode({ + Version = "2012-10-17" + Statement = concat( + length(var.source_account_ids) > 0 ? [local.source_accounts_statement] : [], + length(var.source_org_ids) > 0 ? [local.source_organizations_statement] : [], + length(var.source_org_paths) > 0 ? [local.source_organization_paths_statement] : [], + ) + }) +} diff --git a/modules/sink/outputs.tf b/modules/sink/outputs.tf new file mode 100644 index 0000000..d3dc0e3 --- /dev/null +++ b/modules/sink/outputs.tf @@ -0,0 +1,9 @@ +output "id" { + description = "ID of OAM sink" + value = aws_oam_sink.this.id +} + +output "arn" { + description = "ARN of OAM sink" + value = aws_oam_sink.this.arn +} diff --git a/modules/sink/variables.tf b/modules/sink/variables.tf new file mode 100644 index 0000000..1481d68 --- /dev/null +++ b/modules/sink/variables.tf @@ -0,0 +1,53 @@ +variable "name" { + description = "Name of the OAM sink" + type = string + default = null +} + +variable "source_account_ids" { + description = "List of source AWS account IDs for OAM" + type = list(string) + default = [] +} + +variable "source_org_ids" { + description = "List of source Organisation ID's for OAM" + type = list(string) + default = [] +} + +variable "source_org_paths" { + description = "List of source Organisation unit paths for OAM" + type = list(string) + default = [] +} + +variable "resource_types" { + description = "Resource types to retrieve with OAM" + type = list(string) + + validation { + condition = alltrue([ + for resource_type in var.resource_types : + contains([ + "AWS::CloudWatch::Metric", + "AWS::Logs::LogGroup", + "AWS::XRay::Trace", + "AWS::ApplicationInsights::Application", + ], resource_type) + ]) + error_message = "Invalid values for `oam_resource_types`." + } + + default = [ + "AWS::CloudWatch::Metric", + "AWS::Logs::LogGroup", + "AWS::XRay::Trace", + ] +} + +variable "tags" { + description = "An array of key-value pairs to apply to the sink." + type = map(string) + default = {} +} diff --git a/modules/sink/versions.tf b/modules/sink/versions.tf new file mode 100644 index 0000000..2885716 --- /dev/null +++ b/modules/sink/versions.tf @@ -0,0 +1,10 @@ +terraform { + required_version = ">= 1.5" + + required_providers { + aws = { + source = "hashicorp/aws" + version = ">= 5.15" + } + } +}