Szablon AWS Cloudformation

przez
Tagi: aws cloudformation

Umiejętność tworzenia szablonów (ang. Templates) jest niezbędna do korzystania z serwisu AWS Cloudformation. Obejmuje to:

  • znajomość struktury szablonu,
  • znajomość właściwości zasobów,
  • korzystanie z funkcji specjalnych.

Te zagadnienia omówię na podstawie przykładowego szablonu, który tworzy kubełek S3 z opcją powiadamiania zainteresowanych o utworzonych nowych obiektach. Informacja jest wysyłana do predefiniowanych odbiorcy.

Szablon

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Parameters": {
        "OdbiorcaEmail": {
            "Description": "Adres odbiorcy",
            "Type": "String"
        },
        "NazwaKubelka": {
            "Description": "Nazwa kubelka",
            "Type": "String"
        }
    },
    "Resources": {
	    
		"MojeDokumenty": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
				"BucketName": {"Ref": "NazwaKubelka"},
				"NotificationConfiguration": {
					"TopicConfigurations": [
						{
							"Event": "s3:ObjectCreated:*",
							"Topic" {"Ref": "EmailTopic"}
						}
					]
				}
            }
        },
		"EmailTopic": {
			"Type" : "AWS::SNS::Topic",
			"Properties" : {
				"DisplayName" : String,
				"Subscription" : [ { 
					"Endpoint": {"Ref": "OdbiorcaEmail"},
					"Protocol" "email"
				} ],
				"TopicName" : {"Fn::Sub": [
					"dodany-plik-${NazwaKubelka}"
					]
				}
			}
		}
	},
	"Outputs": {
		"AdresWww": {
			"Value": {"Fn::GetAtt" ["MojeDokumenty", "WebsiteURL"],
			"Descriptoin" "Adress WWW kubelka"
		}
	}

Szablon zdefiniowany jako obiekt JSON posiada następujące atrybuty:

  • AWSTemplateFormatVersion - wersja specyfikacji szablonu. Jeżeli atrybut nie jest zdefiniowany AWS automatycznie przyjmuje ostatnią wersję specyfikacji - obecnie jest to wartość 2010-09-09,
  • Parameters - parametry wejściowe, które podaje się przed tworzeniem albo aktualizowaniem stosu. Parametry mogą być używane w konfiguracji poszczególnych zasobów. Ta sekcja nie jest obowiązkowa,
  • Resources - w tej sekcji definiuje się wszystkie zasoby, które powinny być utworzone w jednym stosie reprezentowanym przez szablon. Każdy z zasobów jest reprezentowany przez obiekt JSON, a jego atrybuty wynikają z dokumentacji. Definiując zasób można odwoływać się do innych, które są skonfigurowane w tym samym szablonie i do parametrów wejściowych używają do tego wewnętrznych funkcji,
  • Outputs - parametry wyjściowe szablonu, które można odczytać w serwisie CloudFormation po utworzeniu stosu.

Parameters

"Parameters": {
        "OdbiorcaEmail": {
            "Description": "Adres odbiorcy",
            "Type": "String"
        },
        "NazwaKubelka": {
            "Description": "Nazwa kubelka",
            "Type": "String"
        }
    }

Każdy z parametrów jest reprezentowany przez obiekt JSON, który może zawierać następujące parametry:

  • Type - wymagany atrybut określa typ wartości parametru. Dozwolone jest użycie tylko typów z listy,
  • Description - przyjazny dla człowieka opis parametru,
  • Default - domyślna wartość parametru, używana jeżeli nie została podana inna przed tworzeniem / aktualizacją stosu. Jeżeli parametr nie ma podanej domyślnej wartości i wartość parametru nie została ustalona przed tworzeniem stosu, wtedy operacja kończy się niepowodzeniem,
  • AllowedValues - lista dozwolonych wartości,
  • AllowedPattern - wyrażenie regularne używane do sprawdzenia poprawności parametru.

W sekcji szablonu, w której konfiguruje się zasoby można się odwoływać do parametrów używając funkcji Ref.

Resources

 "Resources": {
	    
		"MojeDokumenty": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
				"BucketName": {"Ref": "Kubelek"},
				"NotificationConfiguration": {
					"TopicConfigurations": [
						{
							"Event": "s3:ObjectCreated:*",
							"Topic": {"Ref": "EmailTopic"}
						}
					]
				}
            }
        },
		"EmailTopic": {
			"Type" : "AWS::SNS::Topic",
			"Properties" : {
				"Subscription" : [ { 
					"Endpoint": {"Ref": "OdbiorcaEmail"},
					"Protocol": "email"
				} ],
				"TopicName" : {"Fn::Sub": [
					"dodany-plik-${NazwaKubelka}"
					]
				}
			}
		}
	}

W głównej sekcji szablonu tworzymy dwa zasoby:

  • MojeDokumenty kubełek S3 typu AWS::S3::Bucket o nazwie określonej w parametrze NazwaKubelka. Do tej wartości odwołujemy się przy pomocy funkcji Ref. Atrybutem NotificationConfiguration konfigurejmy sposób dostarczenia powiadomień do użytkowników oraz sytuację w której powinny być wygenerowane. W tym przypadku powiadomienie o utworzeniu dowolnego obiektu "Event": "s3:ObjectCreated:* zostanie wysłane na topic SNS "Topic": {"Ref": "EmailTopic"}. W atrybucie Topic odwołujemy się przy pomocy funkcji Ref do innego zasobu utworzonego tym samym szablonem. Oprócz topiców SNS powiadomienia można wysłać także do funkcji lambda oraz kolejki SQS.
  • EmailTopic topic SNS typu AWS::SNS::Topic. Serwisu AWS SNS używa się do wysyłania powiadomień za pomocą różnych protokołów. W celu wysłania powiadomienia na konto e-mail definiujemy subskrypcję z dwoma parametrami Endpoint oraz Protocol. Drugi z nich ma zawsze wartość email na określenie użytego protokołu wysyłania. Dla protokołu e-mail wartością atrybutu Endpoint musi być adres e-mail odbiorcy. W tym przypadku używamy wartości parametru wejściowego. Dodatkowo Topic wymaga ustawienia jego nazwy TopicName. Budujemy go przy pomocy funkcji Fn::Sub. Funkcja Fn::Sub działa w ten sposób, że wartość między ${} zastępuje istniejącym parametrem lub innym zdefiniowanym atrybutem. W naszym przypadku nazwa topicu będzie utorzona z parmetru NazwaKubelka.

Outputs

"Outputs": {
		"AdresWww": {
			"Value": {"Fn::GetAtt" ["MojeDokumenty", "WebsiteURL"],
			"Descriptoin" "Adress WWW kubelka"
		}
	}

W sekcji Outputs określamy parametry wyjściowe, które można odczytać w serwisie CloudFormation. Każdy parametr jest obiektem JSON musi zawierać atrybut Value. W tym przypadku określamy adres URL kubełka MojeDokumenty używając do tego funkcj Fn::GetAtt. Każdy zasób typu AWS::S3::Bucket posiada zestaw atrybutów, które można odczytac przy pomocy ww. funkcji, jedym z nich jest WebsiteURL.

Podsumowanie

W tym artykule z cyklu CloudFormation zapoznaliśmy się z anatomią szablonu, którego używa się do definiowania zasobów w serwisach AWS. Przykładowy szablon zawiera konfigurację kubełka S3 oraz topicu AWS SNS.

Zobacz też