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

本节介绍 CloudWatch 管道的 IAM 要求。所需权限因数据来源和集成方法而异。

下表有助您确定哪些 IAM 部分适用于您的使用案例。


| 使用案例 | 集成方法 | 管道配置中的来源类型 | 需要的 IAM 部分 | 
| --- | --- | --- | --- | 
| [第三方集成（API 拉取）](data-sources-third-party.md) | 管道使用存储的凭证通过供应商 API 拉取 | microsoft\_office365 okta\_sso、palo\_alto\_ngfw、等 | [API 调用方权限](#api-caller-permissions) \+ [第三方来源（API 拉取）](#third-party-api-pull) \+ [资源策略](#resource-policies) | 
| [第三方集成（S3 传输）](data-sources-third-party.md) | 供应商将文件传输到您的 S3 存储桶 | s3 | [API 调用方权限](#api-caller-permissions) \+ [第三方来源（S3 传输）](#third-party-s3-delivery) \+ [资源策略](#resource-policies) | 
| [来自 S3 的自定义数据](data-sources-custom.md) | 您的应用程序将数据写入 S3，然后由管道从存储桶中读取 | s3 | [API 调用方权限](#api-caller-permissions) \+ [来自 S3 的自定义数据](#custom-data-s3) \+ [资源策略](#resource-policies) | 
| [来自 CloudWatch Logs 的自定义数据](data-sources-custom.md) | 您的应用程序将日志发布到 CloudWatch Logs 日志组 | cloudwatch\_logs | [API 调用方权限](#api-caller-permissions) \+ [来自 CloudWatch Logs 的自定义数据](#custom-data-cloudwatch-logs) | 
| [公开发布的 AWS 服务日志](data-sources-aws-services.md) | AWS 服务将日志传输到 CloudWatch Logs（VPC 流日志、Route 53） | cloudwatch\_logs | [API 调用方权限](#api-caller-permissions) \+ [公开发布的 AWS 服务日志](#vended-service-logs) | 

**注意**  
创建管道后，基于 S3 的来源（`s3`）需要具有资源策略。CloudWatch Logs 来源（`cloudwatch_logs`）不需要资源策略。

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

调用 `CreateTelemetryPipeline` 的 IAM 主体需要具有管道配置中所提及任何角色的 `iam:PassRole` 权限。

**Example PassRole 策略模板**  

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

请根据使用案例的要求，将 {{service-principal}} 替换为下表中的值。


| 使用案例 | 服务主体值 | 
| --- | --- | 
| 第三方（API 拉取） | telemetry-pipelines.observabilityadmin.amazonaws.com | 
| 第三方（S3 传输） | telemetry-pipelines.observabilityadmin.amazonaws.com | 
| 来自 S3 的自定义数据 | telemetry-pipelines.observabilityadmin.amazonaws.com | 
| 来自 CloudWatch Logs 的自定义数据 | logs.amazonaws.com | 
| 公开发布的 AWS 服务日志 | logs.amazonaws.com | 

**注意**  
建议使用 `Condition` 块，但这是可选的。不使用此块时，该角色可能会被传递给任何服务。

### 管道规则权限（仅限 CloudWatch Logs 来源）
<a name="pipeline-rule-permissions"></a>

将 `cloudwatch_logs` 用作来源时，API 调用者还需要具有管道规则操作的权限。`CreateTelemetryPipeline` 和 `UpdateTelemetryPipeline` 操作都必须具有 `logs:PutPipelineRule` 权限。`DeleteTelemetryPipeline` 操作必须具有 `logs:DeletePipelineRule` 权限。

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

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

## 来源角色策略
<a name="source-role-policies"></a><a name="source-specific-iam-policies"></a><a name="trust-relationships"></a>

每个管道都必须有一个专用 IAM 角色，服务将代入该角色来读取您的数据。以下小节提供了每个使用案例的完整策略（权限和信任策略）。

### 第三方来源（API 拉取）
<a name="third-party-api-pull"></a>

本节适用于 Microsoft Office 365、Microsoft Entra ID、Okta SSO、Palo Alto NGFW，以及其他在 AWS Secrets Manager 中存储凭证的供应商 API 集成。

**权限策略**

以下策略将允许该角色检索您存储的 API 凭证。

**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}}"
        }
    ]
}
```

**注意**  
只有当 Secrets Manager 中的密钥使用客户自主管理型 KMS 密钥加密时，才需要 `kms:Decrypt` 语句。

**信任策略**

**Example API 拉取来源的信任策略**  

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

#### 完成 API 拉取管道的 IAM 设置
<a name="api-pull-complete-setup"></a>

以下示例演示了端到端创建第三方 API 拉取管道所需的所有 IAM 策略。

**调用者身份策略** – 附加到调用 `CreateTelemetryPipeline` 的主体：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "CreateApiPullPipeline",
            "Effect": "Allow",
            "Action": [
                "observabilityadmin:CreateTelemetryPipeline",
                "iam:PassRole"
            ],
            "Resource": "*"
        }
    ]
}
```

**来源角色权限策略** – 附加到管道所代入的角色：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "SecretsManagerAccess",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:{{your-region}}:{{your-account-id}}:secret:{{your-secret-name}}*"
        }
    ]
}
```

**来源角色信任策略**：

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

**注意**  
创建管道后，您还必须在 5 分钟内创建一个资源策略。请参阅[资源策略](#resource-policies)。

**注意**  
对于生产用途，请使用 [API 调用方权限](#api-caller-permissions) 中演示的条件键缩小 `iam:PassRole` 的范围。如果您的密钥使用客户自主管理型 KMS 密钥，请将 `kms:Decrypt` 添加到来源角色权限策略中。

### 第三方来源（S3 传输）
<a name="third-party-s3-delivery"></a>

本节适用于向您的 S3 存储桶传输日志文件的任何第三方供应商（例如 CrowdStrike Falcon、Wiz 或 Cisco Umbrella）。

**权限策略**

以下策略会允许该角色从 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}}"
        }
    ]
}
```

**注意**  
只有当您的 S3 存储桶或 SQS 队列使用客户自主管理型 KMS 密钥进行加密时，才需要 `kms:Decrypt` 语句。

**信任策略**

**Example S3 传输来源的信任策略**  

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

#### 完成 S3 传输管道的 IAM 设置
<a name="s3-delivery-complete-setup"></a>

以下示例演示了端到端创建 S3 传输管道所需的所有 IAM 策略。

**调用者身份策略** – 附加到调用 `CreateTelemetryPipeline` 的主体：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "CreateS3Pipeline",
            "Effect": "Allow",
            "Action": [
                "observabilityadmin:CreateTelemetryPipeline",
                "iam:PassRole"
            ],
            "Resource": "*"
        }
    ]
}
```

**来源角色权限策略** – 附加到管道所代入的角色：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "S3Access",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::{{your-bucket-name}}/*"
        },
        {
            "Sid": "SqsAccess",
            "Effect": "Allow",
            "Action": [
                "sqs:ReceiveMessage",
                "sqs:DeleteMessage",
                "sqs:ChangeMessageVisibility"
            ],
            "Resource": "arn:aws:sqs:{{your-region}}:{{your-account-id}}:{{your-queue-name}}"
        }
    ]
}
```

**来源角色信任策略**：

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

**注意**  
创建管道后，您还必须在 5 分钟内创建一个资源策略。请参阅[资源策略](#resource-policies)。

**注意**  
对于生产用途，请使用 [API 调用方权限](#api-caller-permissions) 中演示的条件键缩小 `iam:PassRole` 的范围。如果您的 S3 存储桶或 SQS 队列使用客户自主管理型 KMS 密钥，请将 `kms:Decrypt` 添加到来源角色权限策略中。

### 来自 S3 的自定义数据
<a name="custom-data-s3"></a>

本节适用于您自己的应用程序或基础设施将日志文件写入 S3 存储桶的场景。

IAM 设置与[第三方来源（S3 传输）](#third-party-s3-delivery)相同。创建同样的权限策略和信任策略。无论数据由谁写入，管道都会根据 SQS 事件通知从您的存储桶中读取数据。

### 来自 CloudWatch Logs 的自定义数据
<a name="custom-data-cloudwatch-logs"></a>

本节适用于您自己的应用程序（例如，Lambda 函数、ECS 容器或自定义 EC2 应用程序）将日志发布到 CloudWatch Logs 日志组的场景。

**权限策略**

以下策略会允许该角色处理来自您指定日志组的日志。

**Example CloudWatch Logs 来源的 IAM 策略**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "logs-processing-access",
            "Effect": "Allow",
            "Action": [
                "logs:processWithPipeline"
            ],
            "Resource": [
                "arn:aws:logs:{{your-region}}:{{your-account-id}}:log-group:{{your-log-group-01}}",
                "arn:aws:logs:{{your-region}}:{{your-account-id}}:log-group:{{your-log-group-02}}"
            ]
        }
    ]
}
```

您可以使用 `logs:data_source_name` 和 `logs:data_source_type` 条件键来限制哪些管道来源可以调用转换，从而缩小此权限的范围。`logs:data_source_name` 值对应于管道配置中的 `data_source_name`，`logs:data_source_type` 对应于管道配置中的 `data_source_type`。

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

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowProcessWithPipelineScopedDown",
            "Effect": "Allow",
            "Action": "logs:ProcessWithPipeline",
            "Resource": "arn:aws:logs:{{your-region}}:{{your-account-id}}:log-group:{{your-log-group-name}}",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "{{your-account-id}}",
                    "logs:data_source_name": "{{your-source-name}}",
                    "logs:data_source_type": "{{your-source-type}}"
                }
            }
        }
    ]
}
```

**注意**  
CloudWatch Logs 来源的 IAM 角色需要同时具有信任策略（以便 `logs.amazonaws.com` 代入该角色）和权限策略（用于授予 `logs:ProcessWithPipeline` 权限）。如果没有这两个策略，CloudWatch 管道将无法在摄取期间转换日志事件。

**信任策略**

**Example CloudWatch Logs 来源的信任策略**  

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

**注意**  
CloudWatch Logs 来源管道不需要任何资源策略。

#### 完成 CloudWatch Logs 管道的 IAM 设置
<a name="cloudwatch-logs-complete-setup"></a>

以下示例演示了端到端创建 CloudWatch Logs 管道所需的所有 IAM 策略。

**调用者身份策略** – 附加到调用 `CreateTelemetryPipeline` 的主体：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "CreateLogsPipeline",
            "Effect": "Allow",
            "Action": [
                "observabilityadmin:CreateTelemetryPipeline",
                "logs:PutPipelineRule",
                "logs:DeletePipelineRule",
                "iam:PassRole"
            ],
            "Resource": "*"
        }
    ]
}
```

**来源角色权限策略** – 附加到管道所代入的角色：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "LogsProcessing",
            "Effect": "Allow",
            "Action": [
                "logs:processWithPipeline"
            ],
            "Resource": [
                "arn:aws:logs:{{your-region}}:{{your-account-id}}:log-group:{{your-log-group}}"
            ]
        }
    ]
}
```

**来源角色信任策略**：

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

**注意**  
对于生产用途，请使用 [API 调用方权限](#api-caller-permissions) 中演示的条件键缩小 `iam:PassRole` 的范围。

### 公开发布的 AWS 服务日志
<a name="vended-service-logs"></a>

本节适用于传输到 CloudWatch Logs 的 AWS 服务日志，例如 VPC 流日志、Route 53 查询日志以及其他由 AWS 公开发布的日志类型。

IAM 设置与[来自 CloudWatch Logs 的自定义数据](#custom-data-cloudwatch-logs)相同。使用相同的权限策略（将 `logs:processWithPipeline` 范围限定于该日志组）和相同的信任策略 (`logs.amazonaws.com`)。

由于这将使用 `cloudwatch_logs` 来源类型，因此调用者还需要具有 `logs:PutPipelineRule` 和 `logs:DeletePipelineRule` 权限。请参阅[管道规则权限（仅限 CloudWatch Logs 来源）](#pipeline-rule-permissions)。

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

基于 S3 的来源和基于 Secrets Manager 的来源（第三方集成）需要 CloudWatch Logs 资源策略。CloudWatch Logs 来源（自定义数据或已公开发布的日志）**不需要**资源策略。

调用 `CreateTelemetryPipeline` 后，您会收到管道 ARN。您必须调用 `[logs:PutResourcePolicy](https://docs.aws.amazon.com/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>

使用 AWS CLI 为 CloudWatch 管道创建或更新 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 file://policy.json
```

**与现有策略合并**

如果资源策略已经存在，请将此新语句添加到策略文档的现有 `Statement` 数组中，然后使用合并后的文件再次调用 `put-resource-policy`。

1. 检索现有策略：

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

1. 将此新语句添加到现有 `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}}:*
```

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

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

CloudWatch 管道支持使用 IAM 条件键来限定可以创建管道的主体以及可以代入来源角色的账户。使用这些条件键在整个组织中强制执行治理策略。

### CreateTelemetryPipeline 条件
<a name="create-pipeline-conditions"></a>

在身份策略中使用这些条件键来控制主体可以创建的管道。

`observabilityadmin:SourceType`  
将管道创建限制为特定的来源类型。支持的值包括 `cloudwatch_logs`、`s3`、`microsoft_office365`、`okta_sso` 和 `palo_alto_ngfw`。

**Example 按来源类型限制管道创建**  

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

### 来源角色信任策略条件
<a name="source-role-trust-conditions"></a>

在来源角色的信任策略中使用这些条件键来限制可以代入该角色的账户。这样可以防止服务可能会代表其他账户执行操作的混淆代理攻击。

`aws:SourceAccount`  
将角色代入限制为来自特定 AWS 账户的请求。

`aws:SourceArn`  
将角色代入限制为来自特定资源 ARN（例如，日志组）的请求。

**Example 具有 SourceAccount 条件的信任策略（CloudWatch Logs 来源）**  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "logs.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "{{your-account-id}}"
                },
                "ArnLike": {
                    "aws:SourceArn": "arn:aws:logs:{{your-region}}:{{your-account-id}}:log-group:*"
                }
            }
        }
    ]
}
```

## 人工智能辅助的处理器配置权限
<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": "*"
        }
    ]
}
```