Модуль community.aws.wafv2_web_acl — создание и удаление веб-ACL WAF

Примечание

Этот модуль входит в коллекцию community.aws (версия 10.1.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в состав ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install community.aws. Для использования этого модуля требуются дополнительные компоненты; подробности см. в разделе Требования.

Чтобы использовать его в плейбуке, укажите: community.aws.wafv2_web_acl.

Добавлено в community.aws 1.5.0

Краткое описание
Требования
Параметры
Примечания
Примеры
Возвращаемые значения

Краткое описание

Создание, изменение и удаление веб-ACL AWS WAF v2 (не для классического WAF).
Документация: https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html

Требования

Следующие требования должны быть выполнены на хосте, где запускается этот модуль.

python >= 3.6
boto3 >= 1.34.0
botocore >= 1.34.0

Параметры

Параметр	Комментарии
access_key псевдонимы: aws_access_key_id, aws_access_key строка	Идентификатор ключа доступа AWS. Дополнительные сведения о токенах доступа см. в документации AWS: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. Также можно использовать переменные окружения `AWS_ACCESS_KEY_ID` или `AWS_ACCESS_KEY` в порядке убывания приоритета. Параметры aws_access_key и profile нельзя использовать одновременно. Псевдоним aws_access_key_id добавлен в выпуске 5.1.0 для согласованности с AWS botocore SDK.
aws_ca_bundle путь	Путь к пакету сертификатов CA, используемому для проверки SSL-сертификатов. Также можно использовать переменную окружения `AWS_CA_BUNDLE`.
aws_config словарь	Словарь для изменения конфигурации botocore. Описание параметров см. в документации AWS: https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config.
cloudwatch_metrics логическое значение	Включить метрики CloudWatch для веб-ACL wafv2. Варианты: `false` `true` ← (по умолчанию)
custom_response_bodies словарь добавлено в community.aws 3.1.0	Сопоставление ключей пользовательских ответов с их содержимым. Определите здесь тела ответов и ссылайтесь на них в правилах, указывая ключ элемента словаря с телами ответов. Каждый элемент должен иметь уникальный ключ словаря, а сам элемент должен содержать два ключа: content_type и content.
debug_botocore_endpoint_logs логическое значение	Использовать регистратор `botocore.endpoint` для анализа уникальных (а не всех) вызовов API `"resource:action"`, выполняемых во время задачи, и выводить полученный набор в ключ resource_actions результатов задачи. Используйте callback `aws_resource_action`, чтобы вывести полный список вызовов, выполненных в ходе плейбука. Также можно использовать переменную окружения `ANSIBLE_DEBUG_BOTOCORE_LOGS`. Варианты: `false` ← (по умолчанию) `true`
default_action строка	Действие по умолчанию для веб-ACL wafv2. Варианты: `"Block"` `"Allow"`
description строка	Описание веб-ACL wafv2.
endpoint_url псевдонимы: aws_endpoint_url строка	URL для подключения вместо конечных точек AWS по умолчанию. Этот параметр можно использовать для подключения к другим совместимым с AWS сервисам, однако коллекции amazon.aws и community.aws тестируются только с AWS. Также можно использовать переменную окружения `AWS_URL`.
metric_name строка	Имя метрик CloudWatch. Если имя не задано, а параметр cloudwatch_metrics включен, будет использоваться имя самого веб-ACL.
name строка / обязательный	Имя веб-ACL.
profile псевдонимы: aws_profile строка	Именованный профиль AWS для аутентификации. Дополнительные сведения об именованных профилях см. в документации AWS: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html. Также можно использовать переменную окружения `AWS_PROFILE`. Параметр profile нельзя использовать одновременно с параметрами aws_access_key, aws_secret_key и session_token.
purge_rules логическое значение	Если задано значение `no`, существующие правила балансировщика нагрузки сохраняются. Правила будут изменены и добавлены, но не удалены. Варианты: `false` `true` ← (по умолчанию)
purge_tags логическое значение	Если задано значение `purge_tags=true` и задан параметр `tags`, существующие теги ресурса будут удалены, чтобы привести их в точное соответствие с тегами, заданными параметром `tags`. Если параметр `tags` не задан, теги не изменяются, даже если задано значение `purge_tags=True`. Ключи тегов, начинающиеся с `aws:`, зарезервированы Amazon и не могут быть изменены. Поэтому они игнорируются при обработке параметра `purge_tags`. Дополнительные сведения см. в документации Amazon: https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions. Варианты: `false` `true` ← (по умолчанию)
region псевдонимы: aws_region строка	Регион AWS для использования. Для глобальных сервисов, таких как IAM, Route53 и CloudFront, параметр region игнорируется. Также можно использовать переменную окружения `AWS_REGION`. Дополнительные сведения см. в документации Amazon AWS: http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region.
rules список / элементы=словарь	Правила, используемые для выявления веб-запросов, которые нужно разрешить, заблокировать или учесть. Список управляемых правил см. по ссылке https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-list.html.
action словарь	Определяет, будет ли правило блокировать запрос, разрешать его или учитывать.
name строка	Имя правила wafv2
priority целое число	Приоритет правила
statement словарь	Конфигурация правила.
visibility_config словарь	Настройки видимости отдельного правила wafv2.
sampled_requests логическое значение	Определяет, следует ли сохранять образец веб-запросов: true или false. Варианты: `false` ← (по умолчанию) `true`
scope строка / обязательный	Географическая область действия веб-ACL. Варианты: `"CLOUDFRONT"` `"REGIONAL"`
secret_key псевдонимы: aws_secret_access_key, aws_secret_key строка	Секретный ключ доступа AWS. Дополнительные сведения о токенах доступа см. в документации AWS: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. Также можно использовать переменные окружения `AWS_SECRET_ACCESS_KEY` или `AWS_SECRET_KEY` в порядке убывания приоритета. Параметры secret_key и profile нельзя использовать одновременно. Псевдоним aws_secret_access_key добавлен в выпуске 5.1.0 для согласованности с AWS botocore SDK.
session_token псевдонимы: aws_session_token строка	Токен сеанса AWS STS для использования с временными учетными данными. Дополнительные сведения о токенах доступа см. в документации AWS: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. Также можно использовать переменную окружения `AWS_SESSION_TOKEN`. Параметры session_token и profile нельзя использовать одновременно.
state строка / обязательный	Определяет, должно ли правило присутствовать или отсутствовать. Варианты: `"present"` `"absent"`
tags псевдонимы: resource_tags словарь	Словарь с тегами, применяемыми к ресурсу. Если параметр `tags` не задан, теги не изменяются.
validate_certs логическое значение	Если задано значение `false`, SSL-сертификаты при взаимодействии с API AWS проверяться не будут. Настоятельно не рекомендуется устанавливать validate_certs=false; вместо этого рассмотрите возможность использования параметра aws_ca_bundle. Варианты: `false` `true` ← (по умолчанию)

Примечания

Примечание

Поддержка параметра purge_tags добавлена в выпуске 4.0.0.
Внимание: Для модулей переменные окружения и файлы конфигурации считываются в контексте «хоста» Ansible, а не в контексте «контроллера». Поэтому файлы может потребоваться явно скопировать на «хост». Для плагинов поиска и подключения переменные окружения и файлы конфигурации считываются в контексте «контроллера» Ansible, а не «хоста».
Используемый Ansible AWS SDK (boto3) также может считывать значения учетных данных и других параметров по умолчанию, например региона, из файлов конфигурации в контексте «хоста» Ansible (обычно ~/.aws/credentials). Дополнительные сведения см. по ссылке https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html.

Примеры

- name: Create test web acl
  community.aws.wafv2_web_acl:
    name: test05
    description: hallo eins
    scope: REGIONAL
    default_action: Allow
    sampled_requests: false
    cloudwatch_metrics: true
    metric_name: test05-acl-metric
    rules:
      - name: zwei
        priority: 0
        action:
          block: {}
        visibility_config:
          sampled_requests_enabled: true
          cloud_watch_metrics_enabled: true
          metric_name: ddos
        statement:
          xss_match_statement:
            field_to_match:
              body: {}
            text_transformations:
              - type: NONE
                priority: 0
      - name: admin_protect
        priority: 1
        override_action:
          none: {}
        visibility_config:
          sampled_requests_enabled: true
          cloud_watch_metrics_enabled: true
          metric_name: fsd
        statement:
          managed_rule_group_statement:
            vendor_name: AWS
            name: AWSManagedRulesAdminProtectionRuleSet

      # AWS Managed Bad Input Rule Set
      # but allow PROPFIND_METHOD used e.g. by webdav
      - name: bad_input_protect_whitelist_webdav
        priority: 2
        override_action:
          none: {}
        visibility_config:
          sampled_requests_enabled: true
          cloud_watch_metrics_enabled: true
          metric_name: bad_input_protect
        statement:
          managed_rule_group_statement:
            vendor_name: AWS
            name: AWSManagedRulesKnownBadInputsRuleSet
            excluded_rules:
              - name: PROPFIND_METHOD

      # Rate Limit example. 1500 req/5min
      # counted for two domains via or_statement. login.mydomain.tld and api.mydomain.tld
      - name: rate_limit_example
        priority: 3
        action:
          block: {}
        visibility_config:
          sampled_requests_enabled: true
          cloud_watch_metrics_enabled: true
          metric_name: mydomain-ratelimit
        statement:
          rate_based_statement:
            limit: 1500
            aggregate_key_type: IP
            scope_down_statement:
              or_statement:
                statements:
                  - byte_match_statement:
                      search_string: login.mydomain.tld
                      positional_constraint: CONTAINS
                      field_to_match:
                        single_header:
                          name: host
                      text_transformations:
                        - type: LOWERCASE
                          priority: 0
                  - byte_match_dtatement:
                      search_string: api.mydomain.tld
                      positional_constraint: CONTAINS
                      field_to_match:
                        single_header:
                          name: host
                      text_transformations:
                        - type: LOWERCASE
                          priority: 0
    purge_rules: true
    tags:
      A: B
      C: D
    state: present

- name: Create IP filtering web ACL
  community.aws.wafv2_web_acl:
    name: ip-filtering-traffic
    description: ACL that filters web traffic based on rate limits and whitelists some IPs
    scope: REGIONAL
    default_action: Allow
    sampled_requests: true
    cloudwatch_metrics: true
    metric_name: ip-filtering-traffic
    rules:
      - name: whitelist-own-IPs
        priority: 0
        action:
          allow: {}
        statement:
          ip_set_reference_statement:
            arn: 'arn:aws:wafv2:us-east-1:123456789012:regional/ipset/own-public-ips/1c4bdfc4-0f77-3b23-5222-123123123'
        visibility_config:
          sampled_requests_enabled: true
          cloud_watch_metrics_enabled: true
          metric_name: waf-acl-rule-whitelist-own-IPs
      - name: rate-limit-per-IP
        priority: 1
        action:
          block:
            custom_response:
              response_code: 429
              custom_response_body_key: too_many_requests
        statement:
          rate_based_statement:
            limit: 5000
            aggregate_key_type: IP
        visibility_config:
          sampled_requests_enabled: true
          cloud_watch_metrics_enabled: true
          metric_name: waf-acl-rule-rate-limit-per-IP
        purge_rules: true
    custom_response_bodies:
      too_many_requests:
        content_type: APPLICATION_JSON
        content: '{ message: "Your request has been blocked due to too many HTTP requests coming from your IP" }'
    region: us-east-1
    state: present

Возвращаемые значения

Общие возвращаемые значения описаны здесь. Ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
arn строка	ARN веб-ACL Возвращается: Всегда, если веб-ACL существует Пример: `"arn:aws:wafv2:eu-central-1:123456789012:regional/webacl/test05/318c1ab9-fa74-4b3b-a974-f92e25106f61"`
capacity целое число	Текущая емкость веб-ACL Возвращается: Всегда, если веб-ACL существует Пример: `140`
custom_response_bodies словарь	Конфигурации пользовательских тел ответов, используемых в правилах Возвращается: Всегда, если веб-ACL существует Пример: `{"too_many_requests": {"content": "{ message: \"Your request has been blocked due to too many HTTP requests coming from your IP\" }", "content_type": "APPLICATION_JSON"}}`
default_action словарь	Действие ACL по умолчанию Возвращается: Всегда, если веб-ACL существует Пример: `{"allow": {}}`
description строка	Описание веб-ACL Возвращается: Всегда, если веб-ACL существует Пример: `"Some web acl description"`
name строка	Имя веб-ACL Возвращается: Всегда, если веб-ACL существует Пример: `"test02"`
rules список / элементы=строка	Текущие правила веб-ACL Возвращается: Всегда, если веб-ACL существует Пример: `[{"name": "admin_protect", "override_action": {"none": {}}, "priority": 1, "statement": {"managed_rule_group_statement": {"name": "AWSManagedRulesAdminProtectionRuleSet", "vendor_name": "AWS"}}, "visibility_config": {"cloud_watch_metrics_enabled": true, "metric_name": "admin_protect", "sampled_requests_enabled": true}}]`
visibility_config словарь	Конфигурация видимости веб-ACL Возвращается: Всегда, если веб-ACL существует Пример: `{"cloud_watch_metrics_enabled": true, "metric_name": "blub", "sampled_requests_enabled": false}`

Авторы

Markus Bergholz (@markuman)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/aws/wafv2_web_acl_module.html