terravision

TerraVisión

TerraVision es una herramienta CLI que convierte el código Terraform en diagramas profesionales de arquitectura en la nube y resuelve el problema de mantener actualizado el documento más importante en los proyectos en la nube, el documento de arquitectura. Ahora que los lanzamientos de alta velocidad son la norma, los diagramas de arquitectura generados por máquinas son más precisos que confiar en el diagrama de estilo libre dibujado por el arquitecto de la nube que ya no coincide con la realidad. Terravision se ejecuta de forma segura 100% del lado del cliente sin ninguna dependencia de Terraform o acceso a su entorno de nube, para analizar dinámicamente sus recursos y variables creados condicionalmente y generar una imagen automática de su arquitectura. Terravision está diseñado para ser una herramienta de 'Documentos como código' (DaC) que se puede incluir en su proceso de CI/CD para actualizar los diagramas de arquitectura después de las fases de compilación/prueba/lanzamiento y complementar otros generadores de documentos como readthedocs.io junto con él. Actualmente es compatible con AWS y pronto con la nube de Google y Azure.

Gira esto...

en esto...

Este software aún se encuentra en prueba alfa y el código se comparte "TAL CUAL", SIN GARANTÍAS NI CONDICIONES DE NINGÚN TIPO , ya sean expresas o implícitas. Úselo bajo su propio riesgo.

Beneficios de Terravisión

1. Costo
   • Guarde las licencias de software Visio/Drawing: Terravision es gratuito y de código abierto
   • No requiere ningún costo que incurra en recursos de la nube para activarse, funciona instantáneamente desde su máquina local
   • Actualizar periódicamente los diagramas, alinearlos, conectar puntos y distribuir los iconos no es el mejor uso de los costos de personal de su arquitecto.
2. Acelere y automatice
   • Utilice archivos de variables TF como entradas para crear múltiples diagramas de variantes a partir del mismo código TF
   • Automatice la creación de diagramas de arquitectura ejecutando terravision como parte de canalizaciones de CI/CD.
   • Los diagramas basados ​​en YAML como código le permiten anotar diagramas generados con etiquetas y recursos personalizados adicionales, por ejemplo, recursos no administrados o sistemas externos no capturados en el código TF.
3. Coherencia en toda la organización
   • Descarga automáticamente sus módulos organizativos/externos para garantizar la vista más reciente de los módulos Terraform posteriores.
   • Diseño coherente de diagramas de arquitectura utilizando íconos estándar de la industria y estilos aprobados por AWS/GCP/Azure en todos los equipos.
4. Visibilidad precisa
   • El estado en tiempo real del diagrama muestra la infraestructura actual que coincide exactamente con lo que se implementa en producción hoy
   • Ayuda en revisiones de arquitectura de terceros, auditoría, monitoreo, generación de informes y depuración de la pila de forma visual.
   • El código de diagrama personalizado y las imágenes de salida se pueden poner en control de fuente/versión para una mejor capacidad de mantenimiento y descubrimiento.
5. Seguridad
   • No es necesario que proporcione acceso a su cuenta de AWS o CLI para dibujar el diagrama.
   • No crea recursos intrusivos en la nube, por ejemplo, instancias de escaneo o tablas de metadatos que las empresas tendrían que aprobar.
   • Todo el código fuente permanece en su entorno local, los diagramas se generan en sus máquinas sin llamar a API externas.

Instalación y uso

Dependencias externas para todas las versiones

• Graphviz https://graphviz.org/download/
• Git https://git-scm.com/downloads
• terraforma https://developer.hashicorp.com/terraform/downloads

Inicio rápido

1. Instale todas las dependencias externas como se enumeran anteriormente
2. Clonar el repositorio git clone https://github.com/patrickchugh/terravision.git
3. Obtenga el directorio de trabajo (ruta completa) haciendo cd terravision y pwd .
4. Agregue la carpeta terravision a su valor PATH , por ejemplo, export PATH=$PATH:/Users/<PATH TO TERRAVISION> para que pueda ejecutarlo desde cualquier lugar. <PATH TO TERRAVISION> sería el resultado de la línea 3.
5. Instalar los requisitos de Python cd terravision && pip install -r requirements.txt
6. Asegúrese de que su script Python de Terravision sea ejecutable con chmod +x terravision
7. Ejecute terravision y especifique sus archivos fuente de Terraform en el formato:

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

Para pilas de Terraform con espacios de trabajo, puede utilizar el parámetro --workspace :

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

Para el código fuente de Terraform en un repositorio de Git también puedes usar el formulario:

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

Utilice el carácter // para las subcarpetas dentro de los repositorios de Git si el código que desea se encuentra en una jerarquía de carpetas.

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

Anotar diagramas generados

Ningún diagrama generado automáticamente tendrá todos los detalles que necesita; en el mejor de los casos, le llevará entre el 80 y el 90 % del camino. Para agregar anotaciones personalizadas, como el título de un diagrama principal, etiquetas adicionales en flechas o recursos adicionales creados fuera de Terraform, incluya un archivo terravision.yml en la carpeta del código fuente y se cargará automáticamente. Alternativamente, especifique una ruta al archivo de anotaciones como parámetro para terravision.

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

El archivo .yml es un archivo de configuración YAML estándar similar al ejemplo siguiente con uno o más encabezados llamados title , connect , disconnect , add , remove o update . Los nombres de los nodos siguen las mismas convenciones que los nombres de los recursos de Terraform https://registry.terraform.io/providers/hashicorp/aws/latest/docs y admiten comodines. Puede agregar una etiqueta personalizada a cualquier recurso TF modificando los atributos del recurso y agregando el atributo label (no existe en Terraform). Para líneas/conexiones, puede modificar los atributos de recursos agregando edge_labels específicas de terravision para agregar texto a la línea de conexión a un nodo de recurso específico. Vea el ejemplo a continuación:

 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 "

Ayuda detallada

Escriba terravision --help para obtener una lista completa de comandos o para obtener ayuda con un comando específico