terravision

ТерраВижн

TerraVision — это инструмент CLI, который преобразует код Terraform в диаграммы профессиональной облачной архитектуры и решает проблему поддержания в актуальном состоянии самого важного документа в облачных проектах — документа архитектуры. Сейчас, когда высокоскоростные выпуски стали нормой, диаграммы архитектуры, сгенерированные машиной, являются более точными, чем полагаться на произвольную диаграмму, нарисованную облачным архитектором, которая больше не соответствует реальности. Terravision безопасно работает на 100% клиентской стороне без какой-либо зависимости от Terraform или доступа к вашей облачной среде, чтобы динамически анализировать ваши условно созданные ресурсы и переменные и генерировать автоматическое визуальное представление вашей архитектуры. Terravision задуман как инструмент «Документы как код» (DaC), который можно включить в ваш конвейер CI/CD для обновления диаграмм архитектуры после этапов конвейера сборки/тестирования/выпуска и дополнять вместе с ним другие генераторы документов, такие как readthedocs.io. В настоящее время он поддерживает AWS, а в ближайшее время — облако Google и Azure.

Поверните это...

в это...

Это программное обеспечение все еще находится на стадии альфа-тестирования, и код предоставляется на условиях «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ , явных или подразумеваемых. Используйте на свой страх и риск.

Преимущества Терравижн

1. Расходы
   • Сохранение лицензий на программное обеспечение Visio/Drawing — Terravision бесплатна и имеет открытый исходный код.
   • Не требует каких-либо затрат на развертывание облачных ресурсов, он работает мгновенно с вашего локального компьютера.
   • Регулярное обновление диаграмм, выравнивание, соединение точек и расположение значков — не лучшее использование затрат на персонал вашего архитектора.
2. Ускорение и автоматизация
   • Используйте файлы переменных TF в качестве входных данных для создания нескольких вариантов диаграмм из одного и того же кода TF.
   • Автоматизируйте создание архитектурных схем, запустив terravision как часть конвейеров CI/CD.
   • Диаграммы на основе YAML как код позволяют аннотировать сгенерированные диаграммы дополнительными пользовательскими метками и ресурсами, например неуправляемыми ресурсами или внешними системами, не отраженными в коде TF.
3. Согласованность во всей организации
   • Автоматически загружает ваши организационные/внешние модули, чтобы обеспечить новейшее представление последующих модулей Terraform.
   • Согласованный дизайн схем архитектуры с использованием стандартных значков и стиля, одобренного AWS/GCP/Azure для всех команд.
4. Точная видимость
   • Диаграмма состояния в реальном времени показывает текущую инфраструктуру, которая точно соответствует тому, что сегодня развернуто в производстве.
   • Помогает в сторонних обзорах архитектуры, аудите, мониторинге, составлении отчетов и отладке стека в визуальном виде.
   • Код пользовательской диаграммы и выходные изображения можно поместить в систему контроля версий/источников для улучшения удобства обслуживания и обнаружения.
5. Безопасность
   • Не нужно предоставлять доступ к вашей учетной записи AWS или CLI, чтобы нарисовать диаграмму.
   • Не создает навязчивые облачные ресурсы, например экземпляры сканирования или таблицы метаданных, которые предприятиям необходимо будет утвердить.
   • Весь исходный код остается в вашей локальной среде, диаграммы генерируются на ваших машинах без обращения к внешним API.

Установка и использование

Внешние зависимости для всех версий

• графвиз https://graphviz.org/download/
• git https://git-scm.com/downloads
• терраформ https://developer.hashicorp.com/terraform/downloads

Быстрый старт

1. Установите все внешние зависимости, как указано выше.
2. Клонируйте репозиторий git clone https://github.com/patrickchugh/terravision.git
3. Получите рабочий каталог (полный путь), выполнив cd terravision и выполнив pwd .
4. Добавьте папку terravision в значение PATH , например, export PATH=$PATH:/Users/<PATH TO TERRAVISION> чтобы вы могли запускать ее из любого места. <PATH TO TERRAVISION> будет результатом строки 3.
5. Установите требования Python cd terravision && pip install -r requirements.txt
6. Убедитесь, что ваш скрипт Python terravision исполняется с помощью chmod +x terravision
7. Запустите terravision и укажите исходные файлы Terraform в формате:

$ terravision draw --source ~ /src/my-terraform-code

Для стеков Terraform с рабочими пространствами вы можете использовать параметр --workspace :

$ terraform draw --source ~ /src/my-terraform-code --workspace development

Для исходного кода Terraform в репозитории Git вы также можете использовать форму:

$ terravision draw --source https://github.com/your-repo/terraform-examples.git

Используйте символ // для подпапок в репозиториях Git, если нужный вам код находится в иерархии папок.

$ terravision draw --source https://github.com/your-repo/terraform-examples.git//mysubfolder/secondfolder/

Аннотирование созданных диаграмм

Ни одна автоматически сгенерированная диаграмма не будет содержать всех необходимых вам деталей, в лучшем случае она позволит вам достичь цели на 80–90%. Чтобы добавить пользовательские аннотации, такие как заголовок основной диаграммы, дополнительные метки на стрелках или дополнительные ресурсы, созданные вне вашего Terraform, включите файл terravision.yml в папку исходного кода, и он будет загружен автоматически. Альтернативно, укажите путь к файлу аннотаций в качестве параметра terravision.

terravision --source https://github.com/your-repo/terraform-examples.git --annotate /Users/me/MyDocuments/annotations.yml

Файл .yml — это стандартный файл конфигурации YAML, аналогичный приведенному ниже примеру, с одним или несколькими заголовками, называемыми title , connect », disconnect , add , remove или update . Имена узлов соответствуют тем же соглашениям, что и имена ресурсов Terraform https://registry.terraform.io/providers/hashicorp/aws/latest/docs, и поддерживают подстановочные знаки. Вы можете добавить собственную метку к любому ресурсу TF, изменив атрибуты ресурса и добавив атрибут label (не существует в Terraform). Для линий/соединений вы можете изменить атрибуты ресурса, добавив специальные edge_labels terravision, чтобы добавить текст в линию соединения с конкретным узлом ресурса. См. пример ниже:

 format : 0.1
# Main Diagram heading
title : Serverless Wordpress Site
# Draw new connection lines that are not apparent from the Terraforms
connect :
  aws_rds_cluster.this :
    - aws_ssm_parameter.db_master_user : Retrieve credentials from SSM
# Remove connections between nodes that are currently shown
disconnect :
  # Wildcards mean these disconnections apply to any cloudwatch type resource called logs
  aws_cloudwatch*.logs :
    - aws_ecs_service.this
    - aws_ecs_cluster.this
# Delete the following nodes
remove :
  - aws_iam_role.task_execution_role
# Add the following nodes
add :
  aws_subnet.another_one :
    # Specify Terraform attributes for a resource like this 
    cidr_block : " 123.123.1.1 "
# Modify attributes of existing node
update :
  aws_ecs_service.this :
    # Add custom labels to the connection lines that already exist between ECS->RDS
    edge_labels :
      - aws_rds_cluster.this : Database Queries
  # Wildcards save you listing multiple resources of the same type. This edge label is added to all CF->ACM connections.
  aws_cloudfront* :
    edge_labels :
      - aws_acm_certificate.this : SSL Cert
 # Add a custom label to a resource node. Overrides default label
  aws_ecs_service.this :
   label : " My Custom Label "

Подробная помощь

Введите terravision --help , чтобы просмотреть полный список команд или получить помощь по конкретной команде.