기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Step Functions에서 상태 시스템 버전 점진적 배포 수행
<a name="version-rolling-deployment"></a>

롤링 배포는 이전 버전의 애플리케이션을 새 버전의 애플리케이션으로 천천히 바꾸는 배포 전략입니다. 상태 시스템 버전 롤링 배포를 수행하려면 실행 트래픽 양을 점진적으로 늘리면서 새 버전으로 전송합니다. 트래픽 양과 증가 속도는 사용자가 구성하는 파라미터입니다.

다음 옵션 중 하나를 사용하여 버전 롤링 배포를 수행할 수 있습니다.
+ [Step Functions 콘솔](https://console.aws.amazon.com/states/home?region=us-east-1#/) - 같은 상태 시스템 버전 2개를 가리키는 별칭을 만듭니다. 이 별칭의 경우 트래픽이 두 버전 간에 이동하도록 라우팅 구성을 구성합니다. 콘솔을 사용하여 버전을 출시하는 방법에 대한 자세한 내용은 [버전](concepts-state-machine-version.md) 및 [별칭](concepts-state-machine-alias.md) 섹션을 참조하세요.
+ **AWS CLI 및 SDK용 스크립트** - AWS CLI 또는 AWS SDK를 사용하여 쉘 스크립트를 만듭니다. 자세한 내용은 AWS CLI 및 AWS SDK 사용에 대한 다음 섹션을 참조하세요.
+ **AWS CloudFormation 템플릿** - `[AWS::StepFunctions::StateMachineVersion](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html)` 및 `[AWS::StepFunctions::StateMachineAlias](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html)` 리소스를 사용하여 여러 상태 시스템 버전을 게시하고 이러한 버전 중 하나 또는 두 개를 가리키는 별칭을 만듭니다.

## AWS CLI를 사용하여 새 상태 시스템 버전 배포
<a name="version-canary-deploy-cli"></a>

이 섹션의 예제 스크립트에서는 AWS CLI를 사용하여 트래픽을 이전 상태 시스템 버전에서 새 상태 시스템 버전으로 점진적으로 이동하는 방법을 보여줍니다. 이 예제 스크립트를 사용하거나 요구 사항에 따라 업데이트할 수 있습니다.

이 스크립트에서는 별칭을 사용하여 새 상태 시스템 버전을 배포하기 위한 카나리 배포를 보여줍니다. 다음 단계에서는 스크립트에서 수행하는 작업을 간략하게 설명합니다.

1. `publish_revision` 파라미터가 true로 설정되면 최신 [revision](concepts-cd-aliasing-versioning.md#statemachinerev)을 상태 시스템의 다음 버전으로 게시합니다. 배포가 성공하면 이 버전이 새로운 실시간 버전이 됩니다.

   `publish_revision` 파라미터를 false로 설정하면 스크립트는 마지막으로 게시된 상태 시스템 버전을 배포합니다.

1. 아직 존재하지 않으면 별칭을 만듭니다. 별칭이 존재하지 않으면 이 별칭의 모든 트래픽이 새 버전을 가리키도록 한 다음 스크립트를 종료합니다.

1. 별칭의 라우팅 구성을 업데이트하여 소량의 트래픽을 이전 버전에서 새 버전으로 이동합니다. `canary_percentage` 파라미터를 사용하여 이 canary 비율을 설정합니다.

1. 기본적으로 구성 가능한 CloudWatch 경보를 60초 간격으로 모니터링합니다. 이러한 경보 중 하나라도 발생하면 모든 트래픽이 이전 버전을 가리키도록 하여 배포를 즉시 롤백합니다.

   `alarm_polling_interval`에 정의된 시간 간격(초 단위)이 지난 후에 경보를 계속 모니터링합니다. `canary_interval_seconds`에 정의된 시간 간격이 경과할 때까지 계속 모니터링합니다.

1. `canary_interval_seconds` 중에 알람이 발생한 경우 모든 트래픽을 새 버전으로 이동합니다.

1. 새 버전이 성공적으로 배포되면 `history_max` 파라미터에 지정된 숫자보다 오래된 버전을 모두 삭제합니다.



```
#!/bin/bash
# 
# AWS StepFunctions example showing how to create a canary deployment with a
# State Machine Alias and versions.
# 
# Requirements: AWS CLI installed and credentials configured.
# 
# A canary deployment deploys the new version alongside the old version, while
# routing only a small fraction of the overall traffic to the new version to
# see if there are any errors. Only once the new version has cleared a testing
# period will it start receiving 100% of traffic.
# 
# For a Blue/Green or All at Once style deployment, you can set the
# canary_percentage to 100. The script will immediately shift 100% of traffic
# to the new version, but keep on monitoring the alarms (if any) during the
# canary_interval_seconds time interval. If any alarms raise during this period,
# the script will automatically rollback to the previous version.
# 
# Step Functions allows you to keep a maximum of 1000 versions in version history
# for a state machine. This script has a version history deletion mechanism at
# the end, where it will delete any versions older than the limit specified.
# 
# For an example that also demonstrates linear (or rolling) deployments, see the following: 
# https://github.com/aws-samples/aws-stepfunctions-examples/blob/main/gradual-deploy/sfndeploy.py

set -euo pipefail

# ******************************************************************************
# you can safely change the variables in this block to your values
state_machine_name="my-state-machine"
alias_name="alias-1"
region="us-east-1"

# array of cloudwatch alarms to poll during the test period.
# to disable alarm checking, set alarm_names=()
alarm_names=("alarm1" "alarm name with a space")

# true to publish the current revision as the next version before deploy.
# false to deploy the latest version from the state machine's version history.
publish_revision=true

# true to force routing configuration update even if the current routing
# for the alias does not have a 100% routing config.
# false will abandon deploy attempt if current routing config not 100% to a
# single version.
# Be careful when you combine this flag with publish_revision - if you just
# rerun the script you might deploy the newly published revision from the
# previous run.
force=false

# percentage of traffic to route to the new version during the test period
canary_percentage=10

# how many seconds the canary deployment lasts before full deploy to 100%
canary_interval_seconds=300

# how often to poll the alarms
alarm_polling_interval=60

# how many versions to keep in history. delete versions prior to this.
# set to 0 to disable old version history deletion.
history_max=0
# ******************************************************************************

#######################################
# Update alias routing configuration.
# 
# If you don't specify version 2 details, will only create 1 routing entry. In
# this case the routing entry weight must be 100.
# 
# Globals:
#   alias_arn
# Arguments:
#   1. version 1 arn
#   2. version 1 weight
#   3. version 2 arn (optional)
#   4. version 2 weight (optional)
#######################################
function update_routing() {
  if [[ $# -eq 2 ]]; then
    local routing_config="[{\"stateMachineVersionArn\": \"$1\", \"weight\":$2}]"
  elif [[ $# -eq 4 ]]; then
    local routing_config="[{\"stateMachineVersionArn\": \"$1\", \"weight\":$2}, {\"stateMachineVersionArn\": \"$3\", \"weight\":$4}]"
  else
    echo "You have to call update_routing with either 2 or 4 input arguments." >&2
    exit 1
  fi
  
  ${aws} update-state-machine-alias --state-machine-alias-arn ${alias_arn} --routing-configuration "${routing_config}"
}

# ******************************************************************************
# pre-run validation
if [[ (("${#alarm_names[@]}" -gt 0)) ]]; then
  alarm_exists_count=$(aws cloudwatch describe-alarms --alarm-names "${alarm_names[@]}" --alarm-types "CompositeAlarm" "MetricAlarm" --query "length([MetricAlarms, CompositeAlarms][])" --output text)

  if [[ (("${#alarm_names[@]}" -ne "${alarm_exists_count}")) ]]; then
    echo All of the alarms to monitor do not exist in CloudWatch: $(IFS=,; echo "${alarm_names[*]}") >&2
    echo Only the following alarm names exist in CloudWatch:
    aws cloudwatch describe-alarms --alarm-names "${alarm_names[@]}" --alarm-types "CompositeAlarm" "MetricAlarm" --query "join(', ', [MetricAlarms, CompositeAlarms][].AlarmName)" --output text
    exit 1
  fi
fi

if [[ (("${history_max}" -gt 0)) && (("${history_max}" -lt 2)) ]]; then
  echo The minimum value for history_max is 2. This is the minimum number of older state machine versions to be able to rollback in the future. >&2
  exit 1
fi
# ******************************************************************************
# main block follows

account_id=$(aws sts get-caller-identity --query Account --output text)

sm_arn="arn:aws:states:${region}:${account_id}:stateMachine:${state_machine_name}"

# the aws command we'll be invoking a lot throughout.
aws="aws stepfunctions"

# promote the latest revision to the next version
if [[ "${publish_revision}" = true ]]; then
  new_version=$(${aws} publish-state-machine-version --state-machine-arn=$sm_arn --query stateMachineVersionArn --output text)
  echo Published the current revision of state machine as the next version with arn: ${new_version}
else
  new_version=$(${aws} list-state-machine-versions --state-machine-arn ${sm_arn} --max-results 1 --query "stateMachineVersions[0].stateMachineVersionArn" --output text)
  echo "Since publish_revision is false, using the latest version from the state machine's version history: ${new_version}"
fi

# find the alias if it exists
alias_arn_expected="${sm_arn}:${alias_name}"
alias_arn=$(${aws} list-state-machine-aliases --state-machine-arn ${sm_arn} --query "stateMachineAliases[?stateMachineAliasArn==\`${alias_arn_expected}\`].stateMachineAliasArn" --output text)

if [[ "${alias_arn_expected}" == "${alias_arn}" ]]; then
  echo Found alias ${alias_arn}

  echo Current routing configuration is:
  ${aws} describe-state-machine-alias --state-machine-alias-arn "${alias_arn}" --query routingConfiguration
else
  echo Alias does not exist. Creating alias ${alias_arn_expected} and routing 100% traffic to new version ${new_version}
  
  ${aws} create-state-machine-alias --name "${alias_name}" --routing-configuration "[{\"stateMachineVersionArn\": \"${new_version}\", \"weight\":100}]"

  echo Done!
  exit 0
fi

# find the version to which the alias currently points (the current live version)
old_version=$(${aws} describe-state-machine-alias --state-machine-alias-arn $alias_arn --query "routingConfiguration[?weight==\`100\`].stateMachineVersionArn" --output text)

if [[ -z "${old_version}" ]]; then
  if [[ "${force}" = true ]]; then
    echo Force setting is true. Will force update to routing config for alias to point 100% to new version.
    update_routing "${new_version}" 100
    
    echo Alias ${alias_arn} now pointing 100% to ${new_version}.
    echo Done!
    exit 0
  else
    echo Alias ${alias_arn} does not have a routing config entry with 100% of the traffic. This means there might be a deploy in progress, so not starting another deploy at this time. >&2
    exit 1
  fi
fi

if [[ "${old_version}" == "${new_version}" ]]; then
  echo The alias already points to this version. No update necessary.
  exit 0
fi

echo Switching ${canary_percentage}% to new version ${new_version}
(( old_weight = 100 - ${canary_percentage} ))
update_routing "${new_version}" ${canary_percentage} "${old_version}" ${old_weight}

echo New version receiving ${canary_percentage}% of traffic.
echo Old version ${old_version} is still receiving ${old_weight}%.

if [[ ${#alarm_names[@]} -eq 0 ]]; then
  echo No alarm_names set. Skipping cloudwatch monitoring.
  echo Will sleep for ${canary_interval_seconds} seconds before routing 100% to new version.
  sleep ${canary_interval_seconds}
  echo Canary period complete. Switching 100% of traffic to new version...
else
  echo Checking if alarms fire for the next ${canary_interval_seconds} seconds.

  (( total_wait = canary_interval_seconds + $(date +%s) ))

  now=$(date +%s)
  while [[ ((${now} -lt ${total_wait})) ]]; do
    alarm_result=$(aws cloudwatch describe-alarms --alarm-names "${alarm_names[@]}" --state-value ALARM --alarm-types "CompositeAlarm" "MetricAlarm" --query "join(', ', [MetricAlarms, CompositeAlarms][].AlarmName)" --output text)

    if [[ ! -z "${alarm_result}" ]]; then
      echo The following alarms are in ALARM state: ${alarm_result}. Rolling back deploy. >&2
      update_routing "${old_version}" 100

      echo Rolled back to ${old_version}
      exit 1
    fi
  
    echo Monitoring alarms...no alarms have triggered.
    sleep ${alarm_polling_interval}
    now=$(date +%s)
  done

  echo No alarms detected during canary period. Switching 100% of traffic to new version...
fi

update_routing "${new_version}" 100

echo Version ${new_version} is now receiving 100% of traffic.

if [[ (("${history_max}" -eq 0 ))]]; then
  echo Version History deletion is disabled. Remember to prune your history, the default limit is 1000 versions.
  echo Done!
  exit 0
fi

echo Keep the last ${history_max} versions. Deleting any versions older than that...

# the results are sorted in descending order of the version creation time
version_history=$(${aws} list-state-machine-versions --state-machine-arn ${sm_arn} --max-results 1000 --query "join(\`\"\\n\"\`, stateMachineVersions[].stateMachineVersionArn)" --output text)

counter=0

while read line; do
  ((counter=${counter} + 1))

  if [[ (( ${counter} -gt ${history_max})) ]]; then
    echo Deleting old version ${line}
    ${aws} delete-state-machine-version --state-machine-version-arn ${line}
  fi
done <<< "${version_history}"

echo Done!
```

## AWS SDK를 사용하여 새 상태 시스템 버전 배포
<a name="version-deploy-sdk"></a>

[aws-stepfunctions-examples](https://github.com/aws-samples/aws-stepfunctions-examples/tree/main/gradual-deploy)의 예제 스크립트에서는 Python용 AWS SDK를 사용하여 트래픽을 점진적으로 상태 시스템의 이전 버전에서 새 버전으로 이동하는 방법을 보여줍니다. 이 예제 스크립트를 사용하거나 요구 사항에 따라 업데이트할 수 있습니다.

스크립트에서는 다음과 같은 배포 전략을 보여줍니다.
+ **Canary**: 트래픽이 두 증분으로 나뉘어 이동합니다.

  첫 번째 증분에서는 작은 비율의 트래픽(예: 10%)이 새 버전으로 이동합니다. 두 번째 증분에서는 지정된 시간 간격(초)이 초과되기 전에 남은 트래픽이 새 버전으로 이동합니다. 지정된 시간 간격 동안 CloudWatch 경보가 발생하지 않은 경우에만 남은 트래픽이 새 버전으로 전환됩니다.
+  **선형 또는 롤링** - 각 증분 사이의 시간(초)이 같도록 하여 동일한 증분으로 트래픽을 새 버전으로 이동합니다.

  예를 들어 증분 비율을 **600**초 `--interval`을 사용하여 **20**으로 지정하면 이 배포는 새 버전에서 모든 트래픽을 수신할 때까지 600초 간격으로 트래픽을 20%씩 증가합니다.

  CloudWatch 경보가 발생하면 이 배포는 즉시 새 버전을 롤백합니다.
+ **한 번에 모두 또는 블루/그린** - 모든 트래픽을 새 버전으로 즉시 이동합니다. 이 배포는 새 버전을 모니터링하고 CloudWatch 경보가 발생하면 자동으로 이전 버전으로 롤백합니다.

## AWS CloudFormation을 사용하여 새 상태 시스템 버전 배포
<a name="version-deploy-cfn"></a>

다음 CloudFormation 템플릿 예제에서는 `MyStateMachine` 상태 시스템의 두 버전을 게시합니다. 이러한 두 버전을 모두 가리키는 `PROD` 별칭을 만든 다음 버전 `2`를 배포합니다.

이 예제에서는 이 버전에서 모든 트래픽을 수신할 때까지 트래픽의 10%가 5분 간격으로 버전 `2`로 이동합니다. 이 예제에서도 CloudWatch 알람을 설정하는 방법을 보여줍니다. 설정한 경보 중 하나라도 이 `ALARM` 상태로 전환되면 배포가 실패하고 즉시 롤백됩니다.

```
MyStateMachine:
  Type: AWS::StepFunctions::StateMachine
  Properties:
    Type: STANDARD
    StateMachineName: MyStateMachine
    RoleArn: arn:aws:iam::account-id:role/myIamRole
    Definition:
      StartAt: PassState
      States:
        PassState:
          Type: Pass
          Result: Result
          End: true

MyStateMachineVersionA:
  Type: AWS::StepFunctions::StateMachineVersion
  Properties:
    Description: Version 1
    StateMachineArn: !Ref MyStateMachine

MyStateMachineVersionB:
  Type: AWS::StepFunctions::StateMachineVersion
  Properties:
    Description: Version 2
    StateMachineArn: !Ref MyStateMachine

PROD:
  Type: AWS::StepFunctions::StateMachineAlias
  Properties:
    Name: PROD
    Description: The PROD state machine alias taking production traffic.
    DeploymentPreference:
      StateMachineVersionArn: !Ref MyStateMachineVersionB
      Type: LINEAR
      Percentage: 10
      Interval: 5
      Alarms:
        # A list of alarms that you want to monitor. If any of these alarms trigger, rollback the deployment immediately by pointing 100 percent of traffic to the previous version.
        - !Ref CloudWatchAlarm1
        - !Ref CloudWatchAlarm2
```