Day 2 - Run Command, State Manager, Maintenance Window: 운영 자동화 3종 세트

"prod 서버 전체에 새 환경 변수 추가해야 해요. 지금 바로요." 개발팀 리더의 메시지다. EC2 인스턴스 150대, 모두 Environment=prod 태그가 붙어 있다. SSH로 한 대씩? 불가능한 일정이다. 이때 운영자가 꺼내는 것이 Run Command다. 명령을 정의하고, 대상을 태그로 지정하고, 동시성과 에러 한도를 설정한 뒤 실행 버튼을 누르면 150대에 동시에 배포된다. 결과는 S3와 CloudWatch Logs에 자동으로 저장되고, 실패한 인스턴스는 OpsCenter에 OpsItem으로 자동 생성된다.

오늘 다루는 Run Command, State Manager, Maintenance Window는 "SSM 운영 자동화 3종 세트"다. 이 세 도구는 각각 "지금 한 번(Run Command)", "항상 이 상태로(State Manager)", "이 시간에 이 작업(Maintenance Window)"을 담당한다. 셋의 역할을 명확히 구분하는 것이 SOA-C02 시험의 핵심 포인트 중 하나다.

Run Command의 내부 동작 원리

Run Command는 단순해 보이지만 내부적으로 정교한 분산 시스템이다. 운영자가 send-command를 호출하면 어떤 일이 일어나는가.

1. SSM API 수신: 명령이 SSM 서비스에 등록되고 Command ID가 발급된다
2. 대상 선정: Tags/Resource Groups/Instance IDs 기준으로 대상 목록을 계산한다
3. Concurrency 제어: 동시 실행 한도에 따라 첫 배치를 선발한다 (예: 10%면 150대 중 15대)
4. Agent Poll: 선발된 인스턴스들의 Agent가 다음 heartbeat 시 명령을 가져온다 (pull 방식)
5. 실행 및 결과 반환: Agent가 명령을 실행하고 stdout/stderr를 ec2messages 채널로 SSM에 반환
6. 출력 저장: 설정에 따라 S3 버킷과 CloudWatch Logs에 결과 저장
7. 에러 평가: 현재까지 에러율이 Error Threshold를 초과하면 나머지 배치 실행 중단
8. 다음 배치: 에러가 임계값 미만이면 다음 15대를 실행

Run Command의 Concurrency 제어는 분산 시스템의 "circuit breaker pattern"과 "bulkhead pattern"을 결합한 설계다. Michael Nygard의 「Release It!」(2007)에서 circuit breaker는 장애 전파를 막는 패턴으로, Error Threshold 초과 시 나머지 실행을 중단하는 것이 정확한 구현이다. Bulkhead(격벽)는 동시 실행 수를 제한해 실패가 전체로 번지지 않도록 격리한다. 운영자가 --max-concurrency 10%를 설정하는 것은 이 두 패턴을 동시에 적용하는 것이다. Google SRE Book(Beyer et al., 2016) 13장 "Emergency Response"는 같은 원칙을 "rate limiting"으로 표현한다.

Rate Control의 수학: 언제 퍼센트, 언제 절대값?

Run Command의 --max-concurrency와 --max-errors는 퍼센트(%）또는 절대값 중 선택 가능하다. 언제 무엇을 써야 하는가.

퍼센트 계산 예시:

• 150대, max-concurrency=10%: ceil(150 × 0.10) = 15대씩 병렬 실행
• 150대, max-errors=5%: 7대(ceil(150 × 0.05)) 이상 실패 시 중단
• 실패 7대가 첫 배치(15대)에서 발생하면, 나머지 135대는 실행되지 않는다

--max-errors "0"으로 설정하면 단 1개의 실패도 허용하지 않아 즉시 중단된다. 이는 "zero-tolerance rollout"으로, 새 크리티컬 패치가 특정 OS 버전과 호환성 문제가 있는지 모르는 상황에서 한두 대에 먼저 테스트하는 용도로 적합하다. 반면 --max-errors "100%"는 모든 실패를 무시하고 전체 대상에 강제 실행하는 것으로, 이미 알려진 일부 비준수 인스턴스가 있어도 전체를 업데이트해야 할 때 사용한다.

SSM Document: 명령의 정의

Run Command의 실제 실행 내용은 SSM Document(JSON 또는 YAML)에 담긴다. Document는 SSM의 모든 자동화 기능의 기반이다.

Document Type별 사용 용도:

AWS가 제공하는 주요 Command Document:

AWS-RunShellScript          - Linux 쉘 명령 실행
AWS-RunPowerShellScript     - Windows PowerShell 명령 실행
AWS-RunPatchBaseline        - 패치 적용 (Patch Manager 표준)
AWS-ConfigureAWSPackage     - Distributor 패키지 설치/제거
AWS-UpdateSSMAgent          - SSM Agent 자동 업데이트
AmazonCloudWatch-ManageAgent - CloudWatch Agent 관리

SSM Document는 버전 관리를 지원한다. Document의 특정 버전을 $LATEST, $DEFAULT, 또는 숫자(1, 2, 3...)로 지정할 수 있다. $LATEST는 항상 최신 버전이고, $DEFAULT는 운영자가 안정 버전으로 지정한 것이다. 운영 환경에서는 항상 $DEFAULT나 특정 버전 번호를 명시해 예상치 못한 Document 업데이트로 인한 동작 변화를 막아야 한다. AWS 관리형 Document(AWS-*)는 AWS가 업데이트하며 버전 고정이 중요하다. 커스텀 Document는 Git처럼 의미 있는 버전 관리를 적용하고, CI/CD 파이프라인에서 create-document→테스트→update-document-default-version으로 Blue/Green 배포하는 패턴이 표준이다.

Run Command 실전 패턴

기본 실행 (태그 기반 대상):

# 150대 prod 서버에 환경변수 추가
aws ssm send-command \
  --document-name "AWS-RunShellScript" \
  --parameters '{
    "commands":[
      "echo '"'"'NEW_FEATURE_FLAG=true'"'"' >> /etc/environment",
      "source /etc/environment",
      "echo \"Applied on $(hostname) at $(date)\""
    ]
  }' \
  --targets '[{"Key":"tag:Environment","Values":["prod"]}]' \
  --max-concurrency "10%" \
  --max-errors "5%" \
  --output-s3-bucket-name "ssm-command-output" \
  --output-s3-key-prefix "env-var-deploy/$(date +%Y/%m/%d)" \
  --cloud-watch-output-config '{
    "CloudWatchLogGroupName":"/ssm/run-command",
    "CloudWatchOutputEnabled":true
  }' \
  --timeout-seconds 300
 
# Command ID 저장
COMMAND_ID=$(aws ssm send-command ... --query 'Command.CommandId' --output text)
 
# 결과 조회
aws ssm list-command-invocations \
  --command-id "$COMMAND_ID" \
  --details \
  --query 'CommandInvocations[*].[InstanceId,Status,CommandPlugins[0].ResponseCode,CommandPlugins[0].Output]' \
  --output table

실패한 인스턴스만 재실행:

# 실패 인스턴스 ID 목록 추출
FAILED_INSTANCES=$(aws ssm list-command-invocations \
  --command-id "$COMMAND_ID" \
  --filter "key=Status,value=Failed" \
  --query 'CommandInvocations[*].InstanceId' \
  --output text | tr '\t' ',')
 
# 실패 인스턴스에만 재실행
aws ssm send-command \
  --document-name "AWS-RunShellScript" \
  --parameters '...' \
  --instance-ids $FAILED_INSTANCES \
  --max-concurrency "1" \
  --max-errors "0"

⚠️ 함정: --instance-ids로 직접 지정할 때 최대 50개까지다. 50개 초과 시 Tags 또는 Resource Groups를 사용해야 한다. 또한 Run Command는 실행 시점의 태그 매칭이라 실행 후 태그가 변경돼도 이미 보낸 명령은 영향이 없다. 그리고 명령 실행 결과의 stdout/stderr는 S3에 저장 시 각 인스턴스별 별도 경로(<prefix>/<CommandId>/<InstanceId>/awsrunshellscript/0.awsrunshellscript/stdout)로 저장된다.

State Manager: Desired State의 지속적 보장

Run Command가 "지금 한 번"이라면 State Manager는 "항상 이 상태"다. Association이라 불리는 설정 단위가 핵심이다.

Association의 구성 요소:

State Manager의 Convergence 동작:

Association 등록
      │
      ▼
[신규 인스턴스가 Managed Instance로 등록됨]
      │ (태그가 맞으면 즉시 Association 실행)
      ▼
[스케줄 주기마다 재실행]
      │ (drift가 발생했으면 자동 교정)
      ▼
[컴플라이언스 결과 기록]

실용 Association 예시 - CloudWatch Agent 설정 동기화:

aws ssm create-association \
  --association-name "EnforceCWAgentConfig" \
  --name "AmazonCloudWatch-ManageAgent" \
  --targets '[{"Key":"tag:MonitoringEnabled","Values":["true"]}]' \
  --parameters '{
    "action":["configure"],
    "mode":["ec2"],
    "optionalConfigurationSource":["ssm"],
    "optionalConfigurationLocation":["/cloudwatch/agent/prod-config"],
    "optionalRestart":["yes"]
  }' \
  --schedule-expression "rate(1 day)" \
  --max-concurrency "20%" \
  --max-errors "5%" \
  --compliance-severity "HIGH"

이 Association이 등록된 이후 발생하는 일:

1. 새 EC2가 MonitoringEnabled=true 태그와 함께 시작 → Managed Instance 등록 즉시 Association 실행 → CW Agent 설정 자동 적용
2. 누군가 CW Agent 설정을 인스턴스에서 직접 변경(drift) → 다음 스케줄 실행(최대 1일 후)에 자동 교정
3. CW Agent가 충돌로 종료 → 스케줄 실행 시 optionalRestart: yes로 자동 재시작

가상의 사례로, 2023년, 대형 이커머스 플랫폼 B사가 State Manager로 CloudWatch Agent 설정 표준화를 구현했다. 이전에는 새 인스턴스가 스케일아웃될 때마다 개발팀이 수동으로 CW Agent를 설정해 메트릭 수집이 누락되는 일이 잦았다. State Manager Association 도입 후 6개월 동안 "메트릭 수집 누락" 인시던트가 0건이었다. 또한 누군가 실수로 Agent 설정을 변경했을 때 24시간 내 자동 복구되는 것도 확인했다. 컴플라이언스 대시보드에서 Association 실패 인스턴스를 실시간으로 파악할 수 있어 운영 가시성도 높아졌다.

Association의 즉시 실행 (ApplyOnlyAtCronInterval 제어):

# 기본적으로 Association 생성 즉시 한 번 실행됨
# 스케줄에만 실행하고 생성 즉시 실행 방지:
aws ssm create-association \
  --association-name "WeeklyKernelUpdate" \
  --name "AWS-RunShellScript" \
  --schedule-expression "cron(0 3 ? * SUN *)" \
  --apply-only-at-cron-interval \
  --targets '[{"Key":"tag:PatchGroup","Values":["prod"]}]'
 
# Association을 즉시 강제 실행 (스케줄 무관)
aws ssm start-associations-once \
  --association-ids "asc-0123456789abcdef0"

State Manager의 "desired state convergence" 개념은 제어 이론의 "feedback control loop"와 동일하다. 목표 상태(setpoint)와 현재 상태(process variable)의 차이(error)를 감지하고 수정 작업(control action)을 적용한다. Kubernetes의 Reconciler 패턴, Puppet의 Catalog 적용, AWS Config의 자동 교정 모두 같은 원리다. State Manager는 스케줄을 "sampling interval"로 사용해 drift를 정기적으로 감지·교정하는 discrete-time 제어 루프를 구현한다.

Pseudo Parameters로 동적 Document:

# SSM Document에서 {{InstanceId}} 같은 동적 변수 사용
{
  "schemaVersion": "2.2",
  "mainSteps": [
    {
      "action": "aws:runShellScript",
      "name": "labelInstance",
      "inputs": {
        "runCommand": [
          "echo 'InstanceId: {{ssm:instanceId}}' > /etc/instance-label",
          "echo 'Region: {{global:REGION}}' >> /etc/instance-label"
        ]
      }
    }
  ]
}

Maintenance Window: 안전한 시간대에 복잡한 작업 실행

Maintenance Window는 "패치 일요일 새벽 2시에 하기로 했다"는 운영 정책을 코드로 만드는 도구다. 단순한 cron 스케줄러가 아니라, 복잡한 작업 묶음을 안전하게 실행하는 완전한 워크플로 엔진이다.

3개 구성 요소의 관계:

Maintenance Window (시간대 정의)
    │
    ├── Targets (대상 그룹)
    │      tag:PatchGroup=prod-web
    │
    └── Tasks (실행할 작업, 우선순위 순서)
           1. Snapshot 생성 (Automation) - Priority 1
           2. ELB deregister (Automation)  - Priority 2
           3. Patch 적용 (Run Command)     - Priority 3
           4. Health check (Automation)   - Priority 4
           5. ELB register (Automation)   - Priority 5

Window의 시간 파라미터:

Cutoff의 중요성: Duration 4시간, Cutoff 1시간이면 실제 새 작업을 시작할 수 있는 시간은 3시간이다. 03:00에 이미 시작한 작업은 04:00이 되어도 계속 실행된다. Cutoff는 "Window가 끝나기 직전에 새 작업이 시작되어 미완료 상태로 끊기는" 상황을 방지한다.

Maintenance Window의 Cutoff 개념은 운영 시스템에서 "graceful shutdown" 패턴과 동일하다. TCP 연결의 FIN/ACK 과정처럼, 새 작업 접수를 먼저 차단하고 진행 중인 작업이 완료되길 기다린다. 쿠버네티스의 terminationGracePeriodSeconds도 같은 원리다. 분산 시스템에서 "진행 중인 작업은 완료시키되 새 작업은 받지 않는다"는 원칙은 데이터 무결성의 기본이다. POSIX의 SIGTERM → SIGKILL 시퀀스도 같은 graceful shutdown 철학을 구현한다.

CRON 표현식 완전 정복

Maintenance Window의 Schedule은 AWS cron 표현식을 사용한다. AWS cron은 표준 Linux cron과 일부 다르다.

AWS cron 형식: cron(분 시 일 월 요일 연도)
              cron(Minutes Hours Day-of-month Month Day-of-week Year)

특수 문자:
  * : 모든 값
  ? : 특정 값 없음 (Day-of-month와 Day-of-week 중 하나에만 사용)
  - : 범위 (예: 1-5)
  , : 목록 (예: MON,WED,FRI)
  / : 증분 (예: 0/15 = 0, 15, 30, 45)
  L : 마지막 (예: Day-of-month에서 L = 월의 마지막 날)
  W : 가장 가까운 평일
  # : N번째 요일 (예: 2#1 = 월의 첫 번째 화요일)

예시:
  cron(0 2 ? * SUN *)     = 매주 일요일 02:00 UTC
  cron(0 14 ? * MON-FRI *) = 평일 14:00 UTC
  cron(0 1 1 * ? *)        = 매월 1일 01:00 UTC
  cron(0 9 ? * 2#1 *)      = 매월 첫 번째 월요일 09:00 UTC
  cron(15 12 L * ? *)       = 매월 마지막 날 12:15 UTC

⚠️ 함정: AWS cron은 UTC 기준이다. 서울(KST = UTC+9) 새벽 2시에 실행하려면 cron(0 17 ? * SAT *) (토요일 17:00 UTC = 일요일 02:00 KST)로 설정해야 한다. 또한 Day-of-month와 Day-of-week를 동시에 지정할 수 없어, 둘 중 하나는 반드시 ?를 사용해야 한다. cron(0 2 15 * MON *)는 유효하지 않고 cron(0 2 15 * ? *)(매월 15일) 또는 cron(0 2 ? * MON *)(매주 월요일) 중 하나를 선택해야 한다.

완전한 패치 Window 구성 예시:

# 1. Maintenance Window 생성
WINDOW_ID=$(aws ssm create-maintenance-window \
  --name "ProdWebWeeklyPatch" \
  --schedule "cron(0 17 ? * SAT *)" \
  --schedule-timezone "Asia/Seoul" \
  --duration 4 \
  --cutoff 1 \
  --allow-unassociated-targets \
  --description "Weekly patch window for prod web tier (Sun 02:00 KST)" \
  --query 'WindowId' --output text)
 
echo "Window ID: $WINDOW_ID"
 
# 2. 대상 등록 (Patch Group 태그 기반)
TARGET_ID=$(aws ssm register-target-with-maintenance-window \
  --window-id "$WINDOW_ID" \
  --resource-type INSTANCE \
  --targets 'Key=tag:PatchGroup,Values=prod-web' \
  --owner-information "Production Web Tier Servers" \
  --query 'WindowTargetId' --output text)
 
# 3. Task 1: EBS 스냅샷 생성 (Automation, Priority 1)
aws ssm register-task-with-maintenance-window \
  --window-id "$WINDOW_ID" \
  --task-arn "AWS-CreateSnapshot" \
  --task-type AUTOMATION \
  --targets "Key=WindowTargetIds,Values=$TARGET_ID" \
  --priority 1 \
  --max-concurrency "10%" \
  --max-errors "5%" \
  --service-role-arn "arn:aws:iam::123456789012:role/SSMMaintenanceWindowRole"
 
# 4. Task 2: 패치 적용 (Run Command, Priority 2)
aws ssm register-task-with-maintenance-window \
  --window-id "$WINDOW_ID" \
  --task-arn "AWS-RunPatchBaseline" \
  --task-type RUN_COMMAND \
  --targets "Key=WindowTargetIds,Values=$TARGET_ID" \
  --priority 2 \
  --max-concurrency "10%" \
  --max-errors "5%" \
  --service-role-arn "arn:aws:iam::123456789012:role/SSMMaintenanceWindowRole" \
  --task-invocation-parameters '{
    "RunCommand": {
      "Parameters": {
        "Operation": ["Install"],
        "RebootOption": ["RebootIfNeeded"]
      },
      "OutputS3BucketName": "patch-output-bucket",
      "OutputS3KeyPrefix": "prod-web",
      "CloudWatchOutputConfig": {
        "CloudWatchLogGroupName": "/ssm/patch/prod-web",
        "CloudWatchOutputEnabled": true
      }
    }
  }'
 
# 5. Window 이전 실행 기록 조회
aws ssm describe-maintenance-window-executions \
  --window-id "$WINDOW_ID" \
  --query 'WindowExecutions[*].[WindowExecutionId,Status,StartTime,EndTime]' \
  --output table

가상의 사례로, 2022년 의료 SaaS 기업 C사가 HIPAA 컴플라이언스를 위한 패치 자동화를 구현했다. Maintenance Window를 월 2회(1일, 15일 KST 새벽 2시)로 설정하고 Task 순서를 EBS 스냅샷(Priority 1) → ELB Deregister(Priority 2) → 패치(Priority 3) → Health Check(Priority 4) → ELB Register(Priority 5)로 구성했다. max-concurrency=10%, max-errors=5%로 설정해 패치 실패가 연쇄되지 않도록 했다. 도입 전에는 패치 담당자가 매주 토요일 새벽에 출근했는데, 도입 후 완전 무인 자동화로 전환됐다. HIPAA 164.312(c)(2) 요구사항(패치 검증 절차)을 S3 저장 패치 로그로 충족했다.

Compliance: 패치와 Association의 통합 대시보드

Compliance는 Patch Manager와 State Manager의 실행 결과를 종합하여 인스턴스별 컴플라이언스 점수를 산출한다.

컴플라이언스 데이터 유형:

# 컴플라이언스 요약 (전체 계정)
aws ssm list-compliance-summaries \
  --query 'ComplianceSummaryItems[*].[ComplianceType,CompliantSummary.CompliantCount,NonCompliantSummary.NonCompliantCount]' \
  --output table
 
# 특정 인스턴스의 비준수 항목
aws ssm list-compliance-items \
  --resource-ids i-0123456789abcdef0 \
  --resource-types ManagedInstance \
  --filters 'Key=STATUS,Values=NON_COMPLIANT,Type=EQUAL'
 
# 커스텀 컴플라이언스 항목 보고 (Lambda 등에서)
aws ssm put-compliance-items \
  --resource-id i-0123456789abcdef0 \
  --resource-type ManagedInstance \
  --compliance-type "Custom:AppSecurity" \
  --execution-summary '{"ExecutionTime":"2026-05-26T02:00:00Z"}' \
  --items '[{"Id":"SSL_CERT_EXPIRY","Title":"SSL cert valid","Severity":"CRITICAL","Status":"COMPLIANT","Details":{"expiry":"2027-01-01"}}]'

Compliance의 Custom:* 유형을 활용하면 SSM 밖의 보안 검사 결과도 중앙 대시보드에 통합할 수 있다. 예를 들어 CIS Benchmark 스캔 결과, SSL 인증서 만료 여부, 커스텀 애플리케이션 설정 검증 결과를 Lambda에서 put-compliance-items로 보고하면 Compliance 대시보드에 통합된다. 이 데이터는 Security Hub나 Audit Manager로도 집계 가능하다. AWS는 이 패턴을 "operational data aggregation"이라고 부르며, 멀티 계정 환경에서는 Organizations + Resource Data Sync로 중앙 계정에 모든 계정의 컴플라이언스 데이터를 집계하는 구조가 표준이다.

Run Command vs State Manager vs Maintenance Window: 언제 무엇을?

이 세 도구의 차이를 명확히 이해하는 것이 SOA-C02에서 반복적으로 요구된다.

의사결정 흐름도:

명령을 실행해야 하는가?
    │
    ├─ 지금 한 번만? → Run Command
    │
    ├─ 항상 이 상태를 유지해야 하는가? → State Manager
    │
    └─ 특정 시간대에 정기적으로? → Maintenance Window
          │
          └─ 작업이 여러 단계인가? → Maintenance Window + Automation Runbook