Walidator szablonów CloudFormation

Walidator szablonów CloudFormation – błędy przed deploymentem

Błędny szablon CloudFormation wykryty dopiero podczas deploymentu oznacza rollback i stratę czasu. Narzędzie waliduje składnię, strukturę i referencje szablonu AWS CloudFormation (JSON lub YAML) przed wgraniem do AWS – bez dostępu do konta AWS.

Jak działa walidacja szablonu CloudFormation

Narzędzie pracuje w dwóch warstwach: składniowej i semantycznej. Warstwa składniowa to parser, który przyjmuje zarówno JSON, jak i YAML. YAML w CloudFormation nie jest zwykłym YAML-em — używa własnych tagów, takich jak !Ref, !GetAtt, !Sub, !Join, !If czy !FindInMap. Parser zamienia je na wewnętrzną reprezentację równoważną długim formom, czyli zapisom typu Ref albo Fn::GetAtt. Dzięki temu oba formaty trafiają do tej samej struktury danych i dalsze sprawdzanie przebiega identycznie, niezależnie od tego, co wkleiłeś.

Warstwa semantyczna porównuje otrzymaną strukturę z modelem szablonu. Sprawdzana jest obecność i kolejność sekcji najwyższego poziomu, a następnie każdy zasób: czy jego Type istnieje, czy podano właściwości wymagane dla tego typu, czy wartości mają dopuszczalny typ i czy mieszczą się w dozwolonym zbiorze wartości. Równolegle budowany jest graf zależności — węzłami są parametry, zasoby i warunki, a krawędziami odwołania z Ref, GetAtt, DependsOn oraz Sub. Graf pozwala wykryć odwołania do nieistniejących celów, użycie nieistniejącego atrybutu zasobu oraz cykle, które uniemożliwiłyby utworzenie stosu.

Cała analiza odbywa się lokalnie, bez połączenia z API AWS i bez poświadczeń. Walidator zna katalog typów zasobów i reguły ich właściwości, ale nie zna stanu Twojego konta. Wynik ma więc charakter statyczny: pewne błędy blokujące (niepoprawna składnia, brak Resources, odwołanie do nieistniejącego zasobu) oraz ostrzeżenia o konstrukcjach ryzykownych, których nie da się rozstrzygnąć bez deploymentu.

Przykład krok po kroku: szablon z bucketem, rolą i funkcją Lambda

1. Przygotowujesz szablon zawierający sekcje AWSTemplateFormatVersion, Parameters i Resources. W sekcji Resources masz trzy zasoby o nazwach logicznych: Bucket typu AWS::S3::Bucket, TaskRole typu AWS::IAM::Role oraz Funkcja typu AWS::Lambda::Function.
2. Wklejasz całą treść do pola tekstowego i uruchamiasz walidację. Parser rozpoznaje tagi skrócone, przetwarza !GetAtt i !Sub, więc ewentualne błędy składni YAML zostaną zgłoszone jako pierwsze — z podaniem miejsca, w którym parsowanie się zatrzymało.
3. Etap struktury sprawdza, czy sekcja Resources istnieje i czy każdy zasób ma pola Type oraz Properties. Dla funkcji Lambda wymagane są między innymi Code, Handler, Role i Runtime — brak któregokolwiek z nich pojawi się jako błąd wskazujący nazwę logiczną zasobu i nazwę brakującego klucza.
4. Etap referencji weryfikuje odwołania. Zapis !GetAtt Bucket.Arn wskazuje istniejący zasób i prawidłowy atrybut, więc przechodzi. Zapis !GetAtt Bucket.BucketName wygląda podobnie, ale BucketName nie jest atrybutem zwracanym przez AWS::S3::Bucket — poprawna nazwa bucketu pochodzi z Ref, a atrybuty to między innymi Arn i DomainName. Taki wpis zostaje zgłoszony jako błąd.
5. Etap grafu wykrywa cykle. Jeśli w TaskRole umieścisz odwołanie do funkcji, a funkcja w polu Role odwołuje się do tej samej roli przez !GetAtt TaskRole.Arn, powstaje zamknięty łańcuch zależności. Walidator wskaże oba końce cyklu, bo CloudFormation nie potrafi ustalić kolejności tworzenia takich zasobów.
6. Poprawiasz atrybut na DomainName albo zamieniasz go na Ref, usuwasz zależność zwrotną i uruchamiasz walidację ponownie. Brak komunikatów o błędach oznacza, że szablon jest spójny wewnętrznie i gotowy do wgrania do AWS.

Co walidator sprawdza w poszczególnych sekcjach

Praktyczne wskazówki

• Waliduj przyrostowo — uruchamiaj sprawdzenie po dodaniu każdego zasobu, a nie dopiero przed wgraniem całego szablonu. Łatwiej wtedy przypisać komunikat do konkretnej zmiany.
• Ustaw edytor na spacje — YAML nie dopuszcza znaków tabulacji w wcięciach. Mieszanie tabulatorów i spacji w jednym pliku to najczęstsza przyczyna błędu parsowania, który unieważnia wszystkie dalsze sprawdzenia.
• Nadawaj opisowe nazwy logiczne — komunikaty odwołują się do nazw typu Bucket czy TaskRole, a nie do numerów linii w pliku. Nazwy w stylu Zasob1, Zasob2 utrudniają znalezienie miejsca błędu.
• Czytaj komunikaty po kolei — błąd składni zatrzymuje analizę, więc lista problemów pojawia się dopiero po jego naprawieniu. Najpierw usuń problemy parsera, potem zajmij się strukturą i referencjami.
• Sprawdzaj wymagane pola w dokumentacji — gdy walidator zgłosi brak właściwości dla danego typu zasobu, porównaj szablon z dokumentacją tego typu. Sam komunikat podaje nazwę brakującego klucza, ale nie podpowiada jego wartości.

Ograniczenia walidacji offline

• Brak dostępu do konta AWS — narzędzie nie potwierdzi, czy identyfikator AMI istnieje w Twoim regionie, czy rola IAM ma wymagane uprawnienia ani czy nie przekroczysz limitów usługi. Te błędy ujawniają się dopiero podczas tworzenia stosu.
• Nieznane wartości parametrów — parametry bez wartości domyślnej pozostają nierozstrzygnięte, a wartości z Parameter Store i Secrets Manager nie są pobierane. Walidator nie oceni zatem poprawności konkretnego zestawu danych wejściowych.
• Własne makra Transform — rozpoznawane są znane transformy, natomiast niestandardowe makra nie są wykonywane. Zasoby wygenerowane przez makro nie zostaną sprawdzone, bo przed transformacją ich po prostu nie ma w szablonie.
• Aktualność katalogu typów — jeśli katalog jest starszy niż nowo ogłoszone typy i właściwości, walidator może zgłosić fałszywy błąd albo pominąć nowe pole. Wynik nie obejmuje też zmian zachowania usług AWS po deploymencie ani dryftu istniejących zasobów.

Najczęstsze pytania

Powiązane narzedzia: walidator YAML, generator GitLab CI/CD i formater JSON API.