BLOG

AWS CloudFormation 템플릿 매개변수의 자동화된 문서화
작성일: 2019-07-02

AWS Quick Start는 AWS CloudFormation을 사용하여 구축된 자동화 골드 표준 배포이며 단계별 배포 가이드가 함께 제공됩니다. 이 가이드에서는 배포 구성을 제어하기 위해 런타임 시 템플릿에 전달되는 AWS CloudFormation 입력 매개변수의 문서화를 자동화하는 메커니즘이 필요했습니다. 템플릿에는 최대 60개의 매개변수가 포함될 수 있으며 이러한 매개변수를 수동으로 문서화하는 것은 힘든 작업이 될 수 있습니다.

 

이번 블로그 게시물에서는 AWS CloudFormation 매개변수를 테이블에 문서화하는 메커니즘에 대해 자세히 설명해 드리려 합니다. 해당 매커니즘은 사용 가능한 매개변수 조정 범주에 대해 편리한 참고 자료를 제공합니다. 이는 복잡한 CloudFormation 템플릿을 관리하고 매개변수를 문서화하고자 옵션을 탐색하는 팀들이 속한 조직에 특히 유용할 수 있습니다.

 

이 메커니즘은 JSON 또는 YAML 형식으로 AWS CloudFormation 템플릿을 분석하는 파이썬(Python) 스크립트를 사용하고, 문서화에서 이용할 수 있는 HTML 테이블을 생성합니다.

 

또한 Amazon API Gateway 엔드포인트에서 AWS 람다(Lambda) 함수로 스크립트를 패키지화함으로 템플릿 테이블 생성을 위한 편리한 서버리스 솔루션을 제공하는 방법을 보여줍니다.

 

파이썬을 사용하여 템플릿 매개변수 테이블 생성하기

CloudFormation 템플릿은 JSON 또는 YAML로 작성됩니다. 파이썬은 JSON을 기본적으로 지원하며 PyAMAM 또는 ruamel.yaml과 같은 인기 있는 라이브러리를 사용하여 YAML 처리를 수행 할 수 있습니다. JSON 형식도 유효한 YAML 형식이기 때문에 YAML 처리 라이브러리를 사용하여 두 형식을 모두 처리할 수 ​​있습니다. CloudFormation 템플릿의 구조에 대한 자세한 내용은 AWS CloudFormation 설명서를 참고하십시오.

 

YAML 형식의 템플릿 조각은 아래에 제시된 것과 유사합니다.

–

AWSTemplateFormatVersion: “version date”

 

Description:

String

 

Metadata:

template metadata

 

Parameters:

set of parameters

 

…

 

Resources:

set of resources

 

…

 

메타 데이터 및 매개변수 섹션을 분석하여 매개변수 키와 그 의도를 설명하는 기술은 보기 쉽게 표 형식으로 생성할 수 있습니다. 아래 링크를 통해 해당 예시 파일을 확인해 보실 수 있습니다.

https://github.com/aws-samples/aws-cloudformation-parameter-table-generator/blob/master/functions/source/table-generator-lambda.py

 

스크립트에는 네 가지 입력 메커니즘을 실험할 수 있는 주요 방법인 테스트 도구가 있습니다.

  • Absolute file path
  • File URL
  • HTTP(S) URL
  • S3 URI

 

스크립트를 실행하면 HTML 데이터가 콘솔에 출력되고 원하는 브라우저에서 볼 수 있도록 HTML 파일로 리다이렉트할 수 있습니다. 그 예는 아래와 같습니다.

python3 table-generator-lambda.py > test.html

 

스크립트를 실행하는 것이 편리하지만 스크립트에 lambda_handler 방식이 제공되었음을 알아채셨을 겁니다. 이 스크립트는 AWS Lambda 함수로 패키징되어 Amazon API Gateway 엔드포인트에 의해 호출될 수 있습니다. 이렇게 하면 CloudFormation 매개변수 테이블을 생성하기 위한 서버리스 솔루션이 제공됩니다. 자 그럼 다음 과정으로 넘어가 보겠습니다.

 

서버리스 매개변수 테이블 생성기

다음은 솔루션의 고수준 아키텍처 다이어그램입니다.

 

자, 여기 솔루션을 신속하게 프로비저닝하는데 사용할 수 있는 CloudFormation 템플릿을 만들었습니다. 해당 템플릿은 다음의 매개변수를 필요로 합니다. (이러한 테이블을 생성하기 위해 서버리스 매개변수 테이블 생성기를 사용했습니다. 🙂 )

 

입력 구성

매개변수 레이블(이름) 기본 상세 설명
허용된 CIDR 블록
(AllowedCIDRBlocks)		 입력 필요 API 게이트웨이 엔드포인트에 액세스가 허용되는 CIDR 블록의 Comma-delimited(쉼표로 구분된) 목록입니다. 예) ‘’11 .12.13.14 / 24,12.13.14.15 / 24 ‘. 테스트를 위해 ‘0.0.0.0/0’을 사용할 수 있습니다. 이렇게 하면 배포된 API를 공개적으로 사용할 수 있습니다.
템플릿 버킷
(TemplatesBucket)		 — s3 : // <bucket> / <key> URI 형식을 사용하여 비공개적으로 저장된 템플릿을 읽을 수 있는 기존 S3 버킷입니다. 이 값을 지정하지 않으면 공용 템플릿에 대한 테이블만 생성할 수 있습니다.

 

AWS Quick Start 구성

소스에서 배치를 사용자 맞춤형으로 지정하려는 경우에만 다음 기본값을 변경하십시오.

매개변수 레이블(이름) 기본값 상세 설명
Quick Start S3 bucket 이름(QSS3BucketName) aws-cfn-samples Quick Start 자산의 S3 버킷 이름입니다. Quick Start를 사용자가 직접 사용하기 위해 사용자 정의 및 확장하는 경우에만 이 값을 변경하십시오. 해당 문자열은 숫자, 소문자, 대문자 및 하이픈(-)을 포함할 수 있습니다. 단 하이픈(-)으로 시작하거나 끝낼 수는 없습니다.
Quick Start S3 키 접두사(QSS3KeyPrefix) aws-cloudformation-parameter-table-generator/ Quick Start 자산의 S3 키 이름 접두사(prefix)입니다. Quick Start 키 접두사는 숫자, 소문자, 대문자, 하이픈(-) 및 슬래시(/)를 포함할 수 있습니다.

 

허용 CIDR 블록(Allowed CIDR blocks) 매개변수에 대해 IP 범위를 선택하고 CloudFormation 템플릿을 템플릿 버킷(Templates bucket) 매개변수로 안전하게 호스팅하는 기존 S3 버킷을 옵션으로 지정하면 스택을 배포할 수 있습니다.

 

AWS CloudFormation 콘솔을 사용하는 경우, 스택 생성(Create stack) 페이지에서 템플릿 URL을 제공한 후 프롬프트를 따를 수 있습니다.

 

또는 AWS CLI(명령 줄 인터페이스)를 사용하여 스택을 배포할 수 있습니다. 샘플 매개변수 입력 파일을 다운로드하고 구성에 맞게 입력 값을 변경하십시오. 그런 다음 AWS CLI를 사용하여 다음 명령을 실행하십시오. 스택을 배치하기로 선택한 리전으로 <region-name> 을 대체하십시오.

 

aws cloudformation create-stack –stack-name –region <region-name> cfn-table-generator \

–template-url https://s3.amazonaws.com/aws-cfn-samples/aws-cloudformation-parameter-table-generator/templates/cfn-doc-generator.yaml \

–parameters file://params.json \

–capabilities “CAPABILITY_IAM” “CAPABILITY_AUTO_EXPAND” \

–disable-rollback

 

배포 테스트

배포가 완료되면 AWS CloudFormation 콘솔에서 스택의 출력 섹션으로 이동합니다. 예시에선 빠른 시작을 위해 다음과 같은 출력을 포함시켰습니다.

 

배포가 제대로 작동하는지 테스트하려면 CFDocGeneratorApiEndpoint URL에서 REPLACE_WITH_TEMPLATE_URL 토큰을 공용 URL로 교체하십시오. (예: 이전에 스택을 배포하는 데 사용한 공용 URL).

 

https://s3.amazonaws.com/aws-cfn-samples/aws-cloudformation-parameter-table-generator/templates/cfn-doc-generator.yaml

 

API Gateway의 출력은 다음과 같습니다.

 

개인 템플릿용 테이블 생성하기

스택을 배포할 때 템플릿 버킷 매개변수에 값을 제공하면, Lambda 함수 역할에 해당 버킷에 대한 읽기 권한이 부여됩니다. 출력 URL의 토큰을 템플릿 파일의 S3 URI로 대체할 수 있습니다. 그 예는 다음과 같습니다.

 

s3://<my-templates-bucket>/<key/of/my-template.yaml>

 

문제 해결

오류가 발생하면 Amazon CloudWatch Logs에서 Lambda 함수를 확인하십시오.

 

결론

AWS Quick Start팀에서는 AWS CloudFormation을 사용하여 자동화되며 안전한 방식으로 클라우드 환경의 인프라 리소스를 설명 및 제공합니다.

 

특히 길고 복잡한 템플릿인 경우엔 매개변수를 수동으로 문서화하는데 시간이 꽤 오래 걸릴 수 있습니다. 지금까지 로컬 스크립트를 실행할 필요가 없는 서버리스 솔루션을 사용하여 CloudFormation 템플릿을 문서화하는 편리한 방법을 보여드렸습니다. 결과적으로 CloudFormation 입력 매개변수를 사용자 친화적인 매개변수 테이블 형식으로 편리하게 참고할 수 있습니다. 이는 복잡한 CloudFormation 템플릿을 관리하고 이를 문서화하고자 메커니즘을 모색 중인 조직의 다양한 팀들에게도 똑같이 유용할 수 있습니다.

 

코드에 대해서 더 깊이 알고 싶으시다면, GitHub 저장소에 방문하셔서 피드백이나 기능향상을 위한 제안 및 의견을 남겨주십시오.

 

원문 URL : https://aws.amazon.com/ko/blogs/infrastructure-and-automation/automated-documentation-of-aws-cloudformation-template-parameters/

 

** 메가존 클라우드 TechBlog는 AWS BLOG 영문 게재글 중에서 한국 사용자들에게 유용한 정보 및 콘텐츠를 우선적으로 번역하여 내부 엔지니어 검수를 받아서, 정기적으로 게재하고 있습니다. 추가로 번역및 게재를 희망하는 글에 대해서 관리자에게 메일 또는 SNS 페이지에 댓글을 남겨주시면, 우선적으로 번역해서 전달해드리도록 하겠습니다.