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

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

🏷️ धडा 10 — Custom domains आणि TLS: दारावरचा नावफलक

📍 तुम्ही इथे आहात: 12 पैकी धडा 10 · मागे: lesson-09-cors · पुढे: lesson-11-monitoring

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

धडे 01–09, आणि office साठी खरे नाव: AWS च्या यादृच्छिक पत्त्याऐवजी api.school.example — ACM certificate (आणि ते कोणत्या Region मध्ये असायला हवे), DNS, base path mappings (/v1, /v2), तीन endpoint types, किमान TLS version आणि mutual TLS. apigw/demo.py मधले domains() checklist छापते, आणि तुम्ही lab office समोर एक छोटे base path mapping बांधता.

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

Office चा खरा पत्ता म्हणजे एक लांबलचक code: abc123.execute-api.ap-south-1.amazonaws.com. तो कोणालाच लक्षात राहत नाही, आणि शाळेने नवे office बांधले तर code बदलतो आणि प्रत्येक पालकाला नवा code शिकावा लागतो.

म्हणून शाळा फाटकावर एक नावफलक 🏷️ लावते: api.school.example. नावफलकाच्या मागे दोन दारे असू शकतात: /v1 जुन्या office कडे जाते आणि /v2 नव्या office कडे. पालकांसाठी नाव कायम तेच राहते.

नावफलक खरोखर शाळेचाच आहे हे सिद्ध करण्यासाठी फाटक एक certificate दाखवते — विश्वासू office ने सही केलेला कागद (TLS certificate). काही partner शाळांना आत येण्याआधी त्यांचे स्वतःचे certificate सुद्धा दाखवावे लागते — हेच mutual TLS.

🗺️ आकृती

flowchart LR
    user["🙋 https://api.school.example/v1/students/7"] --> dns["📖 Route 53 alias<br/>api.school.example"]
    dns --> dom["🏷️ custom domain<br/>ACM certificate · TLS 1.2 minimum"]
    dom -->|"base path /v1"| a1["🛎️ school-api · prod"]
    dom -->|"base path /v2"| a2["🛎️ school-api-v2 · prod"]
    dom -.->|"no mapping for /students/7"| no["🚫 403"]

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

❓ काय

Custom domain name — तुमच्या मालकीचे नाव (api.school.example) जे तुमच्या API stages कडे निर्देश करते. Default execute-api पत्ता तुम्ही disable करेपर्यंत चालूच राहतो.
Endpoint types —
- edge-optimized (फक्त REST): requests CloudFront च्या edge network मधून आत येतात, जगभर पसरलेल्या clients साठी चांगले;
- regional: requests थेट Region मध्ये जातात — clients त्याच Region मध्ये असतील किंवा तुम्ही समोर स्वतःचे CloudFront ठेवत असाल तेव्हा सर्वोत्तम;
- private (फक्त REST): फक्त VPC च्या आतूनच पोहोचता येते (धडा 12).
Certificate — AWS Certificate Manager (ACM) कडून. edge-optimized साठी ते us-east-1 मध्येच हवे; regional साठी ते API च्या त्याच Region मध्ये हवे.
DNS — domain च्या target कडे जाणारा Route 53 alias record (A / AAAA): edge-optimized साठी CloudFront नाव, regional साठी d-….execute-api… regional नाव.
Base path mapping (REST, v2 API मध्ये "API mappings") — /v1 → API + stage, /v2 → दुसरा API + stage. रिकामा base path संपूर्ण domain एकाच API कडे नेतो.
Security policy — domain स्वीकारतो ते किमान TLS version. TLS 1.2 (TLS_1_2) निवडा.
Mutual TLS (mTLS) — regional custom domains वर, clients नी तुमच्या truststore मधल्या (S3 मधली PEM file) CA ने सही केलेले certificate दाखवायलाच हवे. Partners आणि devices साठी चांगले.

🤔 का

कारण पत्ता म्हणजे प्रत्येक client ला दिलेले वचन. Custom domain मुळे तुम्ही नव्या API कडे, नव्या Region कडे किंवा नव्या प्रकाराकडे (REST ते HTTP) जाऊ शकता, कोणालाही त्यांचा code बदलायला न सांगता. Base paths मुळे clients हळूहळू सरकत असताना v1 आणि v2 शेजारी शेजारी राहू शकतात. आणि TLS settings ठरवतात की कोणते जुने, कमकुवत clients तुम्ही अजूनही स्वीकारता.

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

Lab मध्ये DNS किंवा certificates नाहीत, म्हणून apigw/demo.py मधले domains() checklist छापते. तुम्ही चालवू शकता तो भाग म्हणजे base path mapping: Gateway.handle() समोरचे एक छोटेसे function जे path च्या पहिल्या भागावरून API आणि stage निवडते, तो भाग काढून टाकते, आणि उरलेले पुढे पाठवते — custom domain चे mappings नेमके हेच काम करतात.

🧪 करून पाहा

python3 apigw/demo.py domains
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
v1, _ = office()
MAPPINGS = {"/v1": (v1, "prod"), "/v1-dev": (v1, "dev")}      # api.school.example/<base path> → (API, stage)
def custom_domain(method, url_path):
    for base in sorted(MAPPINGS, key=len, reverse=True):
        if url_path.startswith(base + "/"):
            api, stage = MAPPINGS[base]
            return api.handle(method, url_path[len(base):], stage=stage)
    return 403, {}, {"message": "Forbidden"}
for p in ("/v1/students/7", "/v1-dev/students/9", "/v2/students/7", "/students/7"):
    st, _, out = custom_domain("GET", p); print(f"api.school.example{p:<18} → {st} {out}")
EOF

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

domains पाच ओळी छापते, त्यांपैकी certificate ACM — in us-east-1 for edge-optimized, in the API's Region for regional, base path mapping api.school.example/v1 → school-api prod · /v2 → school-api-v2 prod आणि TLS security policy TLS 1.2 minimum · mutual TLS for partners with client certificates.

तुमचा snippet हे छापतो:

api.school.example/v1/students/7     → 200 {'id': '7', 'name': 'Aishwarya', 'class': '8B'}
api.school.example/v1-dev/students/9 → 200 {'id': '9', 'name': 'Katrina', 'class': '9A'}
api.school.example/v2/students/7     → 403 {'message': 'Forbidden'}
api.school.example/students/7        → 403 {'message': 'Forbidden'}

/v2 ला अजून mapping नाही, आणि base path नसलेला path कशाशीच जुळत नाही.

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

एक नाव अनेक APIs आणि stages कडे नेऊ शकते; base path दार निवडतो, आणि मागच्या API ला base path कधी दिसतच नाही.

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

edge-optimized domain चे certificate us-east-1 ऐवजी API च्या Region मध्ये बनवणे
custom domain च्या target कडे alias ऐवजी execute-api पत्त्याकडे CNAME — TLS अपयशी ठरते
default execute-api endpoint उघडा ठेवणे, त्यामुळे callers custom domain मार्गावरचे mTLS किंवा WAF टाळतात
"जुन्या clients साठी" TLS 1.0 ला परवानगी देणे आणि ती कधीच न काढणे
edge-optimized domain वर mTLS — त्यासाठी regional domain लागतो

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

खऱ्या account वर — TLS 1.2 सह regional custom domain, /v1 mapping, आणि DNS:

aws apigateway create-domain-name --domain-name api.school.example \
    --regional-certificate-arn arn:aws:acm:ap-south-1:111122223333:certificate/1234abcd-12ab-34cd-56ef-1234567890ab \
    --endpoint-configuration types=REGIONAL --security-policy TLS_1_2
aws apigateway create-base-path-mapping --domain-name api.school.example \
    --rest-api-id abc123 --stage prod --base-path v1
aws apigateway get-domain-name --domain-name api.school.example \
    --query '{target:regionalDomainName,zone:regionalHostedZoneId}'

Partners साठी mutual TLS (S3 मध्ये truststore):

aws apigateway create-domain-name --domain-name partners.school.example \
    --regional-certificate-arn arn:aws:acm:ap-south-1:111122223333:certificate/1234abcd-12ab-34cd-56ef-1234567890ab \
    --endpoint-configuration types=REGIONAL --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://school-truststore/partners.pem

Terraform (HTTP API mapping):

resource "aws_apigatewayv2_api_mapping" "v1" {
  api_id          = aws_apigatewayv2_api.school.id
  domain_name     = aws_apigatewayv2_domain_name.api.id
  stage           = aws_apigatewayv2_stage.prod.id
  api_mapping_key = "v1"
}

🏭 Production मध्ये हे का महत्त्वाचे आहे: फक्त custom domain प्रसिद्ध करा, clients सरकल्यावर default endpoint disable करा, किमान TLS 1.2 ठेवा, आणि ACM ला certificate renew करू द्या — validation कधी अपयशी ठरले तर alarm सह.

⏭️ पुढे

Office ला नाव मिळाले. आता: ते निरोगी आहे हे तुम्हाला कसे कळणार? Dashboard आणि stopwatch — monitoring.

git checkout lesson-11-monitoring

🏷️ Lesson 10 — Custom domains & TLS: the name plate on the door

📍 You are here: Lesson 10 of 12 · Previous: lesson-09-cors · Next: lesson-11-monitoring

📦 What's in this branch

Lessons 01–09, plus a real name for the office: api.school.example instead of a random AWS address — the ACM certificate (and which Region it must live in), DNS, base path mappings (/v1, /v2), the three endpoint types, the minimum TLS version and mutual TLS. domains() in apigw/demo.py prints the checklist, and you build a small base path mapping in front of the lab office.

🧒 Explain like I'm 5

The office's real address is a long code: abc123.execute-api.ap-south-1.amazonaws.com. Nobody can remember it, and if the school builds a new office, the code changes and every parent must learn a new one.

So the school puts a name plate 🏷️ on the gate: api.school.example. Behind the name plate there can be two doors: /v1 leads to the old office and /v2 to the new one. Parents keep the same name forever.

To prove the name plate is really the school's, the gate shows a certificate — a paper signed by a trusted office (the TLS certificate). Some partner schools must show their own certificate too before they come in — that is mutual TLS.

🗺️ Diagram

flowchart LR
    user["🙋 https://api.school.example/v1/students/7"] --> dns["📖 Route 53 alias<br/>api.school.example"]
    dns --> dom["🏷️ custom domain<br/>ACM certificate · TLS 1.2 minimum"]
    dom -->|"base path /v1"| a1["🛎️ school-api · prod"]
    dom -->|"base path /v2"| a2["🛎️ school-api-v2 · prod"]
    dom -.->|"no mapping for /students/7"| no["🚫 403"]

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

❓ What

Custom domain name — a name you own (api.school.example) that points at your API stages. The default execute-api address keeps working unless you disable it.
Endpoint types —
- edge-optimized (REST only): requests enter through CloudFront's edge network, good for clients spread around the world;
- regional: requests go straight to the Region — best when clients are in the same Region or when you put your own CloudFront in front;
- private (REST only): reachable only from inside a VPC (lesson 12).
Certificate — from AWS Certificate Manager (ACM). For edge-optimized it must be in us-east-1; for regional it must be in the same Region as the API.
DNS — a Route 53 alias record (A / AAAA) to the domain's target: the CloudFront name for edge-optimized, the d-….execute-api… regional name for regional.
Base path mapping (REST, "API mappings" in the v2 API) — /v1 → API + stage, /v2 → another API + stage. An empty base path maps the whole domain to one API.
Security policy — the minimum TLS version the domain accepts. Choose TLS 1.2 (TLS_1_2).
Mutual TLS (mTLS) — on regional custom domains, clients must present a certificate signed by a CA in your truststore (a PEM file in S3). Good for partners and devices.

🤔 Why

Because an address is a promise to every client. A custom domain lets you move to a new API, a new Region or a new kind (REST to HTTP) without asking anyone to change their code. Base paths let v1 and v2 live side by side while clients move. And the TLS settings decide which old, weak clients you still accept.

🔧 How (in this repo)

The lab has no DNS or certificates, so domains() in apigw/demo.py prints the checklist. The part you can run is a base path mapping: a tiny function in front of Gateway.handle() that picks the API and stage from the first path part, strips it, and forwards the rest — the same job a custom domain's mappings do.

🧪 Try it

python3 apigw/demo.py domains
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
v1, _ = office()
MAPPINGS = {"/v1": (v1, "prod"), "/v1-dev": (v1, "dev")}      # api.school.example/<base path> → (API, stage)
def custom_domain(method, url_path):
    for base in sorted(MAPPINGS, key=len, reverse=True):
        if url_path.startswith(base + "/"):
            api, stage = MAPPINGS[base]
            return api.handle(method, url_path[len(base):], stage=stage)
    return 403, {}, {"message": "Forbidden"}
for p in ("/v1/students/7", "/v1-dev/students/9", "/v2/students/7", "/students/7"):
    st, _, out = custom_domain("GET", p); print(f"api.school.example{p:<18} → {st} {out}")
EOF

✅ Verify — what you should see

domains prints five rows, among them certificate ACM — in us-east-1 for edge-optimized, in the API's Region for regional, base path mapping api.school.example/v1 → school-api prod · /v2 → school-api-v2 prod and TLS security policy TLS 1.2 minimum · mutual TLS for partners with client certificates.

Your snippet prints:

api.school.example/v1/students/7     → 200 {'id': '7', 'name': 'Aishwarya', 'class': '8B'}
api.school.example/v1-dev/students/9 → 200 {'id': '9', 'name': 'Katrina', 'class': '9A'}
api.school.example/v2/students/7     → 403 {'message': 'Forbidden'}
api.school.example/students/7        → 403 {'message': 'Forbidden'}

/v2 has no mapping yet, and a path with no base path matches nothing.

🏁 What you just proved

One name can lead to many APIs and stages; the base path picks the door, and the API behind it never sees the base path.

⚠️ Common mistakes

the certificate for an edge-optimized domain created in the API's Region instead of us-east-1
a CNAME to the execute-api address instead of an alias to the custom domain's target — TLS fails
leaving the default execute-api endpoint open, so callers skip the mTLS or the WAF on the custom domain path
allowing TLS 1.0 "for old clients" and never removing it
mTLS on an edge-optimized domain — it needs a regional one

🏭 In production

On a real account — a regional custom domain with TLS 1.2, a /v1 mapping, and DNS:

aws apigateway create-domain-name --domain-name api.school.example \
    --regional-certificate-arn arn:aws:acm:ap-south-1:111122223333:certificate/1234abcd-12ab-34cd-56ef-1234567890ab \
    --endpoint-configuration types=REGIONAL --security-policy TLS_1_2
aws apigateway create-base-path-mapping --domain-name api.school.example \
    --rest-api-id abc123 --stage prod --base-path v1
aws apigateway get-domain-name --domain-name api.school.example \
    --query '{target:regionalDomainName,zone:regionalHostedZoneId}'

Mutual TLS for partners (truststore in S3):

aws apigateway create-domain-name --domain-name partners.school.example \
    --regional-certificate-arn arn:aws:acm:ap-south-1:111122223333:certificate/1234abcd-12ab-34cd-56ef-1234567890ab \
    --endpoint-configuration types=REGIONAL --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://school-truststore/partners.pem

Terraform (HTTP API mapping):

resource "aws_apigatewayv2_api_mapping" "v1" {
  api_id          = aws_apigatewayv2_api.school.id
  domain_name     = aws_apigatewayv2_domain_name.api.id
  stage           = aws_apigatewayv2_stage.prod.id
  api_mapping_key = "v1"
}

🏭 Why this matters in production: publish only the custom domain, disable the default endpoint once clients have moved, set TLS 1.2 as the minimum, and let ACM renew the certificate — with an alarm if validation ever fails.

⏭️ Next

The office has a name. Now: how do you know it is healthy? The dashboard and the stopwatch — monitoring.

git checkout lesson-11-monitoring

← Previouscors Next →monitoring

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