[AWS] Step Functions (SFN)

AWS Step Functions 란

AWS Step Functions는 AWS Lambda 및 다양한 AWS 서비스를 연계해 분산 애플리케이션과 프로세스를 자동화할 수 있는 서버리스 오케스트레이션 서비스입니다.
 
워크플로를 상태 머신(State Machine) 기반의 이벤트 흐름으로 구성하며, 각 단계(State)를 통해 작업을 순차적으로 실행·관리할 수 있으며, 마이크로서비스 오케스트레이션, 데이터 파이프라인, 머신러닝 워크플로 구축 등에 활용됩니다.

• State에서 task를 수행하고, 결과를 다른 task로 전달할 수 있습니다.
• State Machine == Workflow

 
시각적 워크플로를 사용하여 워크플로를 빌드하고 편집할 수도 있으며, ASL이라고도 하는 Amazon States Language를 사용하여 워크플로를 정의할 수 있습니다.

 
 

State Machine / Workflow

workflow에 각 단계를 state라고 하며 state에서 task를 수행하고 결과를 다른 task로 전달할 수 있으며,
State는 두 가지로 Flow states와 Task states 유형이 있습니다.

https://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/concepts-statemachines.html

 

Actions

AWS Lambda 함수 호출, Amazon SNS로의 publish, Amazon ECS task 실행과 같은 다른 AWS 서비스를 활용해 실제 task를 수행합니다.

 

Flow

Flow에서는 task의 제어 흐름을 정의하는데 사용됩니다.

각 Flow가 제어하는 흐름은 아래와 같습니다.

State	뜻	하는 일	코드로 비유	대표 사용 예시
Choice	조건 분기	조건에 따라 다음 실행 경로를 결정	if / else	결제 성공/실패 분기, 상태값 검사
Parallel	병렬 실행	여러 작업을 동시에 실행 후 모두 완료될 때까지 대기	Promise.all()	포인트 차감 + 재고 감소 + 쿠폰 사용 동시 처리
Map	반복 처리	배열(iterable)의 각 요소마다 동일한 작업 수행	forEach, for	주문 목록 반복 처리, 대량 데이터 처리
Pass	그대로 전달	실제 작업 없이 입력 데이터를 다음 state로 전달	return input	테스트, 디버깅, mock 데이터 생성
Wait	대기	일정 시간 또는 특정 시각까지 workflow 실행 중지	sleep()	재시도 대기, polling, 예약 실행
Success (Succeed)	성공 종료	workflow를 정상 종료 상태로 마무리	return success	주문 완료, 처리 성공
Fail	실패 종료	workflow를 실패 상태로 종료	throw error	결제 실패, 검증 실패, 치명적 오류 발생

 

Task

State Machine에서 실행되는 단일 작업 단위로, State Machine의 모든 작업은 task에 의해 수행됩니다.
task는 직접 Lambda 함수를 호출해서 작업을 수행하거나 다른 서비스의 API 작업으로 파라미터를 전달하여 작업을 수행합니다. 
 
다음은 외부 시스템의 callback을 기다린 후 API를 호출하는 WaitForConfirmation라는 states 예시입니다.

• Type(필수) : states의 유형
• Resource : 실행할 AWS 리소스 (Lambda, ECS 등)
• Parameters : Resource에 전달할 입력값
• TimeoutSeconds : 지정 시간 안에 작업이 끝나지 않으면 timeout 발생
• Catch : 에러 발생 시 이동할 states 정의
• ResultPath : 현재 states의 결과를 state 데이터 어디에 저장할지 지정 (null이면 결과 버림)
• Next : 현재 states 종료 후 실행할 다음 states 이름
• End : true면 workflow 종료
• Comment(선택 사항) : states 설명
• InputPath(선택 사항) : 처리를 위해 states 작업에 전달되도록 states의 입력 부분을 선택하는 경로 (생략하는 경우 $)
• OutputPath(선택 사항) : states 출력의 일부를 다음 states로 전달하도록 선택하는 경로 (생략하는 경우 $)

"WaitForConfirmation": {
  "Type": "Task", // 작업 수행 state
  "Resource": "arn:aws:states:::lambda:invoke.waitForTaskToken", // callback 대기 패턴 사용
  "Parameters": {
    "FunctionName": "arn:aws:lambda:ap-northeast-2:<AWS_ACCOUNT_ID>:function:send-task-token-to-server",
    "Payload": {
      "taskToken.$": "$$.Task.Token", // callback용 token 전달
      "requestId.$": "$.requestId"
    }
  },
  "TimeoutSeconds": 300, // 5분 동안 callback 대기
  "Catch": [
    {
      "ErrorEquals": ["States.Timeout"], // timeout 발생 시
      "Next": "TaskExpired" // TaskExpired state로 이동
    }
  ],
  "ResultPath": null, // Lambda 결과 저장 안 함
  "Next": "CallExternalAPI" // callback 성공 시 다음 state 이동
}

의미를 간단히 정리하면 아래와 같습니다.

1. Lambda 실행
2. task token을 외부 서버에 전달
3. 외부 시스템 callback 기다림
4. callback 오면 다음 단계 진행
5. 5분 안 오면 timeout 처리

 

해당 예제를 로컬에서 간단하게 테스트하기

Step Functions에서 테스트할 상태머신에 들어간 다음에 실행 시작 버튼을 눌러 전송할 Request를 보냅니다.

 
람다에서는 event에 내가 전송한 request 정보가 오는지 확인했으며,
callback 패턴으로 사용했을 때 AWS에서 event에 taskToken과 executionArn이 정상적으로 들어오는지 확인했습니다.

• 이후 CallExternalAPI Step에서 호출되는 람다 역시 로그처리만 진행했습니다.

로그를 확인해보니 아래처럼 event안에 taskToken과 executionArn이 전달되는것을 확인할 수 있었습니다.

 
해당 변수들은 아래의 의미를 가지고 있습니다.

• executionArn: Step Functions 실행 인스턴스 식별자
• taskToken: Step Functions의 callback task를 다시 깨우기 위한 토큰
  • 이 토큰이 있어야 서버가 sendTaskSuccess를 호출해 중단된 state machine을 계속 진행시킬 수 있습니다.

 
AWS CLI를 통해 로그에 찍혀있는 taskToken을 사용해서 Step Functions에 요청을 해보겠습니다.

aws stepfunctions send-task-success \
--task-token "{토큰 정보}" \
--task-output '{"status":"SUCCESS"}'

현재 5분의 Timeout이 설정되어 있기 때문에, 해당 시간 내에 taskToken 을 사용해 callback을 전달하면 Step Functions의 Callback Task가 다시 실행 상태로 전환되며 다음 Step으로 정상적으로 진행되는 것을 확인할 수 있습니다.

 
각각의 Step들이 정상적으로 수행되는 모습을 볼 수 있습니다.

• 현재는 InputPath, OutputPath 생략하여 기본값 $로 처리되어 CallExternalAPI Step의 람다에 WaitForConfirmation Step의 람다에 전달했던 request 정보와 taskToken, executionArn 정보가 같이 전달되는것을 확인할 수 있습니다.

 
5분 타임아웃이 넘어가는 경우 TaskExpired Step으로 이동할 수 있도록 설정을 해두었습니다.

따라서 5분이 경과되어 States.Timeout 예외가 발생하는 것을 확인할 수 있었습니다.

 

전체적인 ASL(Amazon States Language) 예시

아래 예시는 회원가입 요청 이후 Lambda 함수를 실행했다고 가정합니다.

회원 조회 Lambda가 호출되어 반환 결과를 기반으로 Choice State 에서 성공 또는 실패로 분기한 뒤, 성공한 경우 환영 이메일을 발송하는 ASL 예시입니다.

 
State Machine은 아래와 같은 구조를 가집니다.

• Comment(선택 사항) : state machine에 대한 설명입니다.
• StartAt(필수) : workflow가 시작될 state 이름입니다. States 내부에 정의된 이름과 정확히 일치해야 합니다.
• TimeoutSeconds(선택 사항) : state machine 실행의 최대 제한 시간(초)입니다.
• Version(선택 사항) : 사용되는 ASL 버전입니다. (기본값 1.0)
• States(필수) : workflow를 구성하는 state들의 집합입니다.

쉽게 정리해보면 위 workflow는 다음과 같은 흐름으로 동작합니다.

1. 회원 조회 Lambda 실행(Task State) 에서 회원 정보를 조회합니다.
2. 회원 상태 확인(Choice State) 에서 Lambda 실행 결과를 검사합니다.
3. 결과값에 "정상회원" 문자열이 포함되어 있으면 환영 이메일 발송(Task State) 으로 이동합니다.
4. 이메일 발송이 완료되면 처리 완료(Pass State) 로 이동하여 workflow를 종료합니다.
5. 조건에 만족하지 않으면 회원 처리 실패(Fail State) 로 이동하여 workflow를 실패 처리합니다.

 

Input / Output

Step Functions 실행은 JSON 형태의 입력 데이터를 받아 workflow의 첫 번째 State로 전달합니다.
각 State는 입력받은 JSON 데이터를 가공하거나 필터링한 뒤 다음 State로 전달하며, 이 과정에서 Input/Output 관련 옵션을 사용해 데이터를 제어할 수 있습니다.

 

AWS 공식 문서에서는 State 내부 데이터 처리 순서를 아래와 같이 설명합니다.

https://aws.amazon.com/ko/blogs/compute/modeling-workflow-input-output-path-processing-with-data-flow-simulator

InputPath → Parameters → ResultSelector → ResultPath → OutputPath

 

 

각 옵션은 다음과 같은 역할을 수행합니다.

• InputPath: 입력 데이터 중 필요한 데이터만 선택합니다.
• Parameters: 다음 작업에 전달할 입력 데이터를 새롭게 구성합니다.
• ResultSelector: Task 실행 결과 중 필요한 값만 선택합니다.
• ResultPath: Task 실행 결과를 기존 입력 데이터와 어떻게 병합할지 결정합니다.
• OutputPath: 최종적으로 다음 State에 전달할 출력 데이터를 필터링합니다.

아래는 회원 정보를 조회하는 Lambda를 호출하면서 InputPath 와 ResultPath 를 사용하는 간단한 예시입니다.

{
  "Comment": "Input/Output 처리 예시",
  "StartAt": "회원 조회",
  "States": {
    "회원 조회": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:ap-northeast-2:<ACCOUNT_ID>:function:getUser",
      "InputPath": "$.user",
      "ResultPath": "$.userResult",
      "OutputPath": "$",
      "End": true
    }
  }
}

 

예를 들어 아래와 같은 입력 데이터가 들어왔다고 가정합니다.

{
  "user": {
    "userId": 1,
    "name": "홍길동"
  },
  "requestTime": "2025-05-09"
}

InputPath 에 $.user 를 지정했기 때문에 Lambda에는 아래 데이터만 전달됩니다.

{
  "userId": 1,
  "name": "홍길동"
}

이후 Lambda 실행 결과가 아래와 같다면

{
  "status": "정상회원"
}

ResultPath 에 $.userResult 를 지정했기 때문에 Lambda 실행 결과가 기존 입력 데이터에 병합되어 최종 출력은 아래와 같이 생성됩니다.

{
  "user": {
    "userId": 1,
    "name": "홍길동"
  },
  "requestTime": "2025-05-09",
  "userResult": {
    "status": "정상회원"
  }
}

즉 Step Functions는 각 State에서 Input/Output 데이터를 필터링하고 가공하면서 다음 workflow 단계로 전달하는 방식으로 동작합니다.

 

📚 Reference

• https://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/welcome.html
• https://docs.aws.amazon.com/step-functions/latest/dg/input-output-inputpath-params.html
• https://imok2.tistory.com/entry/AWS-Step-Functions#article-2-1-3--asl(amazon-states-language)
• https://m.blog.naver.com/PostView.naver?blogId=classmethodkr&logNo=222660168407&proxyReferer=https:%2F%2Fwww.google.com%2F&trackingCode=external