c7n-mailer: Custodian邮件发送器

% [注释]: # (!!! 重要 !!!) % [注释]: # (此文件在文档生成过程中已移动。) % [注释]: # (仅编辑位于 ./tools/c7n_mailer/README.md 的原始文档)

Custodian的邮件发送器实现。出站邮件投递目前仍然有些组织特定，因此目前主要用作示例实现。

现在可以在Docker容器中轻松运行Cloud Custodian邮件发送器。有关详细信息，请点击此处。

消息中继

保管员邮件发送器订阅SQS队列，查找用户，并通过SES、Slack消息和/或通知发送到DataDog或Splunk发送电子邮件。保管员Lambda和实例策略可以向SQS队列发送消息。SQS队列应启用跨账户发送以在账户之间发送。

教程

我们开始使用保管员邮件发送器的目标是安装邮件发送器，并运行一个触发电子邮件到您收件箱的策略。

1. 在您的笔记本电脑上安装邮件发送器（如果您不是在Docker容器中运行）
   • 或使用pip install c7n-mailer
2. 在您的文本编辑器中创建一个mailer.yml文件来存储您的邮件发送器配置。
3. 在AWS控制台中，创建一个新的标准SQS队列（快速创建即可）。将队列URL复制到mailer.yml中的queue_url。
4. 在AWS中，查找或创建一个具有队列读取访问权限的角色。获取角色ARN并将其设置为mailer.yml中的role。

有不同的通知端点选项，您可以同时使用两者。

电子邮件

请确保您的电子邮件地址已在SES中验证，并将其设置为mailer.yml中的from_address。默认情况下，SES处于沙盒模式，您必须验证每封电子邮件的每个单独的收件人。如果需要，请提交AWS支持工单，以退出SES沙盒模式。

您的mailer.yml现在看起来可能像这样

queue_url: https://sqs.us-east-1.amazonaws.com/1234567890/c7n-mailer-test
role: arn:aws:iam::123456790:role/c7n-mailer-test
from_address: you@example.com

如果您不在us-east-1以外的区域，也可以设置region以及设置lambda_tags以给邮件发送器添加标签。

region: us-east-2
lambda_tags:
  owner: ops

现在让我们创建一个保管员策略来填充您的邮件发送器队列。创建一个test-policy.yml文件，内容如下（更新to和queue以匹配您的环境）

  policies:
  - name: c7n-mailer-test
    resource: sqs
    filters:
      - "tag:MailerTest": absent
    actions:
      - type: notify
        template: default
        priority_header: '2'
        subject: testing the c7n mailer
        to:
          - you@example.com
        transport:
          type: sqs
          queue: https://sqs.us-east-1.amazonaws.com/1234567890/c7n-mailer-test

DataDog

完成DataDog集成的标准方式是使用c7n集成AWS CloudWatch，并使用DataDog与AWS的集成来收集CloudWatch指标。邮件发送器/信使集成仅适用于您不想或无法使用AWS CloudWatch的情况，例如在Azure或GCP中。

请注意，此集成需要额外的依赖项Datadog Python绑定

pip install datadog

您的mailer.yml现在看起来可能像这样

queue_url: https://sqs.us-east-1.amazonaws.com/1234567890/c7n-mailer-test
role: arn:aws:iam::123456790:role/c7n-mailer-test
datadog_api_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX
datadog_application_key: YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

（如果不在us-east-1以外的区域，也请设置region。）

现在，让我们创建一个保管员策略来填充您的邮件发送器队列。创建一个test-policy.yml

policies:
  - name: c7n-mailer-test
    resource: ebs
    filters:
     - Attachments: []
    actions:
      - type: notify
        to:
          - datadog://?metric_name=datadog.metric.name&metric_value_tag=Size
        transport:
          type: sqs
          queue: https://sqs.us-east-1.amazonaws.com/1234567890/c7n-mailer-test

有一个特殊的to格式，用于指定DataDog的投递，并包括通过URL参数的DataDog配置

• metric_name：是要发送到DataDog的指标名称。
• metric_value_tag：默认情况下，发送到DataDog的指标值为1，但如果您想使用策略返回的标签之一，可以使用metric_value_tag属性来设置它。例如，在test-policy.yml策略中，使用的值是EBS卷的大小。值必须是数字，并将其转换为浮点值。

Slack

保管员邮件发送器支持Slack消息作为单独的通知机制，用于SQS传输方法。要启用Slack集成，您必须在mailer.yml文件中的slack_token字段中指定Slack令牌。例如

queue_url: https://sqs.us-east-1.amazonaws.com/1234567890/c7n-mailer-test
role: arn:aws:iam::123456790:role/c7n-mailer-test
slack_token: xoxo-token123

要启用Slack消息，策略中评估了几个唯一字段，如下面的示例所示

policies:
  - name: c7n-mailer-test
    resource: ebs
    filters:
     - Attachments: []
    actions:
      - type: notify
        slack_template: slack
        slack_msg_color: danger
        to:
          - slack://owners
          - slack://foo@bar.com
          - slack://#custodian-test
          - slack://webhook/#c7n-webhook-test
          - slack://tag/resource_tag
          - https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
        transport:
          type: sqs
          queue: https://sqs.us-east-1.amazonaws.com/1234567890/c7n-mailer-test

Slack消息支持使用在slack_template中指定的独特模板字段。该字段是唯一的，使用它不会破坏在template字段中也指定了电子邮件模板的消息的现有功能。此字段是可选的，如果没有指定，邮件发送器将使用默认值slack_default。

独特的模板字段slack_msg_color可以用来指定Slack消息的颜色边框。它接受Slack预设的danger（红色）、warning（黄色）和good（绿色）。它也可以接受HTML十六进制代码。有关详细信息，请参阅Slack文档。

注意：如果您使用十六进制颜色代码，则必须将其用引号括起来，例如：slack_msg_color: '#4287f51'。否则，YAML解释器会将其视为注释。

c7n-mailer的Slack集成支持以下几种消息类型，如下所示。这些类型不是互斥的，可以使用任何类型的组合，但首选方法是传入Webhook。

Slack投递也可以通过资源标签名设置。例如，使用slack://tag/slack_channel将查找标签名为slack_channel的标签，如果与资源匹配，则将消息发送到该资源的标签值

slack_channel:https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX slack_channel:custodian-test owner:foo@bar

标签投递已在Webhook上进行测试，但它应该支持所有投递方法。

Splunk HTTP事件收集器（HEC）

Custodian邮件发送器支持将电子邮件传输方法作为独立的通知机制发送到Splunk实例的HTTP事件收集器（HEC）端点。要启用Splunk HEC集成，您必须指定HEC端点的URL以及有效的用户名和令牌

queue_url: https://sqs.us-east-1.amazonaws.com/1234567890/c7n-mailer-test
role: arn:aws:iam::123456790:role/c7n-mailer-test
splunk_hec_url: https://http-inputs-foo.splunkcloud.com/services/collector/event
splunk_hec_token: 268b3cc2-f32e-4a19-a1e8-aee08d86ca7f

要将策略的事件发送到Splunk HEC端点，请添加一个指定要发送事件的Splunk索引的to地址通知操作，格式为splunkhec://indexName

policies:
  - name: c7n-mailer-test
    resource: ebs
    filters:
     - Attachments: []
    actions:
      - type: notify
        to:
          - splunkhec://myIndexName
        transport:
          type: sqs
          queue: https://sqs.us-east-1.amazonaws.com/1234567890/c7n-mailer-test

splunkhec://indexName地址类型可以在同一通知操作中与其他目标类型（例如电子邮件、Slack、DataDog等）组合。

现在运行

c7n-mailer --config mailer.yml --update-lambda && custodian run -c test-policy.yml -s .

注意：您可以通过环境变量设置配置文件，例如：export AWS_DEFAULT_PROFILE=foo

您应该看到以下类似的输出

(env) $ c7n-mailer --config mailer.yml --update-lambda && custodian run -c test-policy.yml -s .
DEBUG:custodian.lambda:Created custodian lambda archive size: 3.01mb
2017-01-12 07:55:16,227: custodian.policy:INFO Running policy c7n-mailer-test resource: sqs region:default c7n:0.8.22.0
2017-01-12 07:55:16,229: custodian.policy:INFO policy: c7n-mailer-test resource:sqs has count:1 time:0.00
2017-01-12 07:55:18,017: custodian.actions:INFO sent message:dead-beef policy:c7n-mailer-test template:default count:1
2017-01-12 07:55:18,017: custodian.policy:INFO policy: c7n-mailer-test action: notify resources: 1 execution_time: 1.79
(env) $

检查AWS控制台中的新Lambda，名为cloud-custodian-mailer。邮件发送器每五分钟运行一次，所以请稍等片刻，然后在您的收件箱中查找邮件。如果它没有出现，请在Lambda的日志中查找调试信息。如果它出现了，恭喜！您已经开始了Custodian邮件发送器的使用。

用法 & 配置

一旦安装，你应该在你的路径上有一个c7n-mailer可执行文件

(env) $ c7n-mailer
usage: c7n-mailer [-h] -c CONFIG
c7n-mailer: error: argument -c/--config is required
(env) $

从本质上讲，c7n-mailer所做的是根据你在YAML文件中指定的配置部署一个Lambda函数（使用Mu）。以下是文件必须遵守的模式，以及选项的说明

标准Lambda函数配置

标准Azure函数配置

邮件基础设施配置

SMTP配置

如果未设置smtp_server，则c7n_mailer将使用AWS SES或Azure SendGrid。

DataDog配置

如果c7n_mailer在与DataDog代理一起运行的实例/lambda等中运行，则这些字段不是必需的。

Slack配置

SendGrid配置

Microsoft Graph配置

Splunk HEC配置

以下配置项都是可选的。标记为“Splunk必需”的项仅在您向 splunkhec:// 目标发送通知时才是必需的。

SDK配置

安全字符串

为了确保敏感数据不以明文形式存储在策略中， c7n-mailer 支持安全字符串。您可以将其视为常规 string 或使用 secure string 功能。

AWS

您可以使用KMS加密您的机密信息，并在邮件器策略中使用加密的机密信息。Custodian会尝试使用KMS解密字符串，如果失败，c7n将其视为明文机密。

 plaintext_secret: <raw_secret>
 secured_string: <encrypted_secret>

Azure

您可以将您的机密存储在Azure Key Vault机密中，并在策略中引用它们。

  plaintext_secret: <raw_secret>
  secured_string:
    type: azure.keyvault
    secret: https://your-vault.vault.azure.net/secrets/your-secret

注意：对于服务主体，KeyVault的 secrets.get 权限是必需的。

GCP

您可以将您的机密作为GCP Secret Manager机密存储，并在策略中引用它们。

  plaintext_secret: <raw_secret>
  secured_string:
    type: gcp.secretmanager
    secret: projects/12345678912/secrets/your-secret

将SMTP密码作为安全字符串设置的示例

  smtp_password:
    type: gcp.secretmanager
    secret: projects/59808015552/secrets/smtp_pw

注意：如果您未指定版本，则将向您的机密位置附加 /versions/latest。

配置策略以发送电子邮件

您可以通过包含 notify 动作将出站电子邮件添加到任何策略中。

policies:
  - name: bad-apples
    resource: asg
    filters:
     - "tag:ASV": absent
    actions:
      - type: notify
        template: default
        template_format: 'html'
        priority_header: '1'
        subject: fix your tags
        to:
          - resource-owner
        owner_absent_contact:
          - foo@example.com
        transport:
          type: sqs
          queue: https://sqs.us-east-1.amazonaws.com/80101010101/cloud-custodian-message-relay

因此，您添加一个类型为 notify 的动作。您可以指定一个用于格式化电子邮件的模板；自定义模板的说明见 下方。

to 列表指定了电子邮件的预期收件人。您可以指定电子邮件地址、SNS主题、Datadog度量或特殊值。特殊值可以是

• resource-owner，在这种情况下，电子邮件将发送到匹配策略的资源上的列出 OwnerContact 标签，或
• event-owner 对于基于推送/实时策略，将发送到负责底层事件的用户。
• priority_header 以 标题 的形式指示电子邮件的重要性。不同的电子邮件客户端将根据值显示星星、感叹号或标志。应该是从1到5的字符串。

这两个特殊值是尽力而为的，即如果没有指定 OwnerContact 标签，则不会发送 resource-owner 电子邮件，并且在 event-owner 的情况下，实例角色或系统帐户不会导致电子邮件。

可选的 owner_absent_contact 列表指定了仅在 resource-owner 特殊选项无法找到任何匹配的所有者联系标签时才通知的电子邮件地址。

此外，您可以选择使用自定义标签而不是默认的 OwnerContact。为了配置此选项，必须修改 mailer.yaml 以包括 contact_tags 和自定义标签。现在 resource-owner 将发送到自定义标签而不是 OwnerContact。

contact_tags:
  - "custom_tag"

供参考之用的 notify 动作的 JSON Schema

{
  "type": "object",
  "required": ["type", "transport", "to"],
  "properties": {
    "type": {"enum": ["notify"]},
    "to": {"type": "array", "items": {"type": "string"}},
    "owner_absent_contact": {"type": "array", "items": {"type": "string"}},
    "subject": {"type": "string"},
    "priority_header": {"type": "string"},
    "template": {"type": "string"},
    "transport": {
      "type": "object",
      "required": ["type", "queue"],
      "properties": {
        "queue": {"type": "string"},
        "region": {"type": "string"},
        "type": {"enum": ["sqs"]}
      }
    }
  }
}

在Azure上使用

要求

• c7n_azure 软件包。有关 安装Azure插件 的说明
• SendGrid帐户。有关 使用Azure中的SendGrid 的说明
• Azure存储队列

邮件发送器支持Azure存储队列传输和在Azure上使用SendGrid进行投递。为此场景的配置只需要对AWS部署进行一些小的修改。

您需要授予邮件发送器运行所在的队列上的存储队列数据贡献者角色。

策略中的通知操作将反映传输类型asq，以及指向Azure存储队列的URL。例如：

policies:
  - name: azure-notify
    resource: azure.resourcegroup
    description: send a message to a mailer instance
    actions:
      - type: notify
        template: default
        priority_header: '2'
        subject: Hello from C7N Mailer
        to:
          - you@youremail.com
        transport:
          type: asq
          queue: https://storageaccount.queue.core.windows.net/queuename

在邮件发送器配置中，您需要提供您的SendGrid API密钥，并在队列URL前缀加上asq://以让邮件发送器知道队列的类型。

queue_url: asq://storageaccount.queue.core.windows.net/queuename
from_address: you@youremail.com
sendgrid_api_key: SENDGRID_API_KEY

邮件发送器将在每次执行时传输队列上找到的所有消息，如果调用SendGrid失败，将会重试发送3次。重试后，队列消息将被丢弃。

此外，Azure上的SendGrid投递支持使用资源标签发送电子邮件。例如，在to字段中：

to:
  - tag:OwnerEmail

这将找到与资源的OwnerEmail标签关联的电子邮件地址，并向指定的地址发送电子邮件。如果没有找到标签或关联的电子邮件地址无效，则不会发送电子邮件。

部署Azure Functions

如果您的Azure邮件发送器配置了--update-lambda CLI选项，它也会部署Azure Functions。

c7n-mailer --config mailer.yml --update-lambda

其中，一个简单的使用消费函数的mailer.yml可能如下所示：

queue_url: asq://storage.queue.core.windows.net/custodian
from_address: foo@mail.com
sendgrid_api_key: <key>
function_properties:
  servicePlan:
    name: 'testmailer1'

配置函数身份

您可以通过指定函数属性下的身份配置来配置邮件器Azure函数所使用的服务主体。邮件器支持用户分配的身份、系统管理的身份，默认情况下将嵌入CLI用户的主体凭据。

当指定用户分配的身份时，与自定义管理器函数策略中只需要提供名称不同，必须提供身份的uuid/id和客户端id。您可以使用az identity list在CLI中检索此信息。

function_properties:
  identity:
    type: UserAssigned
    id: "/subscriptions/333fd504-7f11-2270-88c8-7325a27f7222/resourcegroups/c7n/providers/Microsoft.ManagedIdentity/userAssignedIdentities/mailer"
    client_id: "b9cb06fa-dfb8-4342-add3-aab5acb2abbc"

也可以使用系统管理的身份，Azure平台会在函数配置时创建身份，但是需要在配置后检索并映射到rbac权限，这项用户管理活动必须手动执行。

function_properties:
  identity:
    type: SystemAssigned

在GCP上使用

要求

• 查看c7n_gcp包。请参阅GCP入门
• google-cloud-secret-manager包，用于拉取受保护的字符串值。
• 一个可用的SMTP账户。
• GCP Pubsub订阅

邮件发送器支持GCP Pubsub传输和SMTP/电子邮件投递，以及Datadog和Splunk。为此场景的配置只需要对AWS部署进行一些小的修改。

策略中的通知操作将反映传输类型projects，以及指向GCP Pub/Sub主题的URL。例如：

policies:
  - name: gcp-notify
    resource: gcp.compute
    description: example policy
    actions:
      - type: notify
        template: default
        priority_header: '2'
        subject: Hello from C7N Mailer
        to:
          - you@youremail.com
        transport:
          type: pubsub
          topic: projects/myproject/topics/mytopic

在邮件发送器配置中，您需要提供您的SMTP账户信息以及队列_url变量中的主题订阅路径。请注意，您指定的订阅应该订阅您在策略通知操作中指定的主题。

queue_url: projects/myproject/subscriptions/mysubscription
from_address: you@youremail.com
# c7n-mailer currently requires a role be present, even if it's empty
role: ""

smtp_server: my.smtp.add.ress
smtp_port: 25
smtp_ssl: true
smtp_username: smtpuser
smtp_password:
  type: gcp.secretmanager
  secret: projects/12345678912/secrets/smtppassword

邮件发送器将使用SMTP/电子邮件投递在每个执行时传输队列上找到的所有消息。

部署GCP函数

c7n-mailer的GCP云函数目前不支持。

编写电子邮件模板

模板在jinja2中编写。将具有.j2扩展名的文件放入模板目录中，并向此存储库发送一个拉取请求。然后您可以在notify操作中通过文件名（不带扩展名）引用它。以.html.j2结尾的模板将以HTML格式发送电子邮件，所有其他模板都以纯文本形式发送。

您可以使用-t或--templates命令行参数来传递包含模板的自定义文件夹。

在渲染模板时，以下变量可用：

以下是一些额外的全局函数可用：

以下是一些额外的jinja过滤器可用：

开发者安装（OS X El Capitan）

克隆仓库

$ git clone https://github.com/cloud-custodian/cloud-custodian

安装依赖项（使用virtualenv）

$ virtualenv c7n_mailer
$ source c7n_mailer/bin/activate
$ cd tools/c7n_mailer
$ pip install -r requirements.txt

安装扩展

python setup.py develop

测试模板和接收者

c7n-mailer-replay入口点提供用于测试电子邮件通知和模板的帮助。此脚本操作云守护者自身的实际SQS消息，您可以从SQS队列检索或本地复制。默认情况下，它期望消息文件是base64编码、gzip压缩的JSON，就像c7n发送到SQS一样。使用-p或--plain参数，它将期望消息文件包含纯JSON。

c7n-mailer-replay有三个主要操作模式：

• 没有额外的参数，它将渲染消息所对应的策略指定的模板，并像c7n-mailer一样从本地机器发送邮件。这只适用于SES，不适用于SMTP。
• 使用-T或--template-print参数，它将记录将接收邮件的电子邮件地址，并将渲染的邮件正文模板打印到STDOUT。
• 使用-d或--dry-run参数，它将打印将发送的每个消息的实际电子邮件正文（包括标题），到STDOUT。

测试Azure模板

可以使用c7n-mailer-replay入口点使用以下任一参数测试Azure模板：

• -T或--template-print
• -d或--dry-run

在没有这些参数的情况下运行c7n-mailer-replay将引发错误，因为它将尝试授权AWS。

以下是一个用于检索用于测试模板的示例消息的示例：

• 运行具有通知操作的策略，提供要测试的模板名称，以填充队列。

• 使用azure cli，将消息保存在本地

$ az storage message get --queue-name <queuename> --account-name <storageaccountname> --query '[].content' > test_message.gz

• 可以使用以下方式将示例消息提供给c7n-mailer-replay：

$ c7n-mailer-replay test_message.gz -T --config mailer.yml