Terraform jest potężnym (jeśli nie najpotężniejszym) i jednym z najczęściej używanych narzędzi, który umożliwia zarządzanie infrastrukturą jako kodem. Pozwala programistom_ką rozwiązywać wiele różnych problemów infrastrukturalnych tak, aby dało się to dalej łatwo wspierać, integrować i rozwijać.

Niektóre informacje opisane w tej książce mogą wydawać się nieoptymalnymi praktykami. Jestem tego świadom. Czasem zachodzi potrzeba pomocy czytelnikom_czkom w oddzieleniu tego, co jest powszechnie znanymi najlepszymi praktykami, a co jest po prostu kolejnym subiektywnym sposobem robienia rzeczy. Używam wtedy wskazówek, aby zapewnić kontekst oraz ikony, które określają poziom trudności w każdej podsekcji dotyczącej najlepszych praktyk.

Kilka lat później został on zaktualizowany o najnowsze zalecane praktyki dostępne w Terraform 1.0. Ostatecznie — ta książka powinna zawierać większość praktyk i zaleceń dla użytkowników Terraform, które można uznać za bezdyskusyjnie najlepsze.

Sponsorowanie

Tłumaczenia

Wsparcie i współpraca

Zawsze chętnie usłyszę wasze opinie i zaktualizuje tę książkę. Społeczność ciągle dojrzewa, a nowe pomysły są weryfikowane i wdrażane.

Autorzy_ki

Licencja

Ta praca jest objęta licencją Apache 2. Zobacz LICENSE, aby uzyskać szczegółowe informacje.

Autorzy_rki __ i __ współtwórcy_czynie treści nie mogą zagwarantować aktualności oraz poprawności informacji tutaj znalezionych. Upewnij się, że rozumiesz, iż informacje podane tutaj są dostarczane dobrowolnie i że między Tobą a jakimikolwiek osobami związanymi z tą treścią lub projektem nie powstaje żadna umowa ani kontrakt. Autorzy_rki __ i __ współtwórcy_czynie nie przyjmują i niniejszym zrzekają się jakiejkolwiek odpowiedzialności wobec jakiejkolwiek strony za jakiekolwiek straty, szkody, lub zakłócenia spowodowane błędami, lub pominięciami w informacjach zawartych w tych treściach, powiązanych z nimi lub z nimi połączonych, niezależnie od tego, czy takie błędy lub pominięcia wynikają z zaniedbania, wypadku lub jakiejkolwiek innej przyczyny.

Prawa autorskie © 2018-2023 Anton Babenko.

Pytania dotyczące struktury kodu są zdecydowanie najczęściej zadawanymi w społeczności Terraform. W pewnym momencie każdy zaczyna się zastanawiać co dla projektu będzie najlepsze.

Jak powinienem uporządkować moje konfiguracje Terraform?

To jedno z pytań, na które jest wiele odpowiedzi, lecz bardzo trudno jest udzielić uniwersalnych porad, więc postarajmy się zacząć od zrozumienia z czym mamy do czynienia.

• Jaka jest złożoność Twojego projektu?

  • Liczba powiązanych zasobów

  • Liczba użytych dostawców Terraform (uwaga — patrz poniżej na temat „dostawców logicznych” (logical providers))

• Jak często zmienia się Twoja infrastruktura?

  • Zaczynając od raz w miesiącu/tygodniu/codziennie

  • Skończywszy na ciągłym (za każdym razem, gdy pojawia się nowa zmiana (commit))

• Kto lub co zmienia kod? Czy pozwalasz serwerowi CI aktualizować repozytorium po zbudowaniu nowego artefaktu?

  • Tylko programiści mogą wysyłać kod do repozytorium infrastruktury

  • Każdy może proponować zmiany, otwierając pull-requesty (w tym automatyczne zadania uruchomione na serwerze CI)

• Z jakiej platformy lub usługi wdrożeniowej korzystasz?

  • AWS CodeDeploy, Kubernetes czy OpenShift wymagają nieco innych podejść

• Jak grupowane są środowiska?

  • Według środowiska, regionu, projektu

Rozpoczęcie pracy z odpowiednim podejściem do struktury projektu w Terraform

Umieszczenie całego kodu w pliku main.tf jest dobrym pomysłem, jeśli dopiero zaczynasz swoją przygodę z Terraform lub piszesz testowy kod, aby coś zweryfikować. We wszystkich innych przypadkach lepiej będzie mieć kilka plików podzielonych logicznie w następujący sposób:

• main.tf — wywoływanie modułów, zmienny lokalnych i źródeł danych w celu utworzenia wszystkich zasobów

• variables.tf — zawiera deklaracje zmiennych używanych w main.tf

• outputs.tf — zawiera dane wyjściowe z zasobów utworzonych w main.tf

• versions.tf — zawiera wymagania dotyczące wersji dla Terraform i dostawców

Jak myśleć o strukturze konfiguracji Terraform?

Popularne wskazówki dotyczące strukturyzowania kodu

• Łatwiej i szybciej pracuje się z mniejszą liczbą zasobów

  • komendy terraform plan i terraform apply wykonują wywołania API, aby zweryfikować status zasobów

  • Jeśli masz całą infrastrukturę w jednej kompozycji, może to zająć trochę czasu

• Promień rażenia jest mniejszy przy mniejszej ilości zasobów

  • Odizolowanie od siebie niepowiązanych zasobów poprzez umieszczenie ich w oddzielnych kompozycjach zmniejsza ryzyko, jeśli coś pójdzie nie tak

• Rozpocznij swój projekt od użycia stanu zdalnego (remote state), ponieważ:

  • Twój laptop nie jest odpowiednim miejscem na źródło prawdy (source of truth) o Twojej infrastrukturze

  • Zarządzanie plikiem tfstate w repozytorium git to koszmar

  • Później, gdy warstwy infrastruktury zaczną rosnąć w wielu kierunkach (liczba zależności lub zasobów) łatwiej będzie mieć wszystko pod kontrolą

• Ćwicz pisanie spójnej struktury i praktykuj zachowywanie konwencji nazewnictwa:

  • Podobnie jak przy kodzie proceduralnym, kod Terraform powinien być napisany tak, aby w pierwszej kolejności mogli go przeczytać ludzie. Zachowanie porządku pomoże, kiedy trzeba będzie wrócić do zmian sprzed pół roku.

  • Przenoszenie zasobów w pliku stanu Terraform jest możliwe, ale może to być trudniejsze, jeśli masz niespójną strukturę i nazewnictwo

• Zachowaj moduły zasobów tak proste, jak to możliwe

• Nie "hardkoduj" wartości, które mogą być przekazywane jako zmienne lub uzyskane przy użyciu źródeł danych

• Użyj źródeł danych i terraform_remote_state jako łącznika między modułami infrastruktury w kompozycji

W tej książce przykładowe projekty są pogrupowane według złożoności — od małych do bardzo dużych infrastruktur. Ten podział nie jest ścisły, więc sprawdź, jak robią to inni.

Orkiestracja modułów i kompozycji infrastruktury

Posiadanie małej infrastruktury oznacza, że istnieje niewielka liczba zależności i niewiele zasobów. Wraz z rozwojem projektu pojawia się potrzeba łączenia wykonywania konfiguracji Terraform. Łączenia różnych modułów infrastruktury i przekazywanie wartości w ramach kompozycji staje się oczywistym następstwem.

Istnieje co najmniej 5 odrębnych grup rozwiązań do orkiestracji, z których korzystają programiści_stki:

1. Czysty Terraform. Bardzo proste rozwiązanie. Programiści_stki muszą znać tylko Terraform, aby wykonać zadanie.

2. Terragrunt. Narzędzie, którego można użyć do orkiestracji całej infrastruktury, a także obsługi zależności. Terragrunt działa natywnie z modułami infrastruktury i kompozycjami, dzięki czemu ogranicza powielanie kodu.

3. Skrypty wewnętrzne. Często używane jako punkt startowy do używania orkiestracji oraz przed odkryciem Terragrunt.

4. Ansible lub inne narzędzie ogólnego przeznaczenia do automatyzacji. Zwykle wybierane rozwiązanie, gdy Terraform jest używany po implementacji Ansible lub gdy aktywnie używany jest interfejs użytkownika Ansible.

Mając to wszystko na uwadze — ta książka zawiera przegląd pierwszych dwóch z struktur projektowych — tylko Terraform i Terragrunt.

Struktura kodu Terraform

Struktura kodu Terragrunt

Ta sekcja opisuje kluczowe pojęcia, które są używane w książce.

Zasób (resource)

Przykładowe zasoby to aws_vpc, aws_db_instance, itd. Zasób należy do dostawcy (provider), może przyjmować argumenty (parameters) oraz zwracać różne atrybuty (outputs) i ma swój cykl życia (lifecycle). Może on być tworzony, pobierany, aktualizowany i usuwany.

Moduł zasobu (resource module)

Moduł infrastruktury (infrastructure module)

Moduł infrastruktury to zbiór modułów zasobów, które nie muszą być ze sobą logicznie połączone, ale mogą, współpracując ze sobą służyć temu samemu celowi. Definiuje konfigurację dla dostawców, która jest następnie przekazywana do modułów zasobów podrzędnych i do samodzielnych zasobów. Zwykle ogranicza się on do pracy w pojedynczej encji na każdy logiczny separator (np. region AWS, projekt Google).

Kompozycja (composition)

Kompozycja to zbiór modułów infrastruktury, które mogą obejmować kilka logicznie oddzielonych obszarów (np. regiony AWS, kilka kont AWS). Kompozycja służy do opisania kompletnej infrastruktury wymaganej dla całej organizacji lub projektu.

Kompozycja składa się z modułów infrastruktury, na które składają się moduły zasobów, które realizują poszczególne zasoby

Źródło danych (data source)

Źródło danych wykonuje operacje tylko do odczytu (read-only) i jest zależne od konfiguracji dostawcy. Jest ono używane w module zasobów i module infrastruktury.

Źródło danych terraform_remote_state działa jako spoiwo dla modułów i kompozycji wyższego poziomu.

Zdalny zapis stanu infrastruktury (remote state)

Dostawca (provider, provisioner)

Skąd te trudności?

Dostęp do danych oraz wymiana między nimi (moduły zasobów i moduły infrastruktury) jest realizowany z wykorzystaniem wyjść modułów (module output) i źródeł danych.

Starając się przedstawić opisane powyżej pojęcia przy pomocy pseudorelacji uzyskamy następującą strukturę:

Ten przykład zawiera kod dla strukturyzacji konfiguracji Terraform dla średniego rozmiaru infrastruktury, która zawiera:

• 2 konta AWS

• 2 oddzielne środowiska (prod i stage, które nic ze sobą nie dzielą). Każde środowisko funkcjonuje na osobnym koncie AWS

• Każde środowisko używa tej samej wersji modułów/sieci (modules/network) modułu wewnętrznego, ponieważ pochodzi z katalogu lokalnego.

Ten przykład zawiera kod dla strukturyzacji konfiguracji Terraform dla małego rozmiaru infrastruktury, w której nie są używane zależności zewnętrzne.

Ten przykład zawiera kod dla strukturyzacji konfiguracji Terraform dla dużego rozmiaru infrastruktury, która zawiera:

• 2 konta AWS

• 2 regiony

• 2 oddzielne środowiska (prod i stage, które nic ze sobą nie dzielą). Każde środowisko funkcjonuje na osobnym koncie AWS

• Każde środowisko używa tej samej wersji modułów/sieci (modules/network) modułu wewnętrznego, ponieważ pochodzi z katalogu lokalnego.

Jakich narzędzi muszę używać?

Należy określić wersje modułów zasobów i infrastruktury. Dostawcy powinni być skonfigurowani poza modułami, ale tylko w kompozycji. Wersję dostawców i Terraform można również zablokować.

Użyj zmiennych lokalnych (locals), aby określić jawne zależności między zasobami

Przydatny sposób na wskazanie Terraform, że niektóre zasoby powinny zostać usunięte wcześniej, nawet jeśli nie ma bezpośredniej zależności w konfiguracjach.

Terraform 0.12 - argumenty wymagane vs opcjonalne

1. Wymagany argument index_document musi być ustawiony, jeśli var.website nie jest pustą mapą.

2. Opcjonalny argument error_document można pominąć.

Dokumentacja

Dokumentacja generowana automatycznie

Dzięki konfiguracjom Terraform pre-commit może służyć do formatowania i sprawdzania poprawności kodu, a także do aktualizowania dokumentacji.

terraform-docs

Źródła

Istnieją też warsztaty dla osób, które chcą przećwiczyć niektóre z zagadnień opisanych w tej książce.

Podstawowe zasady

1. Wszędzie używaj _ (podkreślenia) zamiast - (myślnika) (nazwy zasobów, nazwy źródeł danych, nazwy zmiennych, dane wyjściowe itp.).

2. Staraj się używać małych liter i cyfr (nawet jeśli obsługiwany jest kod UTF-8).

Zasoby i źródła danych

1. Nie powtarzaj typu zasobu w nazwie zasobu (ani częściowo, ani całkowicie):

   resource "aws_route_table" "public" {}

   resource "aws_route_table" "public_route_table" {}

   resource "aws_route_table" "public_aws_route_table" {}

3. Nazwy zawsze powinny być rzeczownikami w liczbie pojedynczej.

4. Używaj - wewnątrz wartości argumentów oraz w miejscach, w których wartość będą odczytywane przez człowiekowa (np. wewnątrz nazwy DNS instancji RDS).

5. Argumenty count lub for_each umieszczaj wewnątrz bloku zasobu lub źródła danych jako pierwszy argument u góry i oddzielaj go znakiem nowej linii.

6. Argument tags, jeśli jest obsługiwany przez zasób, umieszczaj jako ostatni , po którym następuje depend_on i lifecycle, jeśli to konieczne. Wszystkie te elementy powinny być oddzielone pojedynczym pustym wierszem.

7. Używając warunków logicznych przy argumencie count lub for_each stosuj wartości logiczne zamiast porównywania długości ciągu czy innych wyrażeń.

Przykładowy kod zasobu (resource)

Użycie count / for_each

Umiejscowienie tags

Warunki w count

Zmienne

1. Nie próbuj na nowo wymyślać koła w modułach zasobów: użyj nazwy (name), opisu (description) i wartości domyślnej (default) dla zmiennych zgodnie z definicją w sekcji „Odniesienie do argumentów” ("Argument Reference") dla zasobu, z którym pracujesz.

2. Obsługa walidacji w zmiennych jest raczej ograniczona (np. brak dostępu do innych zmiennych lub wyszukiwania). Zawczasu planuj odpowiednie użycie, ponieważ w wielu przypadkach funkcja walidacji jest bezużyteczna.

3. Używaj liczby mnogiej w nazwie zmiennej, gdy jest ona listą (list(...)) lub mapą (map(...)) .

4. Uporządkuj klucze w bloku zmiennych w następujący sposób: opis (description), typ (type), wartość domyślna (default), walidacja (validation).

5. Zawsze dołączaj opis (description) do wszystkich zmiennych, nawet jeśli uważasz, że jest to oczywiste (przyda się w przyszłości).

6. Używaj prostych typów (number, string, list(...), map(...), any) zamiast określonego typu, takiego jak object(), chyba że musisz mieć ścisłą kontrolę nad każdym elementem.

7. Użyj określonych typów, np. map(map(string)) jeśli wszystkie elementy mapy mają ten sam typ (np. string ) lub mogą być na niego przekonwertowane (np. typ number można przekonwertować na string).

8. Użyj any, aby ominąć walidację typu, gdy chcesz obsłużyć różne typy..

9. Wartość {} to czasami mapa, a czasami obiekt. Użyj tomap(...), aby stworzyć mapę, ponieważ nie ma możliwości stworzenia obiektu.

Dane wyjściowe

Spraw, aby dane wyjściowe były spójne i zrozumiałe poza zakresem użycia (scope) (gdy użytkownik korzysta z modułu, powinno być oczywiste, jaki jest typ i atrybut zwracanej wartości).

1. Nazwa danych wyjściowych powinna opisywać właściwość, którą zawiera, i być bardziej ścisła niż standardowo.

2. Dobra struktura nazwy wyjścia wygląda tak: {name}_{type}_{attribute} , gdzie:

   1. {name} to nazwa zasobu lub źródła danych bez prefiksu dostawcy. {name} dla aws_subnet to subnet, a dla aws_vpc to vpc.

   2. {type} to rodzaj źródła zasobów.

   3. {attribute} to zwracany atrybut
5. Zawsze dołączaj opis (description) danych wyjściowych, nawet jeśli uważasz, że jest to oczywiste.

6. Unikaj użycia sensitive, chyba że w pełni kontrolujesz użycie tego wyjścia (danych wyjściowych) we wszystkich miejscach i we wszystkich modułach.

7. Stosuj try() (dostępne od Terraform 0.13) zamiast element(concat(...)) (podejście starsze dla wersji przed 0.13)

Przykłady poprawnego output

Zwróć co najwyżej jeden identyfikator security_group:

W przypadku posiadania wielu zasobów tego samego typu, należy unikać this w nazwie wyjścia:

Użyj nazwy w liczbie mnogiej, jeśli wartością zwracaną jest lista