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
작업에는 다음과 같은 사전 설치된 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 파일에 저장해야 합니다.
- 런타임
-
제공된 스크립트를 실행하는 데 사용할 런타임 언어.
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 객체입니다. 이 스크립트에 입력 데이터를 전달하는 데 사용할 수 있습니다.
유형: 문자열
필수 여부: 아니요
- 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
첨부 파일을 사용하여 런북 생성
다음 단계에 따라 첨부 파일을 사용하는 런북을 생성합니다.
-
Amazon S3에 첨부 파일 업로드
자동화 역할이 액세스할 수 있는 S3 버킷에 스크립트 파일 또는 zip 패키지를 업로드하세요. 다음 단계에서 사용할 수 있도록 S3 URI를 기록하세요.
aws s3 cp my-automation-package.zip s3://my-automation-bucket/scripts/
-
첨부 파일 체크섬 계산
보안 확인을 위해 첨부 파일의 SHA-256 체크섬을 계산하세요.
# Linux/macOS shasum -a 256 my-automation-package.zip # Windows PowerShell Get-FileHash -Algorithm SHA256 my-automation-package.zip
-
런북에서 파일 섹션 정의
런북의 최상위에
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"
-
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 블록을 사용하여 예외를 정상적으로 처리하고 유용한 오류 메시지를 제공합니다.