islamelkadi/terraform-aws-metadata
GitHub: islamelkadi/terraform-aws-metadata
一个为 AWS 基础设施提供标准化命名、安全控件和合规性标签的 Terraform 模块，帮助企业实现跨环境的一致性资源治理。
Stars: 0 | Forks: 0
# Terraform AWS Metadata 模块
一个 Terraform 模块，用于为 AWS 资源生成标准化的命名规范、安全控件和合规性标签。该模块是跨 AWS 基础设施实现一致资源管理的基础。
## 目录
- [前置条件](#prerequisites)
- [功能特性](#features)
- [安全性](#security)
- [安全控件](#security-controls)
- [安全控件覆盖模式](#security-control-override-pattern)
- [安全配置文件](#security-profiles)
- [安全标签](#security-tags)
- [快速入门](#quick-start)
- [支持的资源类型](#supported-resource-types)
- [优势](#benefits)
- [区域配置](#region-configuration)
- [MCP 服务器](#mcp-servers)
- [要求](#requirements)
## 前置条件
本模块专为 macOS 设计。您的机器上必须已安装以下软件：
- Python 3 和 pip
- [Kiro](https://kiro.dev) 和 Kiro CLI
- [Homebrew](https://brew.sh)
要安装其余开发工具，请运行：
```
make bootstrap
```
这将安装/升级：tfenv、Terraform（通过 tfenv）、tflint、terraform-docs、checkov 和 pre-commit。
## 功能特性
- **标准化命名**：以 `organization-project-environment-resourcetype` 格式生成一致的资源前缀
- **安全配置文件**：环境感知的安全控件（dev、staging、prod）
- **合规性支持**：内置支持 FCAC、PCI DSS、SOC2、HIPAA、ISO27001
- **区域缩写**：将 AWS 区域名称转换为短代码（例如，`us-east-1` → `use1`）
- **资源类型代码**：提供常见 AWS 资源类型的缩写代码
- **路径生成**：为 IAM 和其他资源创建层级路径
- **长度验证**：确保生成的名称不超过 AWS 命名限制（64 个字符）
- **组织上下文**：自动获取 AWS 账户 ID 和组织 ID
## 安全性
### 安全控件
`security_controls` 输出提供了一个全面的对象，其中安全设置按类别组织：
- **encryption**：KMS、静态/传输加密、密钥轮换
- **logging**：CloudWatch Logs、保留期、访问日志、流日志
- **network**：私有子网、VPC 终端节点、公有访问、IMDSv2
- **iam**：最小权限、通配符限制、MFA、服务角色
- **data_protection**：版本控制、MFA 删除、备份、公有访问、生命周期
- **monitoring**：X-Ray、增强监控、Performance Insights、CloudTrail
- **high_availability**：多可用区、跨区域备份
- **compliance**：PITR、预留并发、删除保护
**在模块中使用安全控件：**
```
# 在 module 中 (例如, terraform-aws-s3)
module "metadata" {
source = "github.com/islamelkadi/terraform-aws-metadata"
namespace = var.namespace
environment = var.environment
project_name = var.name
resource_type = "s3"
}
# 使用安全控制
locals {
versioning_required = module.metadata.security_controls.data_protection.require_versioning
kms_required = module.metadata.security_controls.encryption.require_kms_customer_managed
log_retention = module.metadata.security_controls.logging.min_log_retention_days
}
# 应用安全标签
resource "aws_s3_bucket" "this" {
bucket = module.metadata.resource_prefix
tags = merge(module.metadata.security_tags, var.tags)
}
```
### 安全控件覆盖模式
模块应允许在提供理由的情况下覆盖安全控件：
```
variable "security_control_overrides" {
description = "Override specific security controls with documented justification"
type = object({
disable_versioning_requirement = optional(bool, false)
disable_kms_requirement = optional(bool, false)
justification = optional(string, "")
})
default = {}
}
locals {
versioning_required = module.metadata.security_controls.data_protection.require_versioning &&
!var.security_control_overrides.disable_versioning_requirement
}
```
### 安全配置文件
该模块提供三种安全配置文件，可根据您的环境自动配置安全控件：
#### Dev 配置文件
**用途**：开发和测试环境
**特点**：
- 宽松的安全控件，便于更快迭代
- 较短的日志保留期（7 天）
- 可选加密，使用 AWS 托管密钥
- 允许单可用区部署
- 允许公有访问以进行测试
- 无删除保护（便于销毁）
**用例**：本地开发、功能分支、概念验证、成本优化
#### Staging 配置文件
**用途**：预生产测试和验证
**特点**：
- 类生产环境的安全控件
- 90 天日志保留期
- 需要客户托管的 KMS 密钥
- 数据库需多可用区
- 需要私有子网
- 启用完整监控
- 启用删除保护
**用例**：集成测试、性能测试、安全测试、UAT 环境
#### Prod 配置文件
**用途**：生产工作负载
**特点**：
- 最高级别的安全控件
- 365 天日志保留期（符合 PCI DSS 合规性）
- 需要客户托管的 KMS 密钥
- 所有关键资源需多可用区
- 启用跨区域备份
- S3 启用 MFA 删除
- Lambda 预留并发
- 完整监控和追踪
**用例**：生产应用程序、面向客户的服务、受监管的工作负载、关键任务系统
### 安全标签
`security_tags` 输出提供标准的安全和合规性标签：
- **Organization**：组织名称（SCREAMING_SNAKE_CASE）
- **Project**：项目名称（SCREAMING_SNAKE_CASE）
- **Environment**：环境（DEV、STAGING、PROD）
- **Region**：区域代码（USE1、EUW1 等）
- **ResourceType**：资源类型代码（SCREAMING_SNAKE_CASE）
- **ManagedBy**：TERRAFORM
- **Repository**：CORPORATE_ACTIONS_ORCHESTRATOR
- **SecurityProfile**：DEV、STAGING 或 PROD
- **DataClass**：CONFIDENTIAL、INTERNAL 或 PUBLIC
- **ComplianceFrameworks**：逗号分隔列表（FCAC、PCI_DSS 等）
- **ComplianceRequired**：TRUE（如果指定了框架）
- **AuditRequired**：TRUE（如果指定了框架）
## 快速入门
### 基本用法
```
module "metadata" {
source = "github.com/islamelkadi/terraform-aws-metadata?ref=v1.0.0"
namespace = "myorg"
project_name = "myapp"
environment = "prod"
region = "us-east-1"
resource_type = "lambda"
}
resource "aws_lambda_function" "example" {
function_name = "${module.metadata.resource_prefix}-handler"
# Results in: myorg-myapp-prod-lambda-handler
tags = module.metadata.security_tags
}
```
### 使用安全控件
```
module "metadata" {
source = "github.com/islamelkadi/terraform-aws-metadata?ref=v1.0.0"
namespace = "myorg"
project_name = "myapp"
environment = "prod"
region = "us-east-1"
resource_type = "s3"
security_profile = "prod"
compliance_frameworks = ["FCAC", "PCI_DSS"]
}
resource "aws_s3_bucket" "example" {
bucket = module.metadata.resource_prefix
tags = module.metadata.security_tags
}
resource "aws_s3_bucket_versioning" "example" {
count = module.metadata.security_controls.data_protection.require_versioning ? 1 : 0
bucket = aws_s3_bucket.example.id
versioning_configuration {
status = "Enabled"
}
}
```
## 支持的资源类型
该模块支持一套全面的 AWS 资源类型及其直观的缩写。您可以使用全名或常用别名。
### 计算服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `lambda` | `lambda` | AWS Lambda function |
| `lambda-layer` | `layer` | Lambda layer |
| `sfn`, `step-functions` | `sfn` | Step Functions state machine |
### 存储服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `s3`, `s3-bucket` | `s3` | S3 bucket |
### 数据库服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `dynamodb`, `dynamodb-table` | `ddb` | DynamoDB table |
| `rds`, `rds-cluster` | `rds` | RDS database instance/cluster |
| `rds-proxy` | `rdsprx` | RDS Proxy |
| `aurora` | `aurora` | Aurora cluster |
### 网络服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `vpc` | `vpc` | Virtual Private Cloud |
| `subnet` | `subnet` | VPC Subnet |
| `sg`, `security-group` | `sg` | Security Group |
| `nacl` | `nacl` | Network ACL |
| `nat`, `nat-gateway` | `nat` | NAT Gateway |
| `vpce`, `vpc-endpoint` | `vpce` | VPC Endpoint |
### 安全与身份服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `kms`, `kms-key` | `kms` | KMS key |
| `secret`, `secrets-manager` | `secret` | Secrets Manager secret |
| `iam-role` | `role` | IAM role |
| `iam-policy` | `policy` | IAM policy |
| `iam-user` | `user` | IAM user |
| `iam-group` | `group` | IAM group |
### 身份服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `cognito-user-pool` | `userpool` | Cognito User Pool |
| `cognito-user-pool-client` | `upclient` | Cognito User Pool Client |
| `cognito-user-pool-domain` | `updomain` | Cognito User Pool Domain |
| `cognito-identity-pool` | `idpool` | Cognito Identity Pool |
### 监控与日志服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `logs`, `log-group` | `logs` | CloudWatch Log Group |
| `alarm`, `cloudwatch-alarm` | `alarm` | CloudWatch Alarm |
### 集成服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `eventbridge` | `eb` | EventBridge bus |
| `eventbridge-rule` | `ebrule` | EventBridge rule |
| `sns`, `sns-topic` | `sns` | SNS topic |
| `sqs`, `sqs-queue` | `sqs` | SQS queue |
| `apigateway`, `api-gateway`, `apigw-rest` | `apigw` | API Gateway REST API |
| `apigw-http` | `httpapi` | API Gateway HTTP API |
| `apigw-websocket` | `wsapi` | API Gateway WebSocket API |
### AI/ML 服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `bedrock` | `bedrock` | Bedrock agent/model |
| `bedrock-agent` | `agent` | Bedrock agent |
| `bedrock-kb` | `kb` | Bedrock knowledge base |
### 内容分发服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `cloudfront`, `cloudfront-dist` | `cf` | CloudFront distribution |
### 治理与管理服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `config` | `config` | AWS Config |
| `config-aggregator` | `cfgagg` | Config aggregator |
| `config-rule` | `cfgrule` | Config rule |
### 应用程序服务
| 资源类型 | 缩写 | 描述 |
|--------------|--------------|-------------|
| `app` | `app` | Generic application |
### 使用示例
```
# Lambda function
resource_type = "lambda" # → acme-payments-prod-lambda
# DynamoDB table
resource_type = "dynamodb" # → acme-payments-prod-ddb
# API Gateway (多个别名)
resource_type = "apigateway" # → acme-payments-prod-apigw
resource_type = "api-gateway" # → acme-payments-prod-apigw
resource_type = "apigw-rest" # → acme-payments-prod-apigw
# Cognito User Pool
resource_type = "cognito-user-pool" # → acme-payments-prod-userpool
```
## 优势
1. **集中化策略管理**：安全策略一次定义，到处应用
2. **环境感知**：根据环境自动配置安全控件
3. **合规性支持**：内置支持合规性框架
4. **一致的标签**：对所有资源应用标准标签
5. **审计追踪**：在代码中记录覆盖理由
6. **灵活性**：可以在需要时通过提供理由来覆盖控件
7. **标准化命名**：所有基础设施使用一致的资源名称
## 区域配置
`region` 变量是基础设施中一致的资源命名和标记所必需的。虽然 AWS provider 配置可以从凭证或环境变量中自动检测区域，但将区域显式传递给此模块可确保：
1. **CI/CD 流水线控制**：在使用 Terragrunt 或类似工具的自动化流水线（GitHub Actions、GitLab CI 等）中，您可以显式控制资源部署到哪个区域
2. **一致的命名**：区域缩写（例如，`us-east-1` → `use1`）包含在资源名称和路径中
3. **多区域部署**：当部署到多个区域时，每个模块实例可以拥有自己特定于区域的命名
**在 CI/CD 中的使用**：
```
# 在你的 Terragrunt 或 Terraform 配置中
module "metadata" {
source = "github.com/islamelkadi/terraform-aws-metadata"
namespace = "myorg"
project_name = "myapp"
environment = "prod"
region = var.region # Passed from pipeline or tfvars
resource_type = "lambda"
}
```
**设置区域**：
- 通过变量：`region = "us-east-1"`
- 通过环境变量：`export TF_VAR_region="us-east-1"`
- 通过 tfvars 文件：在 `terraform.tfvars` 中设置 `region = "us-east-1"`
- 通过 AWS provider：如果区域为 null，模块将使用 `data.aws_region.current` 作为回退
## MCP 服务器
本模块包含两个在 `.kiro/settings/mcp.json` 中配置的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，用于 Kiro：
| 服务器 | 包 | 描述 |
|--------|---------|-------------|
| `aws-docs` | `awslabs.aws-documentation-mcp-server@latest` | 提供对 AWS 文档的访问，用于服务功能、API 参考和最佳实践的上下文查找。 |
| `terraform` | `awslabs.terraform-mcp-server@latest` | 支持直接从 IDE 执行 Terraform 操作（init、validate、plan、fmt、tflint），并为常见工作流提供自动批准的命令。 |
这两个服务器都通过 `uvx` 运行，除了 [引导](#prerequisites) 步骤外，不需要额外的安装。
## 要求
| 名称 | 版本 |
|------|---------|
| [terraform](#requirement\_terraform) | >= 1.14.3 |
| [aws](#requirement\_aws) | >= 6. |
## Providers
| 名称 | 版本 |
|------|---------|
| [aws](#provider\_aws) | >= 6.34 |
## Modules
No modules.
## Resources
| 名称 | 类型 |
|------|------|
| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
| [aws_organizations_organization.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/organizations_organization) | data source |
| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source |
## Inputs
| 名称 | 描述 | 类型 | 默认值 | 必填 |
|------|-------------|------|---------|:--------:|
| [compliance\_frameworks](#input\_compliance\_frameworks) | 要强制执行的合规性框架列表（例如：FCAC、PCI\_DSS、SOC2） | `list(string)` | `[]` | no |
| [environment](#input\_environment) | 部署配置聚合器的环境名称（dev、test、prod 等）。用于语义组织。 | `string` | `"dev"` | no |
| [namespace](#input\_namespace) | 用于资源命名和标记的命名空间（组织/团队名称）。 | `string` | n/a | yes |
| [project\_name](#input\_project\_name) | 分配给此项目的唯一名称。用于语义组织。 | `string` | n/a | yes |
| [region](#input\_region) | 部署用的 AWS 区域。用于感知区域的命名，并传递给消费者模块以进行 provider 配置。 | `string` | `null` | no |
| [resource\_type](#input\_resource\_type) | 正在创建的资源类型（例如：config-aggregator、s3-bucket 等） | `string` | n/a | yes |
| [security\_profile](#input\_security\_profile) | 要应用的安全配置文件（dev、staging、prod）。决定安全控件的默认值。 | `string` | `null` | no |
## Outputs
| 名称 | 描述 |
|------|-------------|
| [account\_id](#output\_account\_id) | AWS 账户 ID。 |
| [effective\_security\_profile](#output\_effective\_security\_profile) | 正在应用的有效安全配置文件（dev、staging 或 prod） |
| [organization\_id](#output\_organization\_id) | AWS 组织 ID。 |
| [region\_code](#output\_region\_code) | AWS 区域代码（缩写）。 |
| [region\_name](#output\_region\_name) | AWS 区域名称。 |
| [resource\_path](#output\_resource\_path) | 格式为 /organization/project/environment/resourcetype/ 的资源路径 |
| [resource\_path\_with\_region](#output\_resource\_path\_with\_region) | 包含区域的资源路径，格式为 /organization/project/environment/region/resourcetype/ |
| [resource\_prefix](#output\_resource\_prefix) | 格式为 organization-project-environment-resourcetype 的资源前缀 |
| [resource\_prefix\_with\_region](#output\_resource\_prefix\_with\_region) | 包含区域的资源前缀，格式为 organization-project-environment-region-resourcetype |
| [resource\_type\_code](#output\_resource\_type\_code) | 资源类型代码（缩写）。 |
| [security\_controls](#output\_security\_controls) | 基于环境和安全配置文件的安全控件配置 |
| [security\_tags](#output\_security\_tags) | 应用于所有资源的标准安全和合规性标签 |
标签：AWS, AWS Organizations, DPI, EC2, ECS, FCAC, HIPAA, IaC, ISO27001, Kiro, PCI DSS, Python, SOC2, Terraform, 云治理, 人工智能安全, 企业级, 合规性, 命名规范, 安全控制, 开发工具库, 无后门, 标签管理, 漏洞利用检测, 自动化运维, 资源元数据, 身份与访问管理, 逆向工具