🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🎭 धडा 05 — Stages आणि deployments: रंगीत तालीम आणि खरा प्रयोग

📍 तुम्ही इथे आहात: 12 पैकी धडा 05 · मागे: lesson-04-mapping-validation · पुढे: lesson-06-auth

📦 या ब्रँचमध्ये काय आहे

धडे 01–04, आणि stages (dev, prod), deployments (API चे snapshots), stage variables (तोच route marks-dev किंवा marks-prod मध्ये लिहितो), आणि canary releases. apigw/demo.py मधले stages() तीच request तीन stages ना पाठवते.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

शाळेच्या नाटकाची एक रंगीत तालीम 🎭 असते आणि एक खरा प्रयोग 🎟️. तीच संहिता, तेच कलाकार — पण तालमीत पुठ्ठ्याचे साहित्य आणि लहान सभागृह वापरतात, आणि प्रयोगात खरा रंगमंच आणि खरे प्रेक्षक असतात.

शिक्षिका संहिता बदलते तेव्हा तो बदल जादूने आजच्या रात्रीच्या प्रयोगात येत नाही. कोणीतरी प्रयोगाला नवी संहिता द्यावी लागते — तेच म्हणजे deployment. तोपर्यंत प्रयोग जुनीच संहिता चालवत राहतो.

प्रत्येक stage च्या भिंतीवर स्वतःच्या चिठ्ठ्या असतात: तालमीसाठी "साहित्य खोली 12 मध्ये आहे", प्रयोगासाठी "साहित्य मुख्य भांडारात आहे". त्या चिठ्ठ्या म्हणजे stage variables.

आणि काळजी घेणारी शिक्षिका सगळ्यांच्या आधी प्रेक्षकांच्या एका रांगेला नवा प्रवेश दाखवू शकते — तो म्हणजे canary.

🗺️ आकृती

flowchart LR
    edit["✏️ you change routes"] --> dep["📸 deployment<br/>a snapshot of the API"]
    dep --> dev["🎭 stage dev<br/>table = marks-dev · rate 5 · no cache"]
    dep --> prod["🎟️ stage prod<br/>table = marks-prod · rate 10,000 · cache 300 s"]
    prod -.->|"canary 10%"| new["🐤 new deployment"]
    x["stage test"] -->|"no such stage"| no["🚫 403 Forbidden"]

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/apigateway/lesson-diagrams.html#l05

❓ काय

Deployment (REST APIs) — तुमचे routes, integrations आणि settings यांचा गोठवलेला snapshot. Console मध्ये किंवा CLI ने केलेले बदल, तुम्ही नवे deployment बनवून stage त्याकडे वळवेपर्यंत live नसतात.
Stage — API ची नाव असलेली, call करता येणारी आवृत्ती, जसे dev किंवा prod, स्वतःच्या URL सह: https://abc123.execute-api.ap-south-1.amazonaws.com/prod/students/7. प्रत्येक stage च्या स्वतःच्या throttling, cache, logging आणि tracing settings असतात.
HTTP APIs auto-deploy करू शकतात: autoDeploy चालू असेल तर प्रत्येक बदल त्या stage वर लगेच live होतो. dev साठी सोयीचे; prod साठी दोनदा विचार करा.
Stage variables — stage वरच्या key/value जोड्या, integrations मध्ये ${stageVariables.table} म्हणून वापरल्या जातात आणि Lambda proxy events ना stageVariables म्हणून दिल्या जातात. नेहमीचा वापर: dev ला dev Lambda alias किंवा table कडे वळवणे.
Canary release (REST APIs) — stage त्याच्या traffic चा काही टक्के भाग (उदाहरणार्थ 10%) नव्या deployment कडे, त्याच्या स्वतःच्या stage variables सह, पाठवू शकते; मग तुम्ही ते promote करता किंवा काढून टाकता.

🤔 का

कारण "मी console मध्ये बदलले" म्हणजे release नव्हे. Snapshots मुळे काय live आहे याची नोंद मिळते, परत जाण्याचा मार्ग मिळतो (stage आधीच्या deployment कडे वळवा), आणि खरे users (prod) पाहण्याआधी बदल करून पाहण्यासाठी सुरक्षित जागा (dev) मिळते. Stage variables मुळे प्रत्येक environment साठी एकच API definition राहते, हळूहळू वेगळ्या होत जाणाऱ्या प्रती नाहीत.

🔧 कसे (या repo मध्ये)

apigw/demo.py मधले office() हे Gateway ला दोन stages देते: dev (vars={"table": "marks-dev"}, rate 5, burst 5, cache_ttl=0) आणि prod (marks-prod, 10,000 / 5,000, cache_ttl=300). Gateway._handle() अस्तित्वात नसलेल्या stage ला 403 उत्तर देते, प्रत्येक stage ला स्वतःचा token bucket देते, आणि stage चे vars integration च्या event["stageVariables"] मध्ये ठेवते; add_mark() table चे नाव तिथूनच वाचते. Lab मध्ये वेगळा deployment object नाही: बदललेल्या settings सह नवे office(...) बनवणे हेच "नवे deployment" ची भूमिका बजावते.

🧪 करून पाहा

python3 apigw/demo.py stages
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
gw, c = office()
for stage in ("dev", "prod"):
    print(stage, gw.stages[stage]["vars"], "rate", gw.stages[stage]["rate"], "burst", gw.stages[stage]["burst"], "cache_ttl", gw.stages[stage]["cache_ttl"])
    print("   ", [gw.handle("GET", "/students/7", stage=stage)[1].get("X-Cache") for _ in range(2)])
print("beta:", gw.handle("GET", "/students/7", stage="beta")[0::2])
gw2, _ = office(cache_ttl=0, vars={"table": "marks-prod-v2"})
print("prod after a new 'deployment':", gw2.stages["prod"]["vars"], [gw2.handle("GET", "/students/7")[1].get("X-Cache") for _ in range(2)])
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

stages हे stage dev → 201 {'saved': {'student': '7', 'subject': 'maths', 'mark': 91}, 'table': 'marks-dev'}, 'table': 'marks-prod' सह prod साठी तसेच, आणि stage test → 403 {'message': 'Forbidden'} print करते.

तुमचा snippet [None, None] सह dev {'table': 'marks-dev'} rate 5 burst 5 cache_ttl 0 (dev वर cache नाही — X-Cache header अजिबात नाही), ['Miss', 'Hit'] सह prod {'table': 'marks-prod'} rate 10000 burst 5000 cache_ttl 300, मग beta: (403, {'message': 'Forbidden'}), आणि prod after a new 'deployment': {'table': 'marks-prod-v2'} [None, None] print करतो.

🏁 तुम्ही आत्ताच काय सिद्ध केले

एक API, अनेक stages: प्रत्येक stage वर त्याच route ने वेगळ्या table मध्ये लिहिले, त्याला वेगळ्या limits आणि वेगळा cache होता, आणि कधीच deploy न झालेली stage अस्तित्वातच नसते.

⚠️ नेहमीच्या चुका

REST API बदलणे आणि deploy करायला विसरणे — "माझा बदल काहीच करत नाही"
HTTP API च्या prod stage वर autoDeploy — प्रत्येक प्रयोग live होतो
stage variables मध्ये secrets — ते साधे configuration आहेत, stage वाचू शकणाऱ्या कोणालाही दिसतात; Secrets Manager वापरा
सगळ्यासाठी एकच stage, म्हणजे testing खऱ्या users वरच होते

🏭 प्रत्यक्ष वापरात

On a real account — REST API prod वर deploy करा, मग पुढचे deployment 10% traffic वर करून पाहा, मग ते promote करा:

aws apigateway create-deployment --rest-api-id abc123 --stage-name prod \
    --description "marks v1"
aws apigateway update-stage --rest-api-id abc123 --stage-name prod \
    --patch-operations op=replace,path=/variables/table,value=marks-prod
aws apigateway create-deployment --rest-api-id abc123 --stage-name prod \
    --canary-settings percentTraffic=10.0 --description "marks v2 canary"
# promote: the canary's deployment becomes the stage's deployment, canary back to 0%
aws apigateway update-stage --rest-api-id abc123 --stage-name prod --patch-operations \
    '[{"op":"replace","path":"/canarySettings/percentTraffic","value":"0.0"},
      {"op":"copy","from":"/canarySettings/deploymentId","path":"/deploymentId"}]'

Terraform — API definition बदलली की प्रत्येक वेळी नवे deployment:

resource "aws_api_gateway_deployment" "school" {
  rest_api_id = aws_api_gateway_rest_api.school.id
  triggers    = { redeploy = sha1(jsonencode(aws_api_gateway_rest_api.school.body)) }
  lifecycle   { create_before_destroy = true }
}
resource "aws_api_gateway_stage" "prod" {
  rest_api_id   = aws_api_gateway_rest_api.school.id
  deployment_id = aws_api_gateway_deployment.school.id
  stage_name    = "prod"
  variables     = { table = "marks-prod" }
}

🏭 Production मध्ये हे का महत्त्वाचे: releases pipeline मधून जातात — dev वर deploy, test, prod वर deploy (बदल धोकादायक असेल तर canary सह) — आणि आधीचा deployment id लिहून ठेवलेला असतो, म्हणजे rollback फक्त एका command चे काम ठरते.

⏭️ पुढे

कोणीही दार ठोठावू शकतो. आता badge ची तपासणी: आत कोण येऊ शकतो — IAM, JWT आणि Lambda authorizers.

git checkout lesson-06-auth

🎭 Lesson 05 — Stages & deployments: the rehearsal and the real show

📍 You are here: Lesson 05 of 12 · Previous: lesson-04-mapping-validation · Next: lesson-06-auth

📦 What's in this branch

Lessons 01–04, plus stages (dev, prod), deployments (snapshots of the API), stage variables (the same route writes to marks-dev or marks-prod), and canary releases. stages() in apigw/demo.py sends the same request to three stages.

🧒 Explain like I'm 5

The school play has a rehearsal 🎭 and a real show 🎟️. Same script, same actors — but the rehearsal uses cardboard props and a small hall, and the show uses the real stage and the real audience.

When the teacher changes the script, the change is not in tonight's show by magic. Someone must hand the new script to the show — that is a deployment. Until then, the show keeps playing the old script.

Each stage also has its own notes on the wall: "props are in room 12" for the rehearsal, "props are in the main store" for the show. Those notes are stage variables.

And a careful teacher can let one row of the audience see the new scene first — a canary — before everyone does.

🗺️ Diagram

flowchart LR
    edit["✏️ you change routes"] --> dep["📸 deployment<br/>a snapshot of the API"]
    dep --> dev["🎭 stage dev<br/>table = marks-dev · rate 5 · no cache"]
    dep --> prod["🎟️ stage prod<br/>table = marks-prod · rate 10,000 · cache 300 s"]
    prod -.->|"canary 10%"| new["🐤 new deployment"]
    x["stage test"] -->|"no such stage"| no["🚫 403 Forbidden"]

🗺️ Drawn version + a lab: https://school-edh.pages.dev/apigateway/lesson-diagrams.html#l05

❓ What

Deployment (REST APIs) — a frozen snapshot of your routes, integrations and settings. Edits you make in the console or with the CLI are not live until you create a new deployment and point a stage at it.
Stage — a named, callable version of the API, such as dev or prod, with its own URL: https://abc123.execute-api.ap-south-1.amazonaws.com/prod/students/7. Each stage has its own throttling, cache, logging and tracing settings.
HTTP APIs can auto-deploy: with autoDeploy on, every change goes live on that stage straight away. Convenient for dev; think twice for prod.
Stage variables — key/value pairs on a stage, used in integrations as ${stageVariables.table} and passed to Lambda proxy events as stageVariables. Typical use: point dev at a dev Lambda alias or table.
Canary release (REST APIs) — a stage can send a percentage of its traffic (for example 10%) to a new deployment, with its own stage variables; then you promote it or remove it.

🤔 Why

Because "I changed it in the console" is not a release. Snapshots give you a record of what is live, a way back (point the stage at the previous deployment), and a safe place to try changes (dev) before real users see them (prod). Stage variables keep one API definition for every environment instead of copies that drift.

🔧 How (in this repo)

office() in apigw/demo.py passes two stages to Gateway: dev (vars={"table": "marks-dev"}, rate 5, burst 5, cache_ttl=0) and prod (marks-prod, 10,000 / 5,000, cache_ttl=300). Gateway._handle() answers 403 for a stage that does not exist, gives each stage its own token bucket, and puts the stage's vars into the integration's event["stageVariables"]; add_mark() reads the table name from there. The lab has no separate deployment object: building a new office(...) with changed settings plays the part of "a new deployment".

🧪 Try it

python3 apigw/demo.py stages
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
gw, c = office()
for stage in ("dev", "prod"):
    print(stage, gw.stages[stage]["vars"], "rate", gw.stages[stage]["rate"], "burst", gw.stages[stage]["burst"], "cache_ttl", gw.stages[stage]["cache_ttl"])
    print("   ", [gw.handle("GET", "/students/7", stage=stage)[1].get("X-Cache") for _ in range(2)])
print("beta:", gw.handle("GET", "/students/7", stage="beta")[0::2])
gw2, _ = office(cache_ttl=0, vars={"table": "marks-prod-v2"})
print("prod after a new 'deployment':", gw2.stages["prod"]["vars"], [gw2.handle("GET", "/students/7")[1].get("X-Cache") for _ in range(2)])
EOF

✅ Verify — what you should see

stages prints stage dev → 201 {'saved': {'student': '7', 'subject': 'maths', 'mark': 91}, 'table': 'marks-dev'}, the same for prod with 'table': 'marks-prod', and stage test → 403 {'message': 'Forbidden'}.

Your snippet prints dev {'table': 'marks-dev'} rate 5 burst 5 cache_ttl 0 with [None, None] (no cache on dev — no X-Cache header at all), prod {'table': 'marks-prod'} rate 10000 burst 5000 cache_ttl 300 with ['Miss', 'Hit'], then beta: (403, {'message': 'Forbidden'}), and prod after a new 'deployment': {'table': 'marks-prod-v2'} [None, None].

🏁 What you just proved

One API, many stages: the same route wrote to a different table, had different limits and a different cache per stage, and a stage that was never deployed does not exist.

⚠️ Common mistakes

editing a REST API and forgetting to deploy — "my change does nothing"
autoDeploy on the prod stage of an HTTP API — every experiment goes live
secrets in stage variables — they are plain configuration, visible to anyone who can read the stage; use Secrets Manager
one stage for everything, so testing happens on real users

🏭 In production

On a real account — deploy a REST API to prod, then try the next deployment on 10% of traffic, then promote it:

aws apigateway create-deployment --rest-api-id abc123 --stage-name prod \
    --description "marks v1"
aws apigateway update-stage --rest-api-id abc123 --stage-name prod \
    --patch-operations op=replace,path=/variables/table,value=marks-prod
aws apigateway create-deployment --rest-api-id abc123 --stage-name prod \
    --canary-settings percentTraffic=10.0 --description "marks v2 canary"
# promote: the canary's deployment becomes the stage's deployment, canary back to 0%
aws apigateway update-stage --rest-api-id abc123 --stage-name prod --patch-operations \
    '[{"op":"replace","path":"/canarySettings/percentTraffic","value":"0.0"},
      {"op":"copy","from":"/canarySettings/deploymentId","path":"/deploymentId"}]'

Terraform — a new deployment whenever the API definition changes:

resource "aws_api_gateway_deployment" "school" {
  rest_api_id = aws_api_gateway_rest_api.school.id
  triggers    = { redeploy = sha1(jsonencode(aws_api_gateway_rest_api.school.body)) }
  lifecycle   { create_before_destroy = true }
}
resource "aws_api_gateway_stage" "prod" {
  rest_api_id   = aws_api_gateway_rest_api.school.id
  deployment_id = aws_api_gateway_deployment.school.id
  stage_name    = "prod"
  variables     = { table = "marks-prod" }
}

🏭 Why this matters in production: releases through a pipeline — deploy to dev, test, deploy to prod (with a canary when the change is risky) — and the previous deployment id written down, so rolling back is one command.

⏭️ Next

Anyone can knock. Now the badge check: who may come in — IAM, JWT and Lambda authorizers.

git checkout lesson-06-auth

← Previousmapping validation Next →auth

This page is the lesson's README from the lesson-05-stages-deployments branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.