Aws에 대한 철저한 설명: SSM 자동화를 위한 executeScript 작업

📅 작성일: 2025/01/04, 수정일: 2025/01/04 ⏱️ 예상 읽기 시간 약 9분 (3,544자)

SSM 자동화는 aws: executeScript 작업을 사용하여 Python 또는 PowerShell 스크립트를 실행할 수 있습니다.
스크립트로 시스템 작업을 자동화할 때 람다로 정기적인 처리를 수행하거나 스크립트를 개발하고 로컬에서 실행하는 것이 일반적입니다.
SSM 자동화를 사용하면 시스템 운영자의 권한을 최소화할 수 있습니다.관리 콘솔에서 프로세스를 실행하는 데 필요한 전용 입력 필드를 준비하거나 승인 단계를 제공할 수 있습니다.
시스템 운영에 특화된 기능을 사용할 수 있습니다.
이 글에서는 SSM 자동화의 aws: executeScript 동작에 대해 설명하겠습니다.

자동화란 무엇입니까?
aws:executeScript 작업 개요
설명
개발 시점

자동화란 무엇입니까?

자동화는 운영 작업을 자동화할 수 있는 AWS Systems Manager의 기능입니다.
자동화로 실행되는 작업을 정의하는 Runbook을 사용하여 다양한 작업을 자동화할 수 있습니다.
AWS에서는 다양한 Runbook을 제공하고 있으며, 필수 파라미터를 제공하여 작업을 실행할 수 있습니다.
참조: Systems Manager 자동화 런북 참조 - AWS 시스템 관리자 자동화 런북 참조
자체 런북을 정의하거나, 작업을 결합하여 사용자 지정 처리를 구현하거나, AWS에서 제공하는 여러 런북을 호출하여 운영 워크플로를 생성할 수도 있습니다.
참조: Systems Manager 자동화 작업 참조 - AWS Systems Manager

aws:executeScript 작업 개요

이 작업을 통해 제공한 Python 또는 PowerShell 스크립트를 실행할 수 있습니다.

설명

CloudFormation 예

다음은 aws:executeScript 단계를 사용하여 CloudFormation에만 정의된 샘플입니다. ${변수 이름} 과 같은 값을 가진 속성은 나중에 설명됩니다.

AWSTemplateFormatVersion: 2010-09-09
Description: template.automation.yml
Resources:
  Document:
    Type: AWS::SSM::Document
    Properties:
      Name: "${Document name}"
      DocumentType: Automation
      Attachments:
        - Key: "S3FileUrl"
          Name: "${ZIP file name}"
          Values:
            - !Sub "s3://${S3 bucket name}/${ZIP file name}"
      Content:
        schemaVersion: "0.3"
        assumeRole: "${Delegation role ARN}"
        mainSteps:
          - action: aws:executeScript
            name: RunSetupScript
            inputs:
              Runtime: "${Runtime name}"
              Handler: "${Python file name}.${Function name}"
              InputPayload:
                "${Payload}"
        files:
          ${ZIP file name}:
            checksums:
              sha256: "${The hash value of the zip file}"

속성: 이름
값 유형: 문자열
설명:
Runbook의 이름을 지정합니다.
이름을 지정하고 Runbook을 업데이트할 때 대체가 발생하는 경우 동일한 이름으로 다른 Runbook을 만들 수 없으며 이로 인해 오류가 발생합니다.
자동으로 생성된 Runbook 이름을 사용하거나 배포할 때마다 고유한 이름을 지정합니다.
속성: 첨부 파일
유형: 첨부 원본 목록
설명: Runbook 실행에 필요한 파일을 지정합니다.
속성: Content -> assumeRole
값 유형: 문자열
설명: Runbook을 실행하는 데 필요한 역할을 지정합니다.
속성: Content -> mainSteps -> inputs -> Runtime
값 유형: 문자열
설명:
실행할 스크립트의 런타임을 지정합니다.
현재 python3.x 또는 PowerShell Core X.X 만 지정할 수 있습니다.
사용 가능한 런타임은 다음을 참조하세요.
시스템 관리자 자동화 작업 참조 - AWS 시스템 관리자
속성: Content -> mainSteps -> inputs -> Handler
값 유형: 문자열
설명:
실행할 스크립트의 함수 이름을 지정합니다.
예를 들어 runbook.py 에서 main 기능을 실행하려면 main 을 지정합니다.
PowerShell의 경우 이 속성이 필요하지 않습니다.
속성: Content -> mainSteps -> inputs -> InputPayload
값 유형: 문자열
설명:
JSON 형식으로 스크립트에 전달할 매개변수를 지정합니다.
매개변수는 스크립트에서 sys.argv 로 액세스할 수 있습니다.
예를 들어, InputPayload 에 이하와 같이 지정했을 경우, 스크립트내에서 sys.argv 를 취득하면, ['runbook.py', '{"key1": "value1", "key2": "value2"}'] 가 됩니다.

InputPayload:
  key1: value1
  key2: value2

프로퍼티명: Content -> files -> ${ZIP file name} -> checksums -> sha256
값 유형: 문자열
해설:
실행할 스크립트가 포함된 ZIP 파일의 해시 값을 지정합니다.해시값은 sha256 만 지정 가능합니다.Windows의 경우 certutil -hashfile ${ZIP file name} SHA256 , Mac의 경우 shasum -a 256 ${ZIP file name} 로 해시 값을 얻을 수 있습니다.

런북 정의(Terraform)

다음은 Terraform에서 aws:executeScript 단계만 정의한 경우의 샘플입니다.값이 ${변수명} 을 이용하고 있는 프로퍼티은 설명을 후술합니다.
Terraform 에서는 null_resource 와 data.archive_file 를 이용해, ZIP 파일을 작성해 S3 에 업로드하는 것이 가능합니다.

resource "null_resource" "install_requirements" {
  triggers = {
    always_run = "${timestamp()}"
  }

  provisioner "local-exec" {
    command = "pip install -r ${path.root}/src/requirements.txt -t ${path.root}/src/modules"
  }
}

data "archive_file" "file" {
  depends_on = [ null_resource.install_requirements ]
  type        = "zip"
  source_dir  = "${path.root}/src/modules"
  output_path = "${path.root}/src/modules.zip"
}

resource "aws_s3_object" "object" {
  bucket = "${S3 bucket name}"
  key    = "modules.zip"
  source = data.archive_file.file.output_path
}

resource "aws_ssm_document" "document" {
  depends_on = [ aws_s3_object.object ]

  name            = "${ドキュメント名}"
  document_type   = "Automation"
  document_format = "JSON"
  attachments_source {
    key = "S3FileUrl"
    name = "modules.zip"
    values = [
      "https://"${S3 bucket name}".s3.amazonaws.com/modules.zip"
    ]
  }

  content = jsonencode({
    assumeRole      = "${Delegation Roll ARN}"
    schemaVersion = "0.3"
    mainSteps = [
      {
        action = "aws:executeScript"
        name   = "RunSetupScript"
        inputs = {
          Runtime = "${Runtime name}"
          Handler = "${関数名}"
          Script  = "${file("${path.root}/src/runbook.py")}"
          Attachment = "modules.zip"
        }
      }
    ]
    files = {
      "modules.zip" = {
        checksums = {
          sha256 = filesha256(data.archive_file.file.output_path)
        }
      }
    }
  })
}

프로퍼티명: aws_s3_object -> bucket , aws_ssm_document -> attachments_source -> values
값 유형: 문자열
해설:
aws_s3_object 의 bucket 은 ZIP 파일을 업로드 할 S3 버킷 이름을 지정합니다.
aws_ssm_document 의 attachments_source 의 values 는 ZIP 파일의 URL을 지정합니다.
프로퍼티명: aws_ssm_document -> name
값 유형: 문자열
해설:
런북의 이름을 지정합니다.
런북의 이름은 고유해야 합니다.
프로퍼티명: aws_ssm_document -> content -> assumeRole
값 유형: 문자열
해설:
– 런북을 실행하는 데 필요한 권한이 있는 역할을 지정합니다.
프로퍼티명: aws_ssm_document -> content -> mainSteps -> inputs -> Runtime
값 유형: 문자열
해설:
– 실행할 스크립트의 런타임을 지정합니다.
현재는 Python3.x 또는 PowerShell Core x.x 만 지정 가능합니다.
사용 가능한 런타임은 아래 링크 대상을 참조하십시오.
Systems Manager Automation 작업 참조 - AWS Systems Manager
프로퍼티명: aws_ssm_document -> content -> mainSteps -> inputs -> Handler
값 유형: 문자열
해설:
– 실행할 스크립트의 함수 이름을 지정합니다.
후술하는 스크립트의 정의(Python)의 예에서는, runbook.py 의 main 함수를 실행하는 경우는 main 라고 지정합니다.
PowerShell의 경우 이 속성은 필요하지 않습니다.
프로퍼티명: aws_ssm_document -> content -> mainSteps -> inputs -> Script
값 유형: 문자열
해설:
– 실행할 스크립트의 파일 경로를 지정합니다.
Terraform 의 경우는, file() 함수를 이용해 파일 패스를 지정하는 것으로, 파일 내용을 캐릭터 라인으로서 취득하는 것이 가능합니다.

스크립트 정의(Python)

다음 파일 구성으로 Python 스크립트를 정의하고 ZIP 파일로 압축하여 S3에 업로드합니다.

${Zipファイル対象のフォルダ名}/
${Zipファイル対象のフォルダ名}/runbook.py
${Zipファイル対象のフォルダ名}/requirements.txt

# ファイル構成例
runbook/
runbook/runbook.py
runbook/requirements.txt

Zip 화할 때는 다음의 2개의 커멘드의 실행이 필요합니다.
Lambda 와 같이 requirements.txt 에 기재된 패키지가 자동으로 인스톨 되는 것은 아니기 때문에, requirements.txt 에 기재된 패키지를 인스톨 하고 나서 ZIP 화할 필요가 있습니다.

pip install -r ${Zipファイル対象のフォルダ名}/requirements.txt -t ${Zipファイル対象のフォルダ名}
zip -rq ${ZIP file name} ${Zipファイル対象のフォルダ名}

자동화 런타임 액션 권한

자동화를 수행하려면 다음 작업에 대한 권한이 필요합니다.

아니요	액션 이름	필요한 작업	리소스 섹션에서 지정하는 ARN
01	ssm:자동화 실행 시작	자동화 실행	자동화정의이름
02	ssm:자동화 실행 중지	자동화 중지	자동화실행 ID
03	ssm:SendAutomationSignal	일시중지된 자동화 재개	자동화실행 ID
04	이미: PassRole	상속 역할을 이용한 자동화 실행	역할이름(경로 포함)

ssm:StartAutomationExecution 및 iam:PassRole 은 리소스 섹션에 고정된 AWS 리소스가 포함된 ARN을 지정할 수 있으므로 실행 사용자에게 특정 런북만 실행할 수 있는 권한만 부여할 수 있습니다.

스크립트 실행 시 환경 정보(Python)

다음 JSON은 런타임 Python 3.8에서 환경 변수를 기록한 것입니다.
환경 변수에서 알 수 있듯이 내부적으로 Lambda가 실행되고 있네요.
Lambda 환경 변수에 대한 자세한 내용은 Lambda 환경 변수 사용 - AWS Lambda(https://docs.aws.amazon.com/ko_kr/lambda/latest/dg/configuration-envvars.html)를 참조하십시오.

{
    "_AWS_XRAY_DAEMON_ADDRESS": "169.254.79.129",
    "_AWS_XRAY_DAEMON_PORT": "2000",
    "_HANDLER": "FalconPythonWrapper.lambda_handler",
    "_X_AMZN_TRACE_ID": "Root=x-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx;Parent=xxxxxxxxxxxxxxxx;Sampled=1;Lineage=xxxxxxxx:x|xxxxxxxx:x|xxxxxxxx:x",
    "AWS_ACCESS_KEY_ID": "xxxxxxxxxx",
    "AWS_DEFAULT_REGION": "us-east-2",
    "AWS_EXECUTION_ENV": "AWS_Lambda_python3.8",
    "AWS_LAMBDA_FUNCTION_MEMORY_SIZE": "512",
    "AWS_LAMBDA_FUNCTION_NAME": "Falcon-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "AWS_LAMBDA_FUNCTION_VERSION": "$LATEST",
    "AWS_LAMBDA_INITIALIZATION_TYPE": "on-demand",
    "AWS_LAMBDA_LOG_GROUP_NAME": "/aws/lambda/Falcon-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "AWS_LAMBDA_LOG_STREAM_NAME": "2023/12/14/[$LATEST]xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "AWS_LAMBDA_RUNTIME_API": "127.0.0.1:9001",
    "AWS_REGION": "us-east-2",
    "AWS_SECRET_ACCESS_KEY": "xxxxxxxxxx",
    "AWS_SECURITY_TOKEN": "xxxxxxxxxx",
    "AWS_SESSION_TOKEN": "xxxxxxxxxx",
    "AWS_XRAY_CONTEXT_MISSING": "LOG_ERROR",
    "AWS_XRAY_DAEMON_ADDRESS": "169.254.79.129:2000",
    "LAMBDA_RUNTIME_DIR": "/var/runtime",
    "LAMBDA_TASK_ROOT": "/var/task",
    "LANG": "en_US.UTF-8",
    "LD_LIBRARY_PATH": "/var/lang/lib:/lib64:/usr/lib64:/var/runtime:/var/runtime/lib:/var/task:/var/task/lib:/opt/lib",
    "PATH": "/var/lang/bin:/usr/local/bin:/usr/bin/:/bin:/opt/bin",
    "PWD": "/var/task",
    "PYTHONPATH": "/var/runtime:/tmp/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-2023-12-14-10-36-37",
    "SHLVL": "0",
    "TZ": ":UTC"
}

개발 시점

포인트 ① 개발 전에 Systems Manager Automation runbook reference에서 사용할 수 있는 런북이 있는지 확인

Systems Manager Automation runbook reference - AWS Systems Manager Automation runbook reference 에서는 AWS가 관리되는 런북을 제공합니다.
독자적으로 Python을 코딩하여 처리를 정의하는 것도 좋지만, 먼저 관리되는 기능을 구현할 수 있는지 검토하는 것이 중요합니다.

포인트 ② 실행 시간을 가능한 한 단축하기 위해 병렬 실행이나 대기 처리를 검토한다.

aws:executeScript 스텝에서는 내부적으로 Lambda 가 동작하고 있기 때문에, 병렬 실행용의 모듈마저 이용하면 병렬 실행이 가능합니다.
concurrent.futures 모듈을 사용하여 병렬 실행으로 처리 시간을 단축하는 것을 고려해 봅시다.
aws:executeScript 스텝 안에서 대기 처리를 실행해 버리면, 대기하고 있는 시간도 과금이 발생해 버리기 때문에, 런북으로 정의하는 스텝을 분할하는 것으로 대기 스텝을 추가하겠습니다.
대기 처리는 aws:waitForAwsResourceProperty 단계에서 AWS 리소스의 상태를 기다리거나 aws:sleep 단계에서 절전 모드를 선택할 수 있습니다.
aws:waitForAwsResourceProperty – AWS 리소스 속성 대기 - AWS Systems Manager
긴 대기 시간은 EventBridge Scheduler를 사용하여 특정 날짜와 시간에 다시 자동화를 수행하는 것도 고려합니다.
aws:executeScript 스텝의 최대 실행 시간은 15분이 아니라 10분이므로 주의해 주세요.
aws:executeScript – 스크립트 실행 - AWS Systems Manager

포인트 ③ Output 출력을 최적화하여 디버깅을 가능하게 한다

aws:executeScript 단계에서 실행할 때의 로그는 로그를 외부 출력하여 CloudWatch Logs 등에 출력하지 않는 한 간단하게 볼 수 없습니다.
에러가 발생하면 에러 출력을 볼 수 있습니다.
정상 종료시의 디버그 로그를 SSM 자동화 실행 화면에서 표시시키는 경우, 엔트리 포인트가 되는 함수의 반환값에 디버그 레벨의 정보를 포함하는 것으로 SSM 자동화 실행 화면에 표시시킬 수 있습니다.

포인트 ④ 파일의 출력이 필요한 경우, `/tmp` 디렉토리를 이용하는 것

앞서 언급했듯이 SSM 자동화 실행 환경은 내부적으로 Lambda가 실행되고 있습니다.무언가 파일을 처리하는 경우, /tmp 디렉토리를 이용합시다.
참고: Lambda 격리 기술 - AWS Lambda 보안 개요

포인트 ⑤ AWS API 의 `Describe` `List` 를 실행할 때는 `paginator` 를 이용하는 것

SSM 오토메이션만이라기보다는 AWS의 자동화 처리를 하는 스크립트를 개발하는데 있어서의 포인트가 됩니다만, 읽기의 API 중, Describe* List* 를 실행하는 경우, 반환값의 사이즈 제한에 주의할 필요가 있습니다.
paginator 를 이용하는 것으로, pagination 가 발생하는 API 의 처리를 심플하게 정의하는 것이 가능합니다.
참고: boto3에서 pagination이 발생하는 API를 좋은 느낌으로 처리한다 #Python - Qiita