Automatyzacja tworzenia diagramów infrastruktury.

Tworzenie diagramów swojej przyszłej infrastruktury to dobry koncept. Pozwala zwizualizować wygląd naszej infrastruktury oraz łatwiej rozplanować kod gdy nasze konfiguracje w cloud powstają na przykład w terraform.

Jednak jak to czesto bywa na etapie pisania kodu czy walidacji kosztów plany naszej konfiguracji się zmieniają - a szkielety infrastruktury w formie (rysunku) pozostają w niezmienionej formie lub z tylko nie wielkimi poprawkami. A co gdyby ten proces zautomtyzować - i dostarczyć gotową dokumentacje wizualną wraz z implementacją naszej infrastruktury?

Narzędzie TerraVision

Terravision to narzędzie wiersza poleceń (CLI), które konwertuje kod Terraform na dynamiczne, profesjonalne diagramy architektury chmury. Głównym celem Terravision jest utrzymanie aktualności najważniejszego dokumentu w projektach chmurowych - dokumentu architektury. W dobie szybkich wydań, automatycznie generowane diagramy architektury są bardziej precyzyjne niż ręcznie rysowane przez architekta chmury, które mogą już nie odzwierciedlać rzeczywistości.

Terravision działa w 100% po stronie klienta, bez zależności od Terraform lub dostępu do środowiska chmurowego. Narzędzie to dynamicznie analizuje warunkowo tworzone zasoby i zmienne, generując automatyczny wizualny obraz architektury. Jest zaprojektowane jako narzędzie 'Docs as Code' (DaC), które można włączyć do pipeline'u CI/CD, aby aktualizować diagramy architektury po fazach budowania, testowania i wdrażania.

W prosty sposób jak to jest przedstawione w repozytorium kodu. To czyli nasz kod

w bardzo prosty sposób i szybki możemy zamienić na diagram

Zalety Terravision

1. Koszt

   1. Oszczędność na licencjach oprogramowania do tworzenia diagramów/rysunków - Terravision jest darmowe i open source

   2. Nie wymaga korzystania z zasobów chmury obciążających kosztami, działa natychmiastowo na lokalnej maszynie

   3. Regularna aktualizacja diagramów, łączenie punktów i rozmieszczanie ikon nie jest najlepszym wykorzystaniem kosztów pracowników architektury

2. Przyspieszenie i automatyzacja

   1. Użyj plików zmiennych TF jako danych wejściowych do tworzenia wielu wariantów diagramów z tego samego kodu TF

   2. Automatyzuj tworzenie diagramów architektury, uruchamiając terravision jako część potoków CI/CD

   3. Diagramy oparte na YAML jako kod pozwalają na dodawanie do wygenerowanych diagramów dodatkowych niestandardowych etykiet i zasobów, np. zasobów niezarządzanych lub zewnętrznych systemów nieuchwyconych w kodzie TF

3. Spójność w całej organizacji

   1. Automatyczne pobieranie modułów organizacyjnych / zewnętrznych, aby zapewnić najnowszy widok modułów Terraform

   2. Spójny projekt diagramów architektury z użyciem standardowych ikon branżowych i zatwierdzonego stylu AWS/GCP/Azure w zespołach

4. Dokładna widoczność

   1. Diagram w czasie rzeczywistym pokazuje aktualną infrastrukturę, która dokładnie odpowiada temu, co jest wdrożone w produkcji dzisiaj

   2. Pomoc w przeglądach architektury stron trzecich, audytach, monitoringu, raportowaniu i debugowaniu stosu w sposób wizualny

   3. Kod diagramu niestandardowego i obrazy wyjściowe mogą być umieszczane w kontroli źródła/wersji dla lepszej utrzymania i odkrywalności

5. Bezpieczeństwo

   1. Nie trzeba dawać dostępu do konta AWS lub CLI, aby rysować diagram Nie tworzy intruzywnych zasobów chmury, np. instancji skanujących lub tabel metadanych, które przedsiębiorstwa musiałyby zatwierdzić

   2. Cały kod źródłowy pozostaje w lokalnym środowisku, diagramy są generowane na twoich maszynach bez wywoływania zewnętrznych API

Instalacja i Użycie

Zależności dla wszystkich wersji

• graphviz https://graphviz.org/download/

• git https://git-scm.com/downloads

Szybki start

1. Zainstaluj wszystkie zależności, jak wyżej wymieniono.

2. Sklonuj repozytorium: git clone https://github.com/patrickchugh/terravision.git.

3. Uzyskaj pełną ścieżkę do katalogu roboczego, wykonując cd terravision i pwd.

4. Dodaj folder terravision do swojej zmiennej PATH, np. export PATH=$PATH:/Users/<ŚCIEŻKA DO TERRAFORM>, aby móc uruchamiać go z dowolnego miejsca. <ŚCIEŻKA DO TERRAFORM> to wynik z punktu 3.

5. Zainstaluj wymagane biblioteki Pythona: cd terravision && pip install -r requirements.txt.

6. Upewnij się, że skrypt pythonowy terravision jest wykonywalny: chmod +x terravision.

7. Uruchom terravision, określając pliki źródłowe Terraform w formacie:

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

Dla kodu źródłowego Terraform w repozytorium Git, można również użyć formy:

$ terravision draw --source https://github.com/twoje-repozytorium/terraform-examples.git

Użyj znaku // dla podfolderów w repozytoriach Git, jeśli kod, który chcesz, znajduje się pod hierarchią folderów.

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

Przykładowe Terraformy do wypróbowania

Nie związane z moim projektem, ale oto kilka przykładów Terraform od osób trzecich do wypróbowania:

terravision draw --source https://github.com/futurice/terraform-examples.git//aws/aws_static_site --varfile examples/variables.tfvars --show
terravision draw --source https://github.com/futurice/terraform-examples.git//aws/wordpress_fargate --varfile examples/variables.tfvars --show
terravision draw --source https://github.com/k-mitevski/terraform-k8s.git//01_terraform_eks --show

Annotowanie wygenerowanych diagramów

Żaden automatycznie wygenerowany diagram nie będzie miał wszystkich potrzebnych szczegółów, w najlepszym przypadku dostarczy 80-90% potrzebnych informacji. Aby dodać niestandardowe adnotacje, takie jak główny tytuł diagramu, dodatkowe etykiety na strzałkach lub dodatkowe zasoby utworzone poza Terraform, dołącz plik architecture.yml w folderze kodu źródłowego, a zostanie on automatycznie załadowany. Alternatywnie, określ ścieżkę do pliku z adnotacjami jako parametr dla terravision.

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

Plik .yml to standardowy plik konfiguracyjny YAML, podobny do poniższego przykładu, z jednym lub więcej nagłówkami takimi jak title, connect, disconnect, add, remove lub update. Nazwy węzłów odpowiadają konwencjom nazw zasobów Terraform https://registry.terraform.io/providers/hashicorp/aws/latest/docs i obsługują znaki wieloznaczne. Możesz dodać niestandardową etykietę do dowolnego zasobu TF, modyfikując atrybuty zasobu i dodając atrybut label (nieistniejący w Terraform). Dla linii/połączeń możesz modyfikować atrybuty zasobu, dodając specyficzne dla terravision edge_labels, aby dodać tekst do linii połączenia z konkretnym węzłem zasobu. Zobacz poniższy przykład:

format: 0.1# Main Diagram headingtitle: Serverless Wordpress Site# Draw new connection lines that are not apparent from the Terraformsconnect:
  aws_rds_cluster.this:
    - aws_ssm_parameter.db_master_user : Retrieve credentials from SSM# Remove connections between nodes that are currently showndisconnect:
  # Wildcards mean these disconnections apply to any cloudwatch type resource called logsaws_cloudwatch*.logs:
    - aws_ecs_service.this
    - aws_ecs_cluster.this# Delete the following nodesremove:
  - aws_iam_role.task_execution_role# Add the following nodesadd:
  aws_subnet.another_one :
    # Specify Terraform attributes for a resource like this cidr_block: "123.123.1.1"# Modify attributes of existing nodeupdate:
  aws_ecs_service.this:
    # Add custom labels to the connection lines that already exist between ECS->RDSedge_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 labelaws_ecs_service.this :
   label: "My Custom Label"

Oczywiście więcej można znaleść na stronie projektu: https://github.com/patrickchugh/terravision