# CloudWatch 管道 IAM 策略和权限
<a name="pipeline-iam-reference"></a>

本节详细介绍了 CloudWatch 管道的 IAM 要求，包括 API 调用方的权限、特定于来源的策略、信任关系和资源策略。

## API 调用方权限
<a name="api-caller-permissions"></a>

在管道配置中指定的任何调用 `CreateTelemetryPipeline` API 的角色（例如 S3 来源角色、Secrets Manager 访问角色或 CloudWatch Logs 来源角色）都必须具有特定权限才能传递角色。

**PassRole 权限**

针对管道配置中指定的任何角色（S3 来源角色、Secrets Manager 访问角色或 CloudWatch Logs 来源角色）均为必填项。

**Example 适用于 S3 来源的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "PassRoleForS3Source",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::your-account-id:role/your-s3-source-role"
        }
    ]
}
```

**Example 适用于 Secrets Manager 来源的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "PassRoleForSecretsManagerSource",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::your-account-id:role/your-secrets-manager-role"
        }
    ]
}
```

**Example 适用于 CloudWatch Logs 来源的 IAM 策略**  

```
{
    "Version": "2012-10-17", 		 	 	 
    "Statement": [
        {
            "Sid": "PassRoleForCloudWatchLogsSource",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::your-account-id:role/your-cloudwatch-logs-role""
        }
  ]
}
```

**管道规则权限**

使用 `cloudwatch_logs` 来源进行创建/更新操作 (`logs:PutPipelineRule`) 和删除操作 (`logs:DeletePipelineRule`) 时，角色还必须具有执行这些操作的权限。

**Example 适用于 CloudWatch Logs 管道规则的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "PipelineRuleForCloudWatchLogs",
            "Effect": "Allow",
            "Action": [
                "logs:PutPipelineRule",
                "logs:DeletePipelineRule"
            ],
            "Resource": "*"
        }
    ]
}
```

**使用条件键缩小范围**

要将权限策略范围缩小到遥测管道，您可以指定条件键，如以下示例所示：

**Example 适用于 S3 来源的 IAM 策略（基本）**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "PassRoleForS3Source",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::your-account-id:role/your-s3-source-role"
        }
    ]
}
```

**Example 适用于 S3 来源的 IAM 策略（使用条件键缩小范围）**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "PassRoleForS3Source",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::your-account-id:role/your-s3-source-role",
            "Condition": {
              "StringEquals": {
                "iam:PassedToService": [
                  "telemetry-pipelines.observabilityadmin.amazonaws.com"
                ],
                "iam:AssociatedResourceARN": [
                  "arn:aws:observabilityadmin:your-region:your-account-id:telemetry-pipeline/*"
                ]
              }
            }
        }
    ]
}
```

**Example 适用于 Secrets Manager 来源的 IAM 策略（基本）**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "PassRoleForSecretsManagerSource",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::your-account-id:role/your-secrets-manager-role"
        }
    ]
}
```

**Example 适用于 Secrets Manager 来源的 IAM 策略（使用条件键缩小范围）**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
          "Sid": "PassRoleForSecretsManagerSource",
          "Effect": "Allow",
          "Action": "iam:PassRole",
          "Resource": "arn:aws:iam::your-account-id:role/your-secrets-manager-role",
          "Condition": {
            "StringEquals": {
              "iam:PassedToService": [
                "telemetry-pipelines.observabilityadmin.amazonaws.com"
              ],
              "iam:AssociatedResourceARN": [
                "arn:aws:observabilityadmin:your-region:your-account-id:telemetry-pipeline/*"
              ]
            }
          }
        }
    ]
}
```

**Example 适用于 CloudWatch Logs 来源的 IAM 策略（使用条件键缩小范围）**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
          "Sid": "PassRoleForCloudWatchLogsSource",
          "Effect": "Allow",
          "Action": "iam:PassRole",
          "Resource": "arn:aws:iam::your-account-id:role/your-cloudwatch-logs-role",
          "Condition": {
            "StringEquals": {
              "iam:PassedToService": [
                "logs.amazonaws.com"
              ],
              "iam:AssociatedResourceARN": [
                "arn:aws:observabilityadmin:your-region:your-account-id:telemetry-pipeline/*"
              ]
            }
          }
        }
    ]
}
```

## 管道条件键
<a name="pipeline-condition-keys"></a>

CloudWatch 管道支持 IAM 条件键，让您可以根据日志来源名称和类型限制谁可以创建管道。使用这些条件键在整个组织中强制执行治理策略。可用条件键

`observabilityadmin:SourceName`  
将管道创建限制为特定的日志来源名称。

`observabilityadmin:SourceType`  
将管道创建限制为特定的日志来源类型。

**Example 按来源类型限制管道创建的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowPipelineCreationForSpecificSourceType",
            "Effect": "Allow",
            "Action": "observabilityadmin:CreateTelemetryPipeline",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "observabilityadmin:SourceType": "cloudwatch_logs"
                }
            }
        }
    ]
}
```

**Example 按来源名称限制管道创建的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowPipelineCreationForSpecificSource",
            "Effect": "Allow",
            "Action": "observabilityadmin:CreateTelemetryPipeline",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "observabilityadmin:SourceName": "your-source-name"
                }
            }
        }
    ]
}
```

## 人工智能辅助的处理器配置权限
<a name="ai-assisted-permissions"></a>

要在 CloudWatch 管道控制台中使用人工智能辅助的处理器配置，IAM 主体必须拥有 `logs:GeneratePipeline` 权限。此权限授权根据自然语言描述生成处理器配置。

**Example 用于人工智能辅助处理器配置的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowGeneratePipeline",
            "Effect": "Allow",
            "Action": "logs:GeneratePipeline",
            "Resource": "*"
        }
    ]
}
```

## 特定于来源的 IAM 策略
<a name="source-specific-iam-policies"></a>

不同的来源类型需要特定的 IAM 权限才能访问其各自的数据来源。

**CloudWatch Logs 来源**

对于 CloudWatch Logs 来源，管道配置中指定的任何 IAM 角色都必须与 `logs.amazonaws.com` 存在信任关系。

**Example 适用于 CloudWatch Logs 来源的 IAM 角色信任策略（基本）**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            ""Effect": "Allow",
            "Principal": {
                "Service": "logs.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

**S3 来源**

对于 S3 来源，客户必须为 IAM 角色提供访问 S3 对象和 SQS 队列的权限。

**Example 适用于 S3 来源的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "s3-access",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::your-bucket-name/*"
        },
        {
            "Sid": "sqs-access",
            "Effect": "Allow",
            "Action": [
                "sqs:ReceiveMessage",
                "sqs:DeleteMessage",
                "sqs:ChangeMessageVisibility"
            ],
            "Resource": "arn:aws:sqs:your-region:your-account-id:your-queue-name"
        },
        {
            "Sid": "kms-access",
            "Effect": "Allow",
            "Action": "kms:Decrypt",
            "Resource": "arn:aws:kms:your-region:your-account-id:key/your-key-id",
            "Condition": {
                "Comment": "Only required if S3 buckets and/or SQS queue uses KMS encryption"
            }
        }
    ]
}
```

**使用 Amazon Secrets Manager 的来源**

对于引用 Amazon Secrets Manager 的来源（Microsoft Office 365、Microsoft Entra ID、Palo Alto NGFW），客户必须为 IAM 角色提供 Secrets Manager 访问权限。

**Example 适用于 Secrets Manager 来源的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "secrets-manager-access",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:your-region:your-account-id:secret:your-secret-name*"
        },
        {
            "Sid": "kms-access",
            "Effect": "Allow",
            "Action": "kms:Decrypt",
            "Resource": "arn:aws:kms:your-region:your-account-id:key/your-key-id",
            "Condition": {
                "Comment": "Only required if Secrets Manager uses KMS encryption"
            }
        }
    ]
}
```

## 信任关系
<a name="trust-relationships"></a>

在管道配置中指定的任何 IAM 角色都必须与 CloudWatch 管道服务主体具有信任关系。

**管道角色信任策略**

所有管道角色都必须信任 `telemetry-pipelines.observabilityadmin.amazonaws.com` 服务主体。

**Example 管道角色的信任策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "telemetry-pipelines.observabilityadmin.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

## 资源策略
<a name="resource-policies"></a>

写入日志组的管道需要使用 CloudWatch Logs 资源策略，使用 `cloudwatch_logs` 来源的管道除外。

**CloudWatch Logs** 资源策略

调用 `CreateTelemetryPipeline` API 后，您将收到管道 ARN。对于来源不是 `cloudwatch_logs` 的管道，客户必须调用 `[logs:PutResourcePolicy](https://docs.amazonaws.cn/AmazonCloudWatchLogs/latest/APIReference/API_PutResourcePolicy.html)` 以允许 CloudWatch 管道服务主体写入配置的日志组。

**时间约束**  
收到管道 ARN 后，您只能在有限的时间窗口（少于 5 分钟）内创建资源策略。如果管道在策略实施之前变为活动状态，则数据将被丢弃。

**Example logs:PutResourcePolicy 请求**  

```
{
    "policyName": "resourceArn=arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*",
    "policyDocument": {
        "Version": "2012-10-17",		 	 	 
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "Service": "telemetry-pipelines.observabilityadmin.amazonaws.com"
                },
                "Action": [
                    "logs:CreateLogStream",
                    "logs:PutLogEvents"
                ],
               
                "Condition": {
                    "StringEquals": {
                        "aws:SourceArn": "arn:aws:observabilityadmin:your-region:your-account-id:telemetry-pipeline/your-pipeline-id"
                    }
                }
            }
        ]
    }
}
```

## 管理资源策略
<a name="managing-resource-policies"></a>

 本指南提供使用 Amazon CLI 为遥测管道创建或更新 CloudWatch Logs 资源策略的步骤。

检查是否存在现有策略：

```
aws logs describe-resource-policies --resource-arn arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*
```

这将返回附加到日志组的所有现有资源策略。查找任何可能已与您的日志组关联的策略。

如果不存在资源策略，请创建一个新资源策略：

```
aws logs put-resource-policy \
        --region <YOUR-REGION> \
        --policy-name  "resourceArn": "arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*"\
        --policy-document '{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "telemetry-pipelines.observabilityadmin.amazonaws.com"
            },
            "Action": [
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": "arn:aws:observabilityadmin:your-region:your-account-id:telemetry-pipeline/your-pipeline-id"
                }
            }
        }
    ]
}'
```

替换以下占位符：
+  *your-region* – 您的 Amazon 区域（例如 us-east-1）
+  *your-account-id* – 您的 12 位 Amazon 账户 ID
+  *your-log-group-name* – 您的 CloudWatch Logs 日志组名称
+  *your-pipeline-id* – 您的遥测管道 ID

 如果资源策略已经存在，请将新语句与其合并：

1. 检索现有策略：

   ```
   aws logs describe-resource-policies --resource-arn arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*
   ```

1.  打开 `existing-policy.json` 并将新语句添加到现有 `Statement` 数组中：

   ```
   {
       "Version": "2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "Service": "existing-service.amazonaws.com"
               },
               "Action": [
                   "logs:SomeAction"
               ]
           },
           {
               "Effect": "Allow",
               "Principal": {
                   "Service": "telemetry-pipelines.observabilityadmin.amazonaws.com"
               },
               "Action": [
                   "logs:CreateLogStream",
                   "logs:PutLogEvents"
               ],
             
               "Condition": {
                   "StringEquals": {
                       "aws:SourceArn": "arn:aws:observabilityadmin:your-region:your-account-id:telemetry-pipeline/your-pipeline-id"
                   }
               }
           }
       ]
   }
   ```

1. 更新策略：

   ```
   aws logs put-resource-policy \
           --region your-region \
           --policy-name resourceArn=arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:* \
           --policy-document file://existing-policy.json
   ```

确认策略已成功创建或更新：

```
aws logs describe-resource-policies --resource-arn arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*
```