기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # AWS Step Functions에서 AWS Systems Manager Automation 작업을 동기적으로 실행 *Elie El khoury, Amazon Web Services* ## 요약 이 패턴은 AWS Step Functions 와를 통합하는 방법을 설명합니다 AWS Systems Manager. AWS SDK 서비스 통합을 사용하여 상태 시스템 워크플로의 작업 토큰으로 Systems Manager **startAutomationExecution** API를 호출하고 토큰이 성공 또는 실패 호출로 반환될 때까지 일시 중지합니다. 통합을 시연하기 위해 이 패턴은 `AWS-RunShellScript` 문서 주변에 자동화 문서(런북) 래퍼를 구현하고 `AWS-RunPowerShellScript`을 사용하여 를 동기적으로 직접 호출합니다. Step Functions의 AWS SDK 서비스 통합에 대한 자세한 내용은 [AWS Step Functions 개발자 안내서](https://docs.aws.amazon.com/step-functions/latest/dg/supported-services-awssdk.html)를 참조하세요. Step Functions****는 분산 애플리케이션을 구축하고, IT 및 비즈니스 프로세스를 자동화하고, 서비스를 사용하여 데이터 및 기계 학습 파이프라인을 구축하는 데 사용할 수 있는 로우코드 시각적 워크플로 AWS 서비스입니다. 워크플로는 장애, 재시도, 병렬화, 서비스 통합 및 관찰성을 관리하므로 더 중요한 비즈니스 로직에 집중할 수 있습니다. 의 기능인 Automation은 Amazon Elastic Compute Cloud(Amazon EC2), Amazon Relational Database Service(Amazon RDS), Amazon Redshift 및 Amazon Simple Storage Service(Amazon S3) AWS 서비스 와 같은에 대한 일반적인 유지 관리, 배포 및 문제 해결 작업을 AWS Systems Manager간소화합니다. Automation을 사용하면 자동화의 동시성을 세부적으로 제어할 수 있습니다. 예를 들어 동시에 대상으로 지정할 리소스 수와 자동화가 중지되기 전에 발생할 수 있는 오류 수를 지정할 수 있습니다. 런북 단계, 파라미터 및 예제를 포함한 구현 세부 정보는 [추가 정보](#run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions-additional) 섹션을 참조하십시오. ## 사전 조건 및 제한 사항 **사전 조건 ** + 활성 AWS 계정 + AWS Identity and Access Management Step Functions 및 Systems Manager에 액세스할 수 있는 (IAM) 권한 + 인스턴스에 AWS Systems Manager Agent(SSM Agent)가 [설치](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-agent.html)된 EC2 인스턴스 + 런북을 실행하려는 인스턴스에 연결된 [Systems Manager용 IAM 인스턴스 프로파일](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html) + 다음과 같은 IAM 권한을 가진 Step Functions 역할(최소 권한 원칙 준수). ``` { "Effect": "Allow", "Action": "ssm:StartAutomationExecution", "Resource": "*" } ``` **제품 버전** + SSM 문서 스키마 버전 0.3 이상 + SSM Agent 버전 2.3.672.0 이상 ## 아키텍처 **대상 기술 스택  ** + AWS Step Functions + AWS Systems Manager 자동화 **대상 아키텍처 ** ![Step Functions에서 Systems Manager 자동화 작업을 동기적으로 실행하기 위한 아키텍처](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/images/pattern-img/47c19e4f-d68d-4f91-bb68-202098757529/images/2d248aae-d858-4565-8af2-593cde0da780.png) **자동화 및 규모 조정** + 이 패턴은 여러 인스턴스에 실행서를 배포하는 데 사용할 수 있는 AWS CloudFormation 템플릿을 제공합니다. (GitHub [Step Functions 및 Systems Manager 구현](https://github.com/aws-samples/amazon-stepfunctions-ssm-waitfortasktoken) 리포지토리를 참조하십시오.) ## 도구 **AWS 서비스** + [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)를 사용하면 AWS 리소스를 설정하고, 빠르고 일관되게 프로비저닝하고, AWS 계정 및 리전의 수명 주기 동안 리소스를 관리할 수 있습니다. + [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)는 AWS 리소스에 대한 액세스를 인증하고 사용할 수 있는 권한을 부여받은 사용자를 제어하여 리소스에 대한 액세스를 안전하게 관리하는 데 도움이 됩니다. + [AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)는 AWS Lambda 함수 및 기타를 결합하여 비즈니스 크리티컬 애플리케이션을 구축하는 AWS 서비스 데 도움이 되는 서버리스 오케스트레이션 서비스입니다. + [AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html)은 AWS 클라우드에서 실행되는 애플리케이션 및 인프라를 관리하는 데 도움을 줍니다. 애플리케이션 및 리소스 관리를 간소화하고, 운영 문제를 감지 및 해결하는 시간을 단축하며, AWS 리소스를 대규모로 안전하게 관리하는 데 도움이 됩니다. **코드 ** 이 패턴의 코드는 GitHub [Step Functions 및 Systems Manager 구현](https://github.com/aws-samples/amazon-stepfunctions-ssm-waitfortasktoken) 리포지토리에서 사용할 수 있습니다.  ## 에픽 ### 런북 생성 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | CloudFormation 템플릿 파일을 다운로드하십시오. | GitHub 리포지토리의 `cloudformation ` 폴더에서 `ssm-automation-documents.cfn.json` 템플릿을 다운로드합니다. | AWS DevOps | | 런북을 생성하십시오. | 에 로그인하고 [CloudFormation 콘솔](https://console.aws.amazon.com/cloudformation/)을 AWS Management Console연 다음 템플릿을 배포합니다. CloudFormation 템플릿 배포에 대한 자세한 내용은 CloudFormation 설명서의 [CloudFormation 콘솔에서 스택 생성을](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html) 참조하세요. 
CloudFormation 템플릿은 세 가지 리소스를 배포합니다.[See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions.html) | DevOps | ### 샘플 상태 머신 생성 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | 테스트 상태 머신을 생성하십시오. | [AWS Step Functions AWS Step Functions 개발자 안내서](https://docs.aws.amazon.com/step-functions/latest/dg/getting-started-with-sfn.html)의 지침에 따라 상태 머신을 생성하고 실행하십시오. 정의를 위해 다음 코드를 사용하십시오. 계정에 있는 유효한 Systems Manager 활성화 인스턴스의 ID로 `InstanceIds` 값을 업데이트해야 합니다.
{
  "Comment": "A description of my state machine",
  "StartAt": "StartAutomationWaitForCallBack",
  "States": {
    "StartAutomationWaitForCallBack": {
      "Type": "Task",
      "Resource": "arn:aws:states:::aws-sdk:ssm:startAutomationExecution.waitForTaskToken",
      "Parameters": {
        "DocumentName": "SfnRunCommandByInstanceIds",
        "Parameters": {
          "InstanceIds": [
            "i-1234567890abcdef0"
          ],
          "taskToken.$": "States.Array($$.Task.Token)",
          "workingDirectory": [
            "/home/ssm-user/"
          ],
          "Commands": [
            "echo \"This is a test running automation waitForTaskToken\" >> automation.log",
            "sleep 100"
          ],
          "executionTimeout": [
              "10800"
          ],
          "deliveryTimeout": [
              "30"
          ],
          "shell": [
              "Shell"
          ]
            }
      },
      "End": true
    }
  }
}

이 코드는 런북을 직접 호출하여 Systems Manager Automation에 대한 `waitForTaskToken` 직접 호출을 보여주는 두 개의 명령을 실행합니다.
`shell` 파라미터 값(`Shell` 또는 `PowerShell`)은 자동화 문서가 `AWS-RunShellScript` 또는를 실행할지 여부를 결정합니다`AWS-RunPowerShellScript`.
작업은 `/home/ssm-user/automation.log` 파일에 “이것은 자동화 WaitForTaskToken을 실행하는 테스트입니다”라고 쓴 다음, 100초 동안 휴면 상태로 있다가 작업 토큰으로 응답하여 워크플로에서 다음 작업을 릴리스합니다.
대신 `SfnRunCommandByTargets` 런북을 직접 호출하려면 이전 코드의 `Parameters` 섹션을 다음과 같이 바꾸십시오.
"Parameters": {
          "Targets": [
            {
              "Key": "InstanceIds",
              "Values": [
                "i-02573cafcfEXAMPLE",
                "i-0471e04240EXAMPLE"
              ]
            }
          ],
| AWS DevOps | | 상태 머신의 IAM 역할을 업데이트합니다. | 이전 단계에서는 상태 머신을 위한 전용 IAM 역할을 자동으로 생성합니다. 하지만 런북 직접 호출 권한은 부여하지 않습니다. 다음 권한을 추가하여 역할을 업데이트합니다.
{
      "Effect": "Allow",
      "Action": "ssm:StartAutomationExecution",
      "Resource": "*"
 }
| AWS DevOps | | 동기 직접 호출을 검증합니다. | 상태 머신을 실행하여 Step Functions와 Systems Manager Automation 간의 동기 직접 호출을 검증합니다. 
샘플 출력은 [추가 정보](#run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions-additional) 섹션을 참조하십시오.  | AWS DevOps | ## 관련 리소스 + [시작하기 AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/getting-started-with-sfn.html)(*AWS Step Functions 개발자 안내서*) + [작업 토큰을 사용하여 콜백 대기](https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token)(*AWS Step Functions 개발자 안내서*, 서비스 통합 패턴) + [send\_task\_success](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_success.html) 및 [send\_task\_failure](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_failure.html) API 직접 호출(Boto3 설명서)  + [AWS Systems Manager 자동화](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-automation.html)(*AWS Systems Manager 사용 설명서*) ## 추가 정보 **구현 세부 정보** 이 패턴은 두 개의 Systems Manager 런북을 배포하는 AWS CloudFormation 템플릿을 제공합니다. + `SfnRunCommandByInstanceIds`가 인스턴스 ID를 사용하여 명령을 실행합니다. + `SfnRunCommandByTargets`이 대상을 사용하여 명령을 실행합니다. 각 런북은 Step Functions의 `.waitForTaskToken` 옵션을 사용할 때 동기 직접 호출을 달성하기 위한 세 단계를 구현합니다. | | | 단계 | 작업 | 설명 | | --- |--- |--- | | **1** | `Branch` | `shell` 파라미터 값(`Shell` 또는 `PowerShell`)을 확인하여 Linux`AWS-RunShellScript`용 또는 Windows`AWS-RunPowerShellScript`용를 실행할지 결정합니다. | | **2** | `RunCommand_Shell` 또는 `RunCommand_PowerShell` | 여러 입력을 가져와`RunShellScript`서 또는 `RunPowerShellScript` 명령을 실행합니다. 자세한 내용은 Systems Manager 콘솔에서 세부 **정보** 탭에서 `RunCommand_Shell` 또는 `RunCommand_PowerShell` 자동화 문서를 확인하세요. | | **3** | `SendTaskFailure` | 2단계가 중단되거나 취소될 때 실행됩니다. Step Functions [send\_task\_failure](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_failure.html) API를 직접 호출하며, 이 API는 상태 머신이 전달한 토큰, 실패 오류, 실패 원인에 대한 설명이라는 세 가지 파라미터를 입력으로 받아들입니다. | | **4** | `SendTaskSuccess` | 2단계가 성공하면 실행됩니다. 상태 머신이 전달한 토큰을 입력으로 받아들이는 Step Functions [send\_task\_success](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_success.html) API를 직접 호출합니다. | **런북 파라미터** `SfnRunCommandByInstanceIds` 런북 | | | 파라미터 이름 | Type | 선택 또는 필수 | 설명 | | --- |--- |--- |--- | | `shell` | 문자열 | 필수 | 인스턴스 쉘은 Linux`AWS-RunShellScript`용 또는 Windows`AWS-RunPowerShellScript`용를 실행할지 여부를 결정합니다. | | `deliveryTimeout` | Integer | 선택 사항 | 명령이 인스턴스의 에 전송될 때까지 대기하는 시간(초)입니다. 이 파라미터의 최소값은 30(0.5분)이고 최대값은 2592000(720시간)입니다. | | `executionTimeout` | 문자열 | 선택 사항 | 명령이 실패로 간주되기 전에 완료해야 할 시간(초). 기본값은 1시간입니다. 최댓값은 172,800(48시간)입니다. | | `workingDirectory` | 문자열 | 선택 사항 | 인스턴스 상의 작업 디렉터리에 대한 경로. | | `Commands` | StringList | 필수 | 실행할 쉘 스크립트 또는 명령. | | `InstanceIds` | StringList | 필수 | 명령을 실행하려고 하는 인스턴스의 ID. | | `taskToken` | 문자열 | 필수 | 콜백 응답에 사용할 작업 토토큰. | `SfnRunCommandByTargets` 런북 | | | 이름 | Type | 선택 또는 필수 | 설명 | | --- |--- |--- |--- | | `shell` | 문자열 | 필수 | 인스턴스 쉘은 Linux`AWS-RunShellScript`용 또는 Windows`AWS-RunPowerShellScript`용를 실행할지 여부를 결정합니다. | | `deliveryTimeout` | Integer | 선택 사항 | 명령이 인스턴스의 에 전송될 때까지 대기하는 시간(초)입니다. 이 파라미터의 최소값은 30(0.5분)이고 최대값은 2592000(720시간)입니다. | | `executionTimeout` | Integer | 선택 사항 | 명령이 실패로 간주되기 전에 완료해야 할 시간(초). 기본값은 1시간입니다. 최댓값은 172,800(48시간)입니다. | | `workingDirectory` | 문자열 | 선택 사항 | 인스턴스 상의 작업 디렉터리에 대한 경로. | | `Commands` | StringList | 필수 | 실행할 쉘 스크립트 또는 명령. | | `Targets` | MapList | 필수 | 지정한 키,값 쌍을 사용하여 인스턴스를 식별하는 검색 기준 배열. 예: `[{"Key":"InstanceIds","Values":["i-02573cafcfEXAMPLE","i-0471e04240EXAMPLE"]}]` | | `taskToken` | 문자열 | 필수 | 콜백 응답에 사용할 작업 토토큰. | **샘플 출력** 다음 테이블에는 step 함수의 샘플 출력이 나와 있습니다. 이는 5단계(`TaskSubmitted`)와 6단계(`TaskSucceeded`) 사이의 총 실행 시간이 100초 이상임을 보여줍니다. 이는 step 함수가 워크플로의 다음 작업으로 이동하기 전에 ‘sleep 100’ 명령이 완료될 때까지 기다렸다는 것을 보여줍니다. | | | ID | Type | 단계 | Resource | 경과 시간(밀리 초) | 타임스탬프 | | --- |--- |--- |--- |--- |--- | | **1** | `ExecutionStarted` | | - | 0 | 2022년 3월 11일 오후 02:50:34. 303 | | **2** | `TaskStateEntered` | `StartAutomationWaitForCallBack` | - | 40 | 2022년 3월 11일 오후 02:50:34. 343 | | **3** | `TaskScheduled` | `StartAutomationWaitForCallBack` | - | 40 | 2022년 3월 11일 오후 02:50:34. 343 | | **4** | `TaskStarted` | `StartAutomationWaitForCallBack` | - | 154 | 2022년 3월 11일 오후 02:50:34. 457 | | **5** | `TaskSubmitted` | `StartAutomationWaitForCallBack` | - | 657 | 2022년 3월 11일 오후 02:50:34. 960 | | **6** | `TaskSucceeded` | `StartAutomationWaitForCallBack` | - | 103835 | 2022년 3월 11일 오후 02:52:18. 138 | | **7** | `TaskStateExited` | `StartAutomationWaitForCallBack` | - | 103860 | 2022년 3월 11일 오후 02:52:18. 163 | | **8** | `ExecutionSucceeded` | | - | 103897 | 2022년 3월 11일 오후 02:52:18. 200 |