aws:executeScript - 스크립트 실행 - AWS Systems Manager
aws:executeScript에서 첨부 파일 사용aws:executeScript 첨부 파일 예제aws:executeScript 첨부 파일 문제 해결

aws:executeScript - 스크립트 실행

지정된 런타임 및 핸들러를 사용하여 제공된 Python 또는 PowerShell 스크립트를 실행합니다. 각 aws:executeScript 작업은 최대 600초(10분)까지 실행할 수 있습니다. aws:executeScript 단계에서 timeoutSeconds 파라미터를 지정하여 시간 제한을 제한할 수 있습니다.

함수에서 return 문을 사용하여 출력 페이로드에 출력을 추가합니다. aws:executeScript 작업에 대한 출력 정의 예시는 예제 2: 스크립팅된 실행서의 내용을 참조하세요. 실행서에 있는 aws:executeScript 작업의 출력을 지정하는 Amazon CloudWatch Logs 로그 그룹으로 전송할 수 있습니다. 자세한 정보는 CloudWatch Logs로 Automation 작업 출력 로깅 섹션을 참조하세요.

aws:executeScript 작업에서 CloudWatch Logs로 출력을 전송하거나 aws:executeScript 작업에 대해 지정한 스크립트가 AWS API 작업을 호출하는 경우, 런북을 실행하려면 AWS Identity and Access Management(IAM) 서비스 역할(또는 역할 수임)이 항상 필요합니다.

참고

aws:executeScript 작업은 자동 스로틀링 재시도를 지원하지 않습니다. 스크립트가 스로틀링될 수 있는 AWS API 호출을 수행하는 경우 스크립트 코드에 자체 재시도 로직을 구현해야 합니다.

aws:executeScript 작업에는 다음과 같은 사전 설치된 PowerShell Core 모듈이 포함되어 있습니다.

  • Microsoft.PowerShell.Host

  • Microsoft.PowerShell.Management

  • Microsoft.PowerShell.Security

  • Microsoft.PowerShell.Utility

  • PackageManagement

  • PowerShellGet

사전 설치되지 않은 PowerShell Core 모듈을 사용하려면 스크립트에서 다음 명령과 같이 -Force 플래그를 사용하여 모듈을 설치해야 합니다. AWSPowerShell.NetCore 모듈은 지원되지 않습니다. ModuleName을 설치하려는 모듈로 바꿉니다.

Install-Module ModuleName -Force

스크립트에서 PowerShell Core cmdlet을 사용하려면 다음 명령과 같이 AWS.Tools 모듈을 사용하는 것이 좋습니다. 각 example resource placeholder를 사용자의 정보로 바꿉니다.

  • Amazon S3 cmdlet입니다.

    Install-Module AWS.Tools.S3 -Force
Get-S3Bucket -BucketName amzn-s3-demo-bucket

  • Amazon EC2 cmdlet.

    Install-Module AWS.Tools.EC2 -Force
Get-EC2InstanceStatus -InstanceId instance-id

  • 공통 또는 서비스 독립적 AWS Tools for Windows PowerShell cmdlet입니다.

    Install-Module AWS.Tools.Common -Force
Get-AWSRegion

스크립트에서 PowerShell Core cmdlet을 사용하는 것 외에 새 객체를 초기화하는 경우 다음 명령과 같이 모듈도 가져와야 합니다.

Install-Module AWS.Tools.EC2 -Force
Import-Module AWS.Tools.EC2

$tag = New-Object Amazon.EC2.Model.Tag
$tag.Key = "Tag"
$tag.Value = "TagValue"

New-EC2Tag -Resource i-02573cafcfEXAMPLE -Tag $tag

AWS.Tools 모듈 설치와 가져오기 및 실행서의 PowerShell Core cmdlet 사용 예는 Automation 런북의 시각적 디자인 경험 섹션을 참조하세요.

입력

스크립트를 실행하는 데 필요한 정보를 입력합니다. 각 example resource placeholder를 사용자의 정보로 바꿉니다.

참고

Python 스크립트의 첨부 파일은 스크립트가 포함된 .py 파일 또는 .zip 파일일 수 있습니다. PowerShell 스크립트는.zip 파일에 저장해야 합니다.

YAML
action: "aws:executeScript"
inputs: 
 Runtime: runtime
 Handler: "functionName"
 InputPayload: 
  scriptInput: '{{parameterValue}}'
 Script: |-
   def functionName(events, context):
   ...
 Attachment: "scriptAttachment.zip"
JSON
{
    "action": "aws:executeScript",
    "inputs": {
        "Runtime": "runtime",
        "Handler": "functionName",
        "InputPayload": {
            "scriptInput": "{{parameterValue}}"
        },
        "Attachment": "scriptAttachment.zip"
    }
}
런타임

제공된 스크립트를 실행하는 데 사용할 런타임 언어. aws:executeScript에서는 Python 3.7(python3.7), Python 3.8(python3.8), Python 3.9(python3.9), Python 3.10(python3.10), Python 3.11(python3.11) PowerShell Core 6.0(dotnetcore2.1), PowerShell 7.0(dotnetcore3.1) 스크립트, PowerShell 7.4(dotnet8) 스크립트를 지원합니다.

지원되는 값: python3.7 | python3.8 | python3.9 | python3.10 | python3.11 | PowerShell Core 6.0 | PowerShell 7.0 | PowerShell 7.4

유형: 문자열

필수 여부: 예

참고

Python 런타임의 경우 이 환경은 512MB의 메모리와 512MB의 디스크 공간을 제공합니다. PowerShell 런타임의 경우 이 환경은 1,024MB의 메모리와 512MB의 디스크 공간을 제공합니다.

핸들러

함수의 이름입니다. 핸들러에 정의된 함수에 두 개의 파라미터 events과 context가 있는지 확인해야 합니다. PowerShell 런타임은 이 파라미터를 지원하지 않습니다.

유형: 문자열

필수: 예(Python) | 지원되지 않음(PowerShell)

InputPayload

핸들러의 첫 번째 파라미터로 전달되는 JSON 또는 YAML 객체입니다. 이 스크립트에 입력 데이터를 전달하는 데 사용할 수 있습니다.

유형: 문자열

필수 여부: 아니요

Python
description: Tag an instance
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
    AutomationAssumeRole:
        type: String
        description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
    InstanceId:
        type: String
        description: (Required) The ID of the EC2 instance you want to tag.
mainSteps:
  - name: tagInstance
    action: 'aws:executeScript'
    inputs:
        Runtime: "python3.11"
        Handler: tagInstance
        InputPayload:
            instanceId: '{{InstanceId}}'
        Script: |-
          def tagInstance(events,context):
            import boto3

            #Initialize client
            ec2 = boto3.client('ec2')
            instanceId = events['instanceId']
            tag = {
                "Key": "Env",
                "Value": "ExamplePython"
            }
            print(f"Adding tag {tag} to instance id {instanceId}")
            ec2.create_tags(
                Resources=[instanceId],
                Tags=[tag]
            )
            return tag
    outputs:
      - Type: String
        Name: TagKey
        Selector: $.Payload.Key
outputs:
  - tagInstance.TagKey
PowerShell
description: Tag an instance
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
  AutomationAssumeRole:
    type: String
    description: (Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.
  InstanceId:
    type: String
    description: (Required) The ID of the EC2 instance you want to tag.
mainSteps:
  - name: tagInstance
    action: aws:executeScript
    isEnd: true
    inputs:
      Runtime: PowerShell 7.0
      InputPayload:
        instanceId: '{{InstanceId}}'
      Script: |-
        Install-Module AWS.Tools.EC2 -Force
        Import-Module AWS.Tools.EC2

        $input = $env:InputPayload | ConvertFrom-Json

        $tag = New-Object Amazon.EC2.Model.Tag
        $tag.Key = "Env"
        $tag.Value = "ExamplePowerShell"

        Write-Information "Adding tag key: $($tag.Key) and value: $($tag.Value) to instance id $($input.instanceId)"
        New-EC2Tag -Resource $input.instanceId -Tag $tag

        return $tag
    outputs:
      - Type: String
        Name: TagKey
        Selector: $.Payload.Key
outputs:
  - tagInstance.TagKey
Script

자동화 중 실행할 기본 제공 스크립트입니다.

유형: 문자열

필수: 아니오(Python) | 예(PowerShell)

연결

작업에서 호출될 수 있는 독립형 스크립트 파일 또는.zip 파일의 이름입니다. Attachments 요청 파라미터에서 지정한 문서 첨부 파일의 Name과 동일한 값을 지정합니다. 자세한 내용은 AWS Systems Manager API 참조의 첨부 파일을 참조하세요. 첨부 파일을 사용하여 스크립트를 제공하는 경우 런북의 최상위 수준 요소에서 files 섹션 또한 정의해야 합니다. 자세한 정보는 스키마 버전 0.3 섹션을 참조하세요.

Python용 파일을 호출하려면 Handler에서 filename.method_name 형식을 사용합니다.

참고

Python 스크립트의 첨부 파일은 스크립트가 포함된 .py 파일 또는 .zip 파일일 수 있습니다. PowerShell 스크립트는.zip 파일에 저장해야 합니다.

첨부 파일에 Python 라이브러리를 포함할 때 각 모듈 디렉터리에 빈 __init__.py 파일을 추가하는 것이 좋습니다. 이를 통해 스크립트 내용 내 첨부 파일의 라이브러리에서 모듈을 가져올 수 있습니다. 예: from library import module

유형: 문자열

필수 여부: 아니요

출력
페이로드

함수에서 반환된 객체의 JSON 표현입니다. 최대 100KB가 반환됩니다. 목록을 출력하는 경우 최대 100개의 항목이 반환됩니다.

aws:executeScript에서 첨부 파일 사용

첨부 파일은 복잡한 스크립트, 여러 모듈 및 외부 종속 항목을 aws:executeScript 작업에서 패키징하고 재사용할 수 있는 강력한 방법을 제공합니다. 다음을 수행해야 경우 첨부 파일을 사용합니다.

  • 여러 Python 모듈 또는 PowerShell 스크립트를 함께 패키징합니다.

  • 여러 런북에서 동일한 스크립트 로직을 재사용합니다.

  • 스크립트에 외부 라이브러리 또는 종속 항목을 포함합니다.

  • 복잡한 스크립트 로직을 분리하여 런북 정의를 정리합니다.

  • 여러 팀 또는 자동화 워크플로에서 스크립트 패키지를 공유합니다.

첨부 파일 구조 및 패키징

단일 파일 또는 여러 파일이 포함된 zip 패키지를 첨부할 수 있습니다. 구조는 사용 사례에 따라 달라집니다.

단일 파일의 첨부 파일

간단한 스크립트의 경우 단일 .py 파일(Python) 또는 단일 PowerShell 스크립트가 포함된 .zip 파일을 첨부할 수 있습니다.

다중 모듈 패키지

여러 모듈이 필요한 복잡한 자동화의 경우 다음과 같은 권장 구조의 zip 패키지를 생성합니다.

my-automation-package.zip
├── main.py                    # Entry point script
├── utils/
│   ├── __init__.py           # Required for Python module imports
│   ├── helper_functions.py   # Utility functions
│   └── aws_operations.py     # AWS-specific operations
├── config/
│   ├── __init__.py
│   └── settings.py           # Configuration settings
└── requirements.txt          # Optional: document dependencies
중요

Python 패키지의 경우 Python 모듈이 포함된 각 디렉터리에 빈 __init__.py 파일을 포함해야 합니다. 이렇게 하면 표준 Python 가져오기 구문(예: from utils import helper_functions)을 사용하여 모듈을 가져올 수 있습니다.

PowerShell 패키지 구조

PowerShell 첨부 파일은 다음과 같은 구조의 zip 파일로 패키징되어야 합니다.

my-powershell-package.zip
├── Main.ps1                  # Entry point script
├── Modules/
│   ├── HelperFunctions.ps1   # Utility functions
│   └── AWSOperations.ps1     # AWS-specific operations
└── Config/
    └── Settings.ps1          # Configuration settings

첨부 파일을 사용하여 런북 생성

다음 단계에 따라 첨부 파일을 사용하는 런북을 생성합니다.

  1. Amazon S3에 첨부 파일 업로드

    자동화 역할이 액세스할 수 있는 S3 버킷에 스크립트 파일 또는 zip 패키지를 업로드하세요. 다음 단계에서 사용할 수 있도록 S3 URI를 기록하세요.

    aws s3 cp my-automation-package.zip s3://my-automation-bucket/scripts/

  2. 첨부 파일 체크섬 계산

    보안 확인을 위해 첨부 파일의 SHA-256 체크섬을 계산하세요.

    # Linux/macOS
shasum -a 256 my-automation-package.zip

# Windows PowerShell
Get-FileHash -Algorithm SHA256 my-automation-package.zip

  3. 런북에서 파일 섹션 정의

    런북의 최상위에 files 섹션을 추가하여 첨부 파일을 참조하세요.

    files:
  my-automation-package.zip:
    sourceType: "S3"
    sourceInfo:
      path: "s3://my-automation-bucket/scripts/my-automation-package.zip"
      checksums:
        sha256: "your-calculated-checksum-here"

  4. executeScript 단계에서 첨부 파일 참조

    Attachment 파라미터를 사용하여 업로드된 파일을 참조하세요.

    - name: runMyScript
  action: aws:executeScript
  inputs:
    Runtime: python3.11
    Handler: main.process_data
    Attachment: my-automation-package.zip
    InputPayload:
      inputData: "{{InputParameter}}"

aws:executeScript 첨부 파일 예제

다음 예제에서는 aws:executeScript 작업에서 첨부 파일을 사용하는 다양한 방법을 보여줍니다.

예제 1: 단일 파일 연결

이 예제에서는 단일 Python 파일을 첨부 파일로 사용하여 EC2 인스턴스 데이터를 처리하는 방법을 보여줍니다.

첨부 파일: process_instance.py

다음 콘텐츠가 포함된 Python 파일을 생성합니다.

import boto3
import json

def process_instance_data(events, context):
    """Process EC2 instance data and return formatted results."""
    try:
        instance_id = events.get('instanceId')
        if not instance_id:
            raise ValueError("instanceId is required")
        
        ec2 = boto3.client('ec2')
        
        # Get instance details
        response = ec2.describe_instances(InstanceIds=[instance_id])
        instance = response['Reservations'][0]['Instances'][0]
        
        # Format the response
        result = {
            'instanceId': instance_id,
            'instanceType': instance['InstanceType'],
            'state': instance['State']['Name'],
            'availabilityZone': instance['Placement']['AvailabilityZone'],
            'tags': {tag['Key']: tag['Value'] for tag in instance.get('Tags', [])}
        }
        
        print(f"Successfully processed instance {instance_id}")
        return result
        
    except Exception as e:
        print(f"Error processing instance: {str(e)}")
        raise
런북 완료

다음은 단일 파일의 첨부 파일을 사용하는 전체 런북입니다.

description: Process EC2 instance data using single file attachment
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
  AutomationAssumeRole:
    type: String
    description: (Required) IAM role for automation execution
  InstanceId:
    type: String
    description: (Required) EC2 instance ID to process

files:
  process_instance.py:
    sourceType: "S3"
    sourceInfo:
      path: "s3://my-automation-bucket/scripts/process_instance.py"
      checksums:
        sha256: "abc123def456..."

mainSteps:
  - name: processInstance
    action: aws:executeScript
    inputs:
      Runtime: python3.11
      Handler: process_instance.process_instance_data
      Attachment: process_instance.py
      InputPayload:
        instanceId: '{{InstanceId}}'
    outputs:
      - Type: StringMap
        Name: InstanceData
        Selector: $.Payload

outputs:
  - processInstance.InstanceData

예제 2: 다중 모듈 패키지

이 예제에서는 복잡한 S3 버킷 작업을 위해 여러 Python 모듈을 포함하는 zip 패키지를 사용하는 방법을 보여줍니다.

패키지 구조

다음 구조의 zip 패키지를 생성합니다.

s3-operations.zip
├── main.py
├── utils/
│   ├── __init__.py
│   ├── s3_helper.py
│   └── validation.py
└── config/
    ├── __init__.py
    └── settings.py
main.py(진입 지점)

작업을 오케스트레이션하는 기본 스크립트:

from utils.s3_helper import S3Operations
from utils.validation import validate_bucket_name
from config.settings import get_default_settings

def cleanup_s3_bucket(events, context):
    """Clean up S3 bucket based on specified criteria."""
    try:
        bucket_name = events.get('bucketName')
        max_age_days = events.get('maxAgeDays', 30)
        
        # Validate inputs
        if not validate_bucket_name(bucket_name):
            raise ValueError(f"Invalid bucket name: {bucket_name}")
        
        # Initialize S3 operations
        s3_ops = S3Operations()
        settings = get_default_settings()
        
        # Perform cleanup
        deleted_objects = s3_ops.delete_old_objects(
            bucket_name, 
            max_age_days,
            settings['dry_run']
        )
        
        result = {
            'bucketName': bucket_name,
            'deletedCount': len(deleted_objects),
            'deletedObjects': deleted_objects[:10],  # Return first 10 for brevity
            'dryRun': settings['dry_run']
        }
        
        print(f"Cleanup completed for bucket {bucket_name}")
        return result
        
    except Exception as e:
        print(f"Error during S3 cleanup: {str(e)}")
        raise

aws:executeScript 첨부 파일 문제 해결

다음 지침을 사용하여 aws:executeScript 첨부 파일과 관련된 일반적인 문제를 해결합니다.

모듈 가져오기 오류

다중 모듈 패키지를 사용할 때 가져오기 오류를 수신하는 경우:

  • Python 모듈을 포함하는 각 디렉터리에 빈 __init__.py 파일이 포함되어 있는지 확인합니다.

  • import 문이 zip 패키지의 실제 파일 및 디렉터리 구조와 일치하는지 확인합니다.

  • 상대적 가져오기(예: from .utils import helper) 또는 절대적 가져오기(예: from utils import helper)를 일관되게 사용합니다.

첨부 파일 찾을 수 없음 오류

자동화에서 첨부 파일을 찾지 못하는 경우:

  • Attachment 파라미터 값이 files 섹션의 키와 정확히 일치하는지 확인합니다.

  • files 섹션에서 S3 버킷 경로 및 파일 이름이 올바른지 확인합니다.

  • 자동화 역할에 첨부 파일의 S3 위치에 대한 s3:GetObject 권한이 있는지 확인합니다.

  • 런북의 체크섬이 실제 파일 체크섬과 일치하는지 확인합니다.

핸들러 함수 오류

핸들러 관련 오류를 수신하는 경우:

  • Python의 경우: Handler 파라미터에서 filename.function_name 형식을 사용합니다(예: main.process_data).

  • 핸들러 함수가 정확히 두 개의 파라미터(events 및 context)를 수락하는지 확인합니다.

  • PowerShell의 경우: Handler 파라미터를 지정하지 마세요. 스크립트는 직접 실행됩니다.

스크립트 실행 실패

실행 중에 스크립트가 실패하는 경우:

  • 자동화 실행 기록에서 자세한 오류 메시지 및 스택 추적을 확인합니다.

  • print() 문(Python) 또는 Write-Information(PowerShell)을 사용하여 디버깅 출력을 추가합니다.

  • 자동화 역할에 필요한 모든 AWS 권한이 부여되었는지 확인합니다.

  • 첨부 파일로 패키징하기 전에 스크립트 로직을 로컬로 테스트합니다.

종료 코드 및 오류 처리

오류를 올바르게 처리하고 종료 코드를 반환하는 방법:

  • Python의 경우: raise Exception("error message")를 사용하여 스크립트 실패를 나타냅니다.

  • PowerShell의 경우: throw "error message" 또는 Write-Error를 사용하여 실패를 나타냅니다.

  • 함수에서 구조화된 데이터를 반환하여 성공 또는 실패에 대한 세부 정보를 제공합니다.

  • try-catch 블록을 사용하여 예외를 정상적으로 처리하고 유용한 오류 메시지를 제공합니다.