ระดับ 5a · บทที่ 3/5

CI/CD ไร้คีย์ถาวร — GitHub Actions + OIDC role, deploy อัตโนมัติ และ approval ก่อนขึ้น prod

⏱ 50 นาทีลองในAWS Console ↗

เป้าหมาย

ให้ GitHub Actions deploy CDK stack จากบท 02 ได้ โดยไม่มี access key เก็บใน GitHub เลย ใช้ OIDC ขอ credential ชั่วคราวทุกรอบ จำกัดว่า repo/branch/environment ไหนเท่านั้นที่ assume role ได้ และให้ prod ต้องมีคนกดอนุมัติ

ทำไมห้ามใช้ access key ใน CI

access key ใน GitHub Secrets OIDC
อายุยาวจนกว่าจะหมุน — หลุดครั้งเดียวใช้ได้เรื่อยๆ credential อายุสั้น (ค่าเริ่มต้น 1 ชม.) หมดเองหลังจบ job
ใครแก้ workflow ได้ก็ขโมยไปได้ trust policy จำกัดได้ถึงระดับ repo + branch + environment
ต้องหมุนคีย์เอง ไม่มีอะไรให้หมุน
CloudTrail เห็นแค่ชื่อ IAM user CloudTrail เห็น role session ต่อ run

OIDC ทำงานอย่างไร

GitHub job ──ขอ JWT (id-token: write)──▶ GitHub OIDC (token.actions.githubusercontent.com)
     │ JWT มี claim: aud=sts.amazonaws.com, sub=repo:ORG/REPO:ref:refs/heads/main ...
     ▼
AWS STS AssumeRoleWithWebIdentity ──ตรวจลายเซ็น + เทียบ trust policy──▶ credential ชั่วคราว

รูปแบบ sub claim ที่ต้องรู้ (ค่าเริ่มต้นของ GitHub)

job แบบไหน sub
push ไป branch repo:ORG/REPO:ref:refs/heads/main
job ที่มี environment: prod repo:ORG/REPO:environment:prod (ไม่มี ref แล้ว!)
pull request repo:ORG/REPO:pull_request
tag repo:ORG/REPO:ref:refs/tags/v1.2.3

จุดพลาดอันดับหนึ่ง: ใส่ environment: ใน job แล้ว trust policy ยังเช็ก ref:refs/heads/main → Not authorized to perform sts:AssumeRoleWithWebIdentity

ออกแบบ role แบบ least privilege

  • แยก role ตามหน้าที่: gh-cdk-diff (อ่านอย่างเดียว ใช้กับ PR) และ gh-cdk-deploy (ใช้กับ main/prod)
  • role ของ CI ไม่ต้องมีสิทธิ์สร้าง Lambda/DynamoDB เอง — ให้แค่ sts:AssumeRole ไปยัง role ที่ CDK bootstrap สร้างไว้ (cdk-hnb659fds-deploy-role-*, file-publishing-role, lookup-role ฯลฯ) สิทธิ์จริงอยู่ที่ CloudFormation execution role
  • อย่าใช้ StringLike กับ repo:ORG/* — ทุก repo ในองค์กร (รวม fork ภายใน) จะ deploy prod ได้
  • prod ควรอยู่บัญชีแยก + role แยกที่ trust เฉพาะ environment:prod

Approval ก่อนขึ้น prod

GitHub → repo Settings → Environments → New environment prod → เปิด Required reviewers และจำกัด Deployment branches เป็น main → job ที่ระบุ environment: prod จะหยุดรอคนกด Approve และ sub จะเป็น environment:prod ที่ AWS เช็กได้

ลองเลย 🧪

ต้องมี repo บน GitHub ที่มีโค้ด notes-api จากบท 02 (ตัวอย่างใช้ my-org/notes-api — เปลี่ยนเป็นของคุณ) · ทำในบัญชี dev

ทดลอง A — สร้าง OIDC provider และ role

aws sso login --profile dev
export AWS_PROFILE=dev AWS_REGION=ap-southeast-1
ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REPO="[my-org/notes-api]"

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com

ผลที่ควรเห็น:

{
    "OpenIDConnectProviderArn": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
}

(ถ้าได้ EntityAlreadyExists แปลว่ามีอยู่แล้ว ใช้ตัวเดิมได้ — หนึ่งบัญชีมี provider URL นี้ได้ตัวเดียว · ไม่ต้องใส่ thumbprint เพราะ AWS ตรวจใบรับรองของ GitHub ด้วย CA ที่เชื่อถือเอง)

trust policy — อนุญาตเฉพาะ branch main และ environment prod ของ repo นี้

cat > trust.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::${ACCOUNT}:oidc-provider/token.actions.githubusercontent.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
      "StringLike": { "token.actions.githubusercontent.com:sub": [
        "repo:${REPO}:ref:refs/heads/main",
        "repo:${REPO}:environment:prod"
      ] }
    }
  }]
}
EOF

cat > deploy-perms.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "AssumeCdkBootstrapRoles",
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::${ACCOUNT}:role/cdk-hnb659fds-*-${ACCOUNT}-ap-southeast-1"
  }]
}
EOF

aws iam create-role --role-name gh-cdk-deploy \
  --assume-role-policy-document file://trust.json --max-session-duration 3600 \
  --query Role.Arn --output text
aws iam put-role-policy --role-name gh-cdk-deploy \
  --policy-name assume-cdk-roles --policy-document file://deploy-perms.json

ผลที่ควรเห็น: arn:aws:iam::123456789012:role/gh-cdk-deploy — เอาค่านี้ไปใส่ GitHub Settings → Secrets and variables → Actions → Variables ชื่อ AWS_DEPLOY_ROLE_ARN (เป็น variable ไม่ใช่ secret ก็ได้ เพราะ ARN ไม่ใช่ความลับ)

ทดลอง B — workflow ไฟล์ .github/workflows/deploy.yml

name: deploy
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false   # อย่ายกเลิก deploy กลางทาง stack จะค้าง

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }
      - run: npm ci
      - run: npm test
      - run: npx cdk synth -c stage=dev > /dev/null

  deploy-dev:
    if: github.event_name == 'push'
    needs: test
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }
      - run: npm ci
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ vars.AWS_DEPLOY_ROLE_ARN }}
          aws-region: ap-southeast-1
      - run: aws sts get-caller-identity
      - run: npx cdk deploy -c stage=dev --require-approval never

  deploy-prod:
    needs: deploy-dev
    runs-on: ubuntu-latest
    environment: prod          # หยุดรอ reviewer + sub กลายเป็น environment:prod
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }
      - run: npm ci
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ vars.AWS_DEPLOY_ROLE_ARN }}
          aws-region: ap-southeast-1
      - run: npx cdk diff -c stage=prod
      - run: npx cdk deploy -c stage=prod --require-approval never

push ขึ้น main แล้วดูแท็บ Actions ผลที่ควรเห็น: job deploy-dev ขั้น aws sts get-caller-identity แสดง

"Arn": "arn:aws:sts::123456789012:assumed-role/gh-cdk-deploy/GitHubActions"

และ deploy-prod ขึ้นสถานะ Waiting — review required จนกว่าจะกด Approve

ในงานจริง ใช้ role แยกสำหรับ prod ในบัญชี prod — ตัวอย่างนี้ใช้ role เดียวเพื่อให้แล็บสั้น

ทดลอง C — พิสูจน์ว่าล็อกได้จริง สร้าง branch feature/x แก้ใน branch นั้นให้ on.push.branches เป็น [main, feature/x] แล้ว push → job deploy-dev จะรันบน branch นี้ ผลที่ควรเห็น: ขั้น configure-aws-credentials ของ deploy-dev ล้มด้วย Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity — ถูกต้อง เพราะ sub เป็น ref:refs/heads/feature/x (ลบ branch ทิ้งหลังทดสอบ อย่า merge การแก้นี้เข้า main)

ดูใน CloudTrail ว่าใคร assume

aws cloudtrail lookup-events --region ap-southeast-1 \
  --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity \
  --max-results 3 --query "Events[].[EventTime,Username]" --output table

เก็บกวาด (ถ้าไม่ใช้ต่อ)

npx cdk destroy -c stage=dev --force
npx cdk destroy -c stage=prod --force   # ตาราง prod ถูก RETAIN — ลบเองในคอนโซล DynamoDB ถ้าตั้งใจ
aws iam delete-role-policy --role-name gh-cdk-deploy --policy-name assume-cdk-roles
aws iam delete-role --role-name gh-cdk-deploy
# OIDC provider ไม่คิดเงิน เก็บไว้ได้ ถ้าจะลบ (และไม่มี role อื่นใช้อยู่):
# aws iam delete-open-id-connect-provider --open-id-connect-provider-arn "arn:aws:iam::${ACCOUNT}:oidc-provider/token.actions.githubusercontent.com"

ถ้าพัง: Credentials could not be loaded → ลืม permissions: id-token: write ใน job · Not authorized ... AssumeRoleWithWebIdentity → เทียบ sub จริงกับ trust policy (ชื่อ org/repo ตัวพิมพ์เล็ก-ใหญ่ต้องตรง) · current credentials could not be used to assume 'cdk-hnb659fds-deploy-role' → ARN ใน deploy-perms.json ผิด region/account หรือยังไม่ bootstrap

กับดักที่เจอบ่อย

อาการ สาเหตุ / แก้
job prod assume ไม่ได้ แต่ dev ได้ ใส่ environment: prod แล้ว sub เปลี่ยน — เพิ่ม repo:ORG/REPO:environment:prod ใน trust
ใครเปิด PR จาก fork ก็ deploy ได้ trust ใช้ repo:ORG/* หรือ * — ระบุ repo และ ref/environment ให้ชัด
ใส่ id-token: write ระดับ workflow ทุก job ได้ token หมด ใส่เฉพาะ job ที่ต้องคุย AWS
workflow ถูกยกเลิกกลาง deploy แล้ว stack ค้าง UPDATE_IN_PROGRESS cancel-in-progress: false และอย่ากด Cancel ระหว่าง deploy
role CI มี AdministratorAccess ให้แค่ assume CDK bootstrap roles และจำกัด CloudFormation execution policy ตอน bootstrap
ยังมี AWS_ACCESS_KEY_ID ค้างใน Secrets ลบทิ้ง และ deactivate คีย์ของ IAM user นั้น

สรุปจำง่าย

CI ห้ามมีคีย์ถาวร ใช้ OIDC — trust ล็อก aud + sub ถึงระดับ repo/branch/environment — job ที่มี environment ได้ sub แบบ environment:<ชื่อ> — role CI แค่ assume role ของ CDK — prod ต้องมี required reviewers