워크샵에 운영자만의 계정이 생겼습니다

동작 방식

한 계정이 늘었을 뿐인데, 무엇이 가능해지나

Central Account 자체는 그냥 계정 하나입니다. 진짜 새로운 것은 이 계정과 참가자(Team) 계정 사이를 잇는 다리, SSM Parameter Store입니다. 운영자가 Central Account에서 파라미터를 쓰면(Put), 참가자 계정에 심어둔 인스턴스가 주기적으로 그 값을 읽어(Get) 스스로 설정을 바꿉니다. 반대로 참가자 쪽 정보를 Central이 읽어가는 방향도 가능하지만, 아래 세 사례는 모두 Central → Team 방향을 씁니다 — 운영자가 하나의 값을 바꾸면 모든 참가자에게 한 번에 퍼진다는 뜻입니다.

이 한 가지 패턴이 아래 세 사례에서 각각 조금씩 다른 재료를 실어 나릅니다 — 비밀번호, 서버 주소, API 키. 재료가 달라도 다리는 똑같습니다.

동작 방식 · 심화

그 다리의 진짜 이름 — Central Account Client API

앞서 본 SSM Parameter Store는 값이 마지막에 흘러 들어가는 곳일 뿐, Central Account가 처음부터 참가자 계정에 손을 뻗을 수 있는 것은 Workshop Studio가 공식으로 제공하는 Central Account Client API 덕분입니다. Central Account 안의 IAM 역할에서 SigV4로 서명해야만 호출할 수 있고, 반대로 참가자 계정에서는 이 API를 호출할 수 없습니다 — 항상 운영자 쪽에서 참가자 쪽으로만 열리는 문입니다.

앞의 세 가지 예시에서 운영자가 push-bedrock-key.sh를 실행하거나 텔레메트리 엔드포인트를 내려줄 수 있었던 것도 이 API가 있었기 때문입니다. 중앙의 poller는 CentralListTeams로 이벤트에 속한 팀을 모두 파악하고, CentralGetEventTeamCredentials로 팀마다 임시 자격증명을 받아 그 안에서 ssm:PutParameter를 실행합니다 — SSM Parameter Store는 최종 목적지이고, 거기까지 가는 문을 열어준 것은 이 API입니다.

같은 NotificationBus는 팀/이벤트의 상태가 바뀔 때마다(같은 상태로의 전환은 알리지 않습니다) 신호를 보내주기도 합니다 — team(배포 대기 → 성공/실패 → 종료), event(시작, 일시정지), event_parameters(운영자가 런타임에 값을 바꿈) 세 종류입니다. 팀이 배포에 성공하는 순간을 붙잡아 그 팀에게 환영 메시지를 만들어주는 식의 자동화가 이 신호 위에서 돌아갑니다.

활용 예시

임시 채팅방으로 슬랙을 대신한다

예시 1 aws-workshop-chat github/aws-workshop-chat

워크샵 기간에만 필요한 Q&A·공지 채널을 위해 슬랙 워크스페이스를 새로 만드는 대신, Central Account 안에 가벼운 채팅 서비스를 띄워두고 워크샵이 끝나면 계정과 함께 통째로 치웁니다. 참가자는 별도 가입 절차 없이 자신의 팀 계정 정보로 그대로 들어옵니다.

참가자가 보는 것

• 로그인 — ID는 <참가자 계정 ID>@ws, 비밀번호는 참가자 본인의 랩 환경(code-server) 비밀번호와 동일합니다. 워크샵용으로 새로 외울 계정이 하나 더 늘지 않습니다.
• 질문/채팅 게시판 — 채널, 스레드, 업보트, 이미지 첨부.
• AI 어시스턴트 — 운영자가 올려둔 워크샵 가이드를 근거로 답하는 Bedrock 기반 RAG 챗.

운영자가 보는 것

• 참가자 명단과 QR 코드, 채널별 미해결 질문 필터, 랩 스텝별 태깅.
• 행사 종료 전 대화 전체를 xlsx로 한 번에 내보내는 기능 — 계정이 사라지기 전에 기록을 남기는 유일한 방법입니다.

로그인 자격증명은 채팅 서비스가 참가자 수만큼 스스로 파생시켜 Cognito에 등록하고, 운영자 화면에서 명단으로 확인할 수 있습니다 — 이 사례는 SSM보다는 서비스 자체 등록으로 자격증명 문제를 푼 예로 보면 됩니다.

활용 예시

참가자의 Claude Code 사용량을 한곳에 모은다

예시 2 claude-code-usage-dashboard github/claude-code-usage-dashboard

참가자 각자의 Claude Code가 내보내는 OTel(OpenTelemetry) 메트릭을 참가자 계정 안에만 쌓아두면 운영자는 아무것도 볼 수 없습니다. 대신 Central Account에 ClickHouse를 하나 두고, 참가자 인스턴스의 OTel Collector가 거기로 바로 쏘게 만들면 운영자가 실시간 대시보드로 워크샵 전체 사용량을 지켜볼 수 있습니다.

이때 참가자 인스턴스가 알아야 하는 건 딱 두 가지, ClickHouse 주소와 쓰기용 비밀번호입니다. 이 두 값을 Central Account가 SSM Parameter Store(SecureString)에 기록해두고, 참가자 인스턴스가 부팅할 때 읽어갑니다.

# 참가자 EC2 부팅 스크립트 (user-data.sh)
CH_PASSWORD_SSM_PARAM="/claude-code/ab/clickhouse-writer-password"

CH_PASSWORD="$(aws ssm get-parameter \
  --name "$CH_PASSWORD_SSM_PARAM" --with-decryption \
  --query 'Parameter.Value' --output text)"

# OTel Collector 설정에 주입 → Central의 ClickHouse로 전송 시작

운영자가 보는 것

• Overview — 참가자별/시간대별 사용 추이.
• Cost — 모델·캐시 티어별 토큰 비용.
• Productivity — 코드 라인, 커밋, 코드 제안 수락률.
• Ask Claude — 자연어로 물으면 대시보드가 직접 SQL을 만들어 답해주는 챗 인터페이스.

참가자 인스턴스에는 ssm:GetParameter와 kms:Decrypt 권한만 있으면 되고, 비밀번호 자체는 어떤 코드에도 하드코딩되지 않습니다 — Central Account가 값을 바꾸면 다음 폴링에서 바로 반영됩니다.

활용 예시

API 키를 참가자 한 명 한 명 손대지 않고 나눠준다

# 운영자 (Central Account)
$ ./push-bedrock-key.sh <bedrock-api-key>
# → SSM SecureString에 기록 (/<stack>/bedrock-key-config)

# 참가자 계정 인스턴스 — 60초 주기 타이머
$ ./get-bedrock-key.sh
# → 값이 바뀌어 있으면 즉시 반영, 그대로면 조용히 넘어감

더 넓은 가능성

세 가지는 예시일 뿐이다

Central Account가 실어 나르는 건 결국 "값 하나"입니다. 비밀번호나 API 키가 아니어도, 운영자가 전체 참가자에게 한 번에 밀어주고 싶은 것이라면 같은 다리를 쓸 수 있습니다. 같은 push/poll 구조로 시도해볼 만한 것들입니다:

• 실시간 진행 현황판 — 참가자 인스턴스가 각자의 랩 진행 단계를 Central로 올리고, 운영자는 누가 어느 챕터에서 막혀 있는지 한 화면에서 봅니다. 퍼실리테이터가 순회하며 도와줄 팀을 미리 골라둘 수 있습니다.
• 공유 지식베이스 실시간 갱신 — 진행 중 자료를 고치면 워크샵 챗봇의 RAG 소스를 다시 색인하지 않고도, 변경된 문서 버전을 Central이 내려보내 모든 참가자의 어시스턴트가 즉시 최신 내용으로 답하게 만들 수 있습니다.
• 비용·쿼터 가드레일 — 참가자별 Bedrock 호출량이 임계치를 넘으면 Central이 완화 모드(저비용 모델로 강제 전환 등)를 신호로 내려보내, 예산을 넘기지 않으면서 행사를 계속 진행할 수 있습니다.
• 제한된 라이선스/키 풀링 — 수가 한정된 API 키나 프리뷰 기능 액세스를 팀들이 순번대로 나눠 쓰도록 Central이 배정을 조율해 내려줄 수 있습니다.
• 행사 종료 직전 일괄 백업 — 계정이 회수되기 전, Central이 "지금 내보내라" 신호를 모든 팀에 동시에 내려 결과물을 한 곳에 모을 수 있습니다.

이번 워크샵에서 확인한 것

대규모 워크샵을 흔들림 없이 치르고, 그 과정 자체가 데이터가 됐다

위 구조를 이번 대규모 워크샵에 실제로 얹어본 결과는 두 가지로 요약됩니다. 하나는 운영이 가벼워졌다는 것입니다. 참가자 수가 많아져도 운영자가 손으로 건드려야 하는 지점은 늘지 않았습니다 — 비밀번호를 재발급하거나 키를 교체할 때도 Central Account에서 한 번만 조작하면 됐고, 참가자 각자의 환경은 다음 폴링 주기에 스스로 따라왔습니다.

다른 하나는 워크샵 자체가 관측 대상이 됐다는 것입니다. 참가자들의 Claude Code 사용 흐름이 OTel을 거쳐 Central의 ClickHouse에 실시간으로 쌓이면서, 행사가 끝나야 알 수 있던 것들을 진행 중에 바로 확인할 수 있었습니다 — 참가자들이 Bedrock과 Claude Enterprise 중 어느 쪽으로 더 몰리는지, 어느 랩 구간에서 사용량이 급감해 도움이 필요한 팀이 많아지는지, 모델별·시간대별 채택 곡선이 어떻게 그려지는지 같은, 이전에는 사후 설문으로나 추정하던 지표들이 진행 중에 관측 가능한 데이터포인트로 바뀐 것입니다. 다음 워크샵을 설계할 때 "느낌"이 아니라 이 데이터를 근거로 어느 챕터에 시간을 더 배정할지, 어떤 안내가 더 필요한지를 판단할 수 있게 됐습니다.

부록 · 상세 레퍼런스

contentspec.yaml 전체 스키마

앞의 예시들이 어떻게 동작하는지 이해했다면, 이제 그것을 직접 contentspec.yaml에 쓰는 방법이 필요합니다. Workshop Studio는 값을 주입하는 방식을 세 가지 층으로 나눠 제공합니다 — 서로 독립적이고 용도가 다르므로 섞어 쓰지 않는 것이 중요합니다.

① params — 콘텐츠에 쓰는 값

스키마가 정해져 있지 않은 자유 형식 YAML 딕셔너리입니다. 마크다운 파싱 이전에 치환되기 때문에 코드 블록이나 링크 href처럼 마크다운이 파싱하지 않는 영역에서도 동작합니다. CloudFormation과는 완전히 무관합니다 — 이 값을 인프라로 넘기려면 반드시 ②를 써야 합니다.

params:
  clusterName: workshop-cluster
  contact:
    name: John Doe

# 본문에서: :param{key="clusterName"}
# 값이 없을 때 대체: :param{key=missingKey defaultValue="N/A"}

② CFN parameters — 운영자가 조정 가능한 값

userOverridable: true가 붙은 파라미터만 이벤트 생성/설정 시점에 운영자가 값을 바꿀 수 있습니다. 이 표시가 없으면 모든 이벤트가 같은 값으로 배포됩니다 — 참가자 수나 인스턴스 크기처럼 이벤트마다 달라져야 하는 값에는 반드시 붙여야 합니다.

parameters:
  - templateParameter: InstanceType       # 고정값 — 운영자가 못 바꿈
    defaultValue: t3.large
  - templateParameter: ParticipantCapacity  # 운영자가 이벤트마다 override 가능
    defaultValue: '10'
    userOverridable: true

③ Magic Variables — 자동 주입되는 값

팀 스택용, Central 스택용, IAM 정책 JSON용으로 각각 다른 변수 집합이 제공됩니다. 계정 ID나 ARN을 직접 하드코딩하지 않고 이 변수들, 또는 표준 CFN 유사 파라미터 (!Ref AWS::Region 등)를 쓰는 것이 원칙입니다.

Outputs·Exports 노출 규칙

CFN Outputs/Exports는 기본적으로 참가자에게 보이지 않습니다. 템플릿당 Outputs·Exports는 각각 최대 50개까지만 허용됩니다(Workshop Studio 빌드 검증 기준). 운영자는 항상 Events → Team → Stack Deployments 화면에서 전부 볼 수 있습니다.

infrastructure:
  cloudformationTemplates:
    - templateLocation: static/cfn/workshop-stack.yaml
      label: Workshop Infra
      participantVisibleStackOutputs:   # 방법 1 — 특정 Output만 노출
        - WorkshopUrl
      participantAllStackOutputsVisible: false  # 방법 2 — 전체 노출(기본 false)

전체 예시 — Central Account를 포함한 contentspec.yaml

params:
  clusterNameHint: "예: my-eks-cluster"

infrastructure:
  cloudformationTemplates:
    - templateLocation: static/cfn/team-stack.yaml
      label: Team Infra
      parameters:
        - templateParameter: ParticipantRoleArn
          defaultValue: "{{.ParticipantRoleArn}}"

centralAccountInfrastructure:            # [선택] 공유 리소스가 필요할 때만
  cloudformationTemplates:               # 최대 5개
    - templateLocation: static/cfn/central-stack.yaml
      label: Central Stack
      participantVisibleStackOutputs:
        - LeaderboardUrl
      parameters:
        - templateParameter: NotificationBusArn
          defaultValue: "{{.NotificationBusArn}}"
        - templateParameter: WSEventsAPIEndpoint
          defaultValue: "{{.WSEventsAPIEndpoint}}"
        - templateParameter: WksEventsRegion
          defaultValue: "{{.WSEventsAPIRegion}}"

값 하나가 지나가는 전체 경로 — 예시

ClusterName 하나를 예로 들면 이렇게 흘러갑니다.

1. 작성자가 static/cfn/eks-stack.yaml에 ClusterName 파라미터와 ClusterEndpoint Output을 정의합니다.
2. 빌드 시점에는 defaultValue: workshop-cluster가 기본값으로 적용되고, userOverridable: true이므로 운영자가 이벤트 설정 시 다른 이름으로 바꿀 수 있습니다.
3. 배포 시점에 ParticipantRoleArn은 Workshop Studio가 팀마다 실제 ARN을 계산해 자동으로 주입합니다.
4. ClusterEndpoint Output이 participantVisibleStackOutputs에 있으므로 참가자의 Event Outputs 화면에 노출됩니다.
5. 마크다운 본문에는 별도의 params 값만 텍스트로 보여줄 수 있습니다 — 실제 배포된 클러스터 이름 자체를 보여주려면 Output 노출 설정을 씁니다.

저작 전 체크리스트

• 비밀값을 params나 CFN defaultValue에 평문으로 넣지 않았나요? — 항상 Secrets Manager/SSM SecureString + IAM 정책을 씁니다.
• 계정 ID·ARN을 하드코딩하지 않고 Magic Variable이나 CFN 유사 파라미터를 썼나요?
• 운영자가 이벤트마다 바꿔야 하는 값에 userOverridable: true를 빠뜨리지 않았나요?
• participantAllStackOutputsVisible: true로 내부 진단용 Output까지 한꺼번에 노출하고 있지 않나요? — 필요한 것만 participantVisibleStackOutputs로 고릅니다.
• Central Account가 정말 필요한가요? — 계정 쿼터를 하나 더 쓰는 선택이니, 팀 인프라만으로 충분하다면 Central Account 없이 갑니다.
• centralAccountInfrastructure.cloudformationTemplates가 5개를 넘지 않나요?
• Central Account API 호출은 항상 SigV4 + Central 내부 IAM 역할로만 하고 있나요? — 팀 계정에서 직접 호출은 불가능합니다.

제작 가이드

내가 만드는 워크샵에도 적용하려면

세 사례를 관통하는 패턴을 그대로 가져다 쓰면 됩니다. 새 모듈을 준비할 때 아래 순서를 따라갑니다.

1. Central Account에 올릴 CloudFormation을 만듭니다. contentspec.yaml의 centralAccountInfrastructure.cloudformationTemplates에 등록하면 Workshop Studio가 이벤트 생성/종료와 함께 이 스택을 같이 배포·정리합니다.
2. 내려줄 값을 SSM Parameter Store에 SecureString으로 정의합니다. 비밀번호·키처럼 민감한 값은 항상 SecureString + KMS로, 인스턴스 프로파일에는 ssm:GetParameter와 kms:Decrypt만 최소 권한으로 부여합니다.
3. 참가자 쪽에 값을 읽어가는 타이머를 심습니다. systemd timer나 cron으로 짧은 주기(예: 60초)마다 폴링하고, 값이 바뀌었을 때만 설정을 다시 적용하도록 이전 값의 해시를 비교합니다 — 매번 재시작하지 않게 하는 것이 핵심입니다.
4. 참가자 환경이 값 없이도 홀로 동작하게 만듭니다. Central Account의 값은 "있으면 더 좋은 것"으로 설계합니다. 이렇게 하면 Central Account 배포가 늦거나 문제가 생겨도 워크샵 진행 자체는 막히지 않습니다.
5. 참가자에게 보여줄 출력값만 명시적으로 선언합니다. participantVisibleStackOutputs에 선언한 값만 Event Outputs 화면에 노출됩니다 — Central Account 쪽 리소스는 애초에 이 목록에 넣지 않으므로 운영자만 보는 정보와 참가자에게 보여줄 정보가 자연히 분리됩니다.

제작 가이드

완성된 데모 영상

위 화면들을 이어붙인 32초 데모 영상입니다. SSM 메커니즘 애니메이션 → 실제 운영자 콘솔의 Central infrastructure 탭 → 예시 1(임시 채팅방) → 예시 2(사용량 대시보드) 순서로 구성되어 있습니다. Remotion으로 코드 기반 렌더링했습니다.

아직 남은 것 — 예시 3 · API 키 배포

운영자가 push-bedrock-key.sh를 실행해 팀 계정에 새 키가 반영되는 흐름은 아직 촬영 전입니다. 실제 이벤트 계정에 접근할 수 있을 때 이어서 채웁니다.

• 운영자가 push-bedrock-key.sh를 실행하는 터미널 터미널 캡처
• 참가자 환경에서 다음 폴링 주기에 새 키가 적용되는 로그 터미널 캡처
• Central Account SSM 콘솔에서 파라미터 값이 갱신된 화면 스크린샷