Как желание генерировать код из файлов спецификации CloudFormation, привел к аудиту документов AWS с помощью Python и GitHub действий
Примечание: Этот пост расширяет некоторые контенты, ранее упомянутые в Сокращение документов, чтобы генерировать помощь PowerShell в Vaporshell , но не нужно читать, чтобы понять, что здесь происходит.
«Это выглядит круто».
Когда я впервые увидел Файлы спецификации ресурсов AWS CloudFormation Files В 2016 или 2017 году, представляя услуги, поддерживаемые CFN, я предполагал, что они будут полезны для инфракодеров. Я люблю создавать и улучшать инструменты автоматизации. Как еще можно не отставать от количества новых услуг, поддерживаемых AWS CloudFormation?
Мне было любопытно, как был сгенерирован код для наборов разработки, которые помогали в создании шаблонов CFN, таких как Sparkleformation , Тропосфера , вероятно, AWS Cloud Development Kit и Параслет .
Я снова вернул эту идею в недавнем посте, и это привело к списку пробелов, которые я хотел создать инструменты.
Некоторые мысли о документации AWS CloudFormation
Документация AWS, кажется, не синхронизирована во многих местах, когда дело доходит до:
- Какие услуги AWS поддерживаются в каждом регионе
- Какие сервисы AWS поддерживаются AWS CloudFormation в каждом регионе
Вместо этого он существует через спектр источников, которые иногда могут противоречить друг другу:
- AWS Region Table
- AWS Service Pricing (который может перечислять только стоимость обслуживания, а не доступность региона)
- Файлы спецификации ресурсов AWS CFN
- AWS объявления (Ex. Документация AWS (Ex. «… Следующие регионы поддерживаются для этой услуги …» )
Решения для этого были оставлены людьми, чтобы создать свой собственный источник истины, который быстро падает без автоматизации. В будущем я могу сделать дополнительные инструменты, которые соскребают дополнительные страницы, и попытаться создать целевые страницы с одним консенсусом, которые включают, где страницы противоречат.
Другое дело: источник документации AWS для руководства пользователя AWS CloudFormation, на GitHub , не так много Источник Как это дублирование из Live CFN Руководство пользователя И источник выглядит вручную, когда вручную обновляется непоследовательно. Это приводит к тому, что источник документации не отражает документацию, которая является живой, и также надеется оставить путаницу в отношении того, как подходить к PRS к дублированной документации источника:
- В настоящее время есть> 90 PRS
- Объединенные изменения делают «источник» на GitHub еще дальше от синхронизации от Live Docs, поскольку он уже не отражает живую/публичную документацию, для которой она является «источником». Управление этим вручную должно быть головной болью
- Иногда в репозитории источника GitHub не существует документации для ресурса или типа свойства. Это может иметь место, даже если документация существует на живом веб -сайте.
- PR обычно закрыты, без слияния, после того, как правопреемник упоминает, что билет был сделан внутри, чтобы внести исправление в файлы спецификации ресурсов. Это делается из-за кусков документации по руководству пользователя, сгенерируемой из файлов Spec.
Эти файлы спецификации не отслеживаются на GitHub AWS, однако они являются JSON и используются для автоматического генерации больших частей руководства пользователя AWS CFN (и сторонним инструментами, сделанными для оказания помощи в создании/подкладке для шаблонов CFN/и т. Д.). Что делать?
Спецификация ресурсов аудитор
Я сделал свой собственный репозиторий для отслеживания и аудирования этих файлов спецификации в то же время: AWS AWS CloudFormation Specization Auditor Анкет
Это привело к автоматизации всего с помощью Действия GitHub Анкет Я подписался на бета -версию и теперь использую действия GitHub с помощью сценариев Python для:
- Ищите новые обновления спецификаций CFN и загрузить/push to Repo, если обнаружено
- Каталог, какие регионы поддерживаются для каждой услуги в CFN
- Аудиторские ссылки на документацию и руководство пользователя AWS CFN Source Repo для согласованности
- Какие ссылки нарушены ссылки?
- Какая документация существует на веб -сайте документации в прямом эфире, но не источник GitHub для документации CFN?
Реализация
Действия GitHub в бета , и я столкнулся только с одной ошибкой, когда задание выглядит застрявшей в цикле выполнения рабочего процесса без вывода консоли или способа ее закрыть. Я открыл билет на поддержку с GitHub, и они вернулись ко мне о том, что это известная ошибка, где рабочие процессы, кажется, повешены, но на самом деле ничего не происходит (?). На сегодняшний день я ранее запускал рабочие процессы, которые показывают, что они не перестали выполнять.
Чтобы обойти это, мне пришлось переименовать и протолкнуть новый файл рабочего процесса YAML. По сути, это создает новый рабочий процесс GitHub Actions под новым именем, что позволяет выполнять новые прогоны без в зависимости от завершения подвешенного рабочего процесса.
Чтобы получить такой хороший выход для рабочего процесса, как выглядит рабочий процесс YAML?
Для действий GitHub ваши рабочие процессы должны существовать в следующем месте: .github/Workflow/myworkflow.yml
Я использовал по умолчанию для повседневного запланированного рабочего процесса приложения Python и модифицирован для работы с Pipenv и мои сценарии аудита на питоне:
name: CFN Specification and User Guide Audit
on:
schedule:
- cron: 0 2 * * 1-5
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: Set up Python 3.7
uses: actions/setup-python@v1
with:
python-version: 3.7
- name: Install dependencies
run: |
python -m pip install --upgrade pip setuptools
git submodule update --init --recursive --remote
pip install pipenv
pipenv install --dev
- name: Lint with flake8
run: |
# stop the build if there are Python syntax errors or undefined names
pipenv run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
pipenv run flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
- name: Look for and update new CFN specs if found
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
run: |
pipenv run python tools/cfn-resource-list.py
- name: Audit documentation links and cfn user guide
run: |
pipenv run python tools/cfn-supported-region-generator.py
- name: Create pull request if any files were updated
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
pipenv run python tools/create-pull-request.py
Как видно выше, действия GitHub позволяют получить доступ к секретам, которые можно хранить в настройках репозитория на GitHub:
Я видел много примеров и учебных пособий в Интернете, которые предпочитают использовать Amazons3readonlyaccess Политика, когда речь заходит о предоставлении доступа к публичным ведра S3, что выглядит так:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": "*"
}
]
}
Не делай этого.
Это позволяет любому, кто использует политику для перечисления/загрузки Что угодно Хранится в S3 и на вашем собственном аккаунте, если только политики, специфичные для конкретного ведра, в дополнение к возможности получить доступ к публичным ведра S3, принадлежащие другими учетными записями AWS.
Лучшая практика — пойти с самым явным, ограниченным маршрутом. Поскольку я знаю, к каким общественным ведрах я хочу получить доступ, политика выглядит так:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": [
"arn:aws:s3:::cfn-resource-specifications-us-east-1-prod",
"arn:aws:s3:::cfn-resource-specifications-us-east-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-eu-north-1-prod",
"arn:aws:s3:::cfn-resource-specifications-eu-north-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-ap-south-1-prod",
"arn:aws:s3:::cfn-resource-specifications-ap-south-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-eu-west-3-prod",
"arn:aws:s3:::cfn-resource-specifications-eu-west-3-prod/*",
"arn:aws:s3:::cfn-resource-specifications-eu-west-2-prod",
"arn:aws:s3:::cfn-resource-specifications-eu-west-2-prod/*",
"arn:aws:s3:::cfn-resource-specifications-eu-west-1-prod",
"arn:aws:s3:::cfn-resource-specifications-eu-west-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-ap-northeast-3-prod",
"arn:aws:s3:::cfn-resource-specifications-ap-northeast-3-prod/*",
"arn:aws:s3:::cfn-resource-specifications-ap-northeast-2-prod",
"arn:aws:s3:::cfn-resource-specifications-ap-northeast-2-prod/*",
"arn:aws:s3:::cfn-resource-specifications-ap-northeast-1-prod",
"arn:aws:s3:::cfn-resource-specifications-ap-northeast-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-sa-east-1-prod",
"arn:aws:s3:::cfn-resource-specifications-sa-east-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-ca-central-1-prod",
"arn:aws:s3:::cfn-resource-specifications-ca-central-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-ap-southeast-2-prod",
"arn:aws:s3:::cfn-resource-specifications-ap-southeast-2-prod/*",
"arn:aws:s3:::cfn-resource-specifications-ap-southeast-1-prod",
"arn:aws:s3:::cfn-resource-specifications-ap-southeast-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-eu-central-1-prod",
"arn:aws:s3:::cfn-resource-specifications-eu-central-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-us-east-2-prod",
"arn:aws:s3:::cfn-resource-specifications-us-east-2-prod/*",
"arn:aws:s3:::cfn-resource-specifications-us-west-1-prod",
"arn:aws:s3:::cfn-resource-specifications-us-west-1-prod/*",
"arn:aws:s3:::cfn-resource-specifications-us-west-2-prod",
"arn:aws:s3:::cfn-resource-specifications-us-west-2-prod/*"
]
}
]
}
Будущее
AWS AWS CloudFormation Specization Auditor должен продолжать обновлять себя сверхурочно, и полученные файлы JSON могут быть полезны для людей, желающих легко увидеть:
- Какие ресурсы поддерживаются в каких регионах облачной информации?
- Какие ссылки на документацию нарушены в файлах спецификации ресурсов CFN, предоставленных AWS?
- Какие ресурсы, если таковые имеются, упоминаются в других файлах спецификации за пределами
US-EAST-1Анкет Некоторые инструменты зависят отUS-EAST-1Специальный файл в качестве основного исходного файла, хотя мой инструмент обнаружил ошибки, где определенные поддерживаемые ресурсы не были включены (когда они были поддержаны)
Я буду продолжать расширять его, когда сталкиваюсь с большим количеством проблем.
Бонусные мысли
Я подумал, что хорошая функция для документации пользователя AWS CFN будет состоит в том, чтобы перечислить все поддерживаемые регионы в документации для каждого ресурса и типа свойств, поэтому я создал следующее в качестве пиара для Hacktoberfest :
- Выпуск GitHub: Включите поддерживаемые регионы для PropertyTypes и ResourceTypes
- GitHub PR: Добавление поддерживаемых регионов ко всем документам на основе включения файла CFN Spec
Присоединяйтесь к разговорам о них, если они кажутся стоящими или могут использовать некоторые отзывы!
Окончательные примечания
Хотите помочь улучшить свой рабочий процесс шаблона CloudFormation? Взгляни на:
- CFN-Python-Lint (Установите свои шаблоны CFN; инструмент включает в себя проверки с конкретными регионами!)
- AWS CDK : Используйте официальные инструменты Amazon для создания шаблонов CFN через ваш любимый язык кодирования вместо Raw Json/Yaml
- Проект AWS CDK и CFN-Python-Lint имеет подзаконные зареагии, которые использовались для патчей на лете против базовых файлов спецификации CFN и являются хорошими местами, на которых можно следить за созданием CFN-SPEC рабочих процессов (или если только столкнуться с проблемами):
- AWS CDK Spec Source — кричать Ян Маккей ( github / Twitter ) за то, чтобы показать мне это!
- CFN Python Lint: ExtendEdSpecs — кричать Пэт Мирон ( github ) за то, что показано мне!
Первоначально опубликовано в https://icanteven.io 18 октября, 2019
Оригинал: «https://dev.to/scriptautomate/aws-cloudformation-resource-specification-auditor-26g»