Traefik (v3) पर कस्टम SSL सर्टिफिकेट कैसे इंस्टॉल करें

Traefik ACME के ज़रिए अपने-आप सर्टिफिकेट जारी करने के लिए मशहूर है। लेकिन कभी-कभी आपको इसके बजाय अपना खुद का सर्टिफिकेट लाना पड़ता है — GetHTTPS द्वारा जारी किया गया, किसी कॉर्पोरेट/आंतरिक CA का, या कोई वाइल्डकार्ड जिसे आप कहीं और मैनेज करते हैं। यह गाइड आपको ठीक-ठीक दिखाती है कि Traefik v3 पर यह कैसे करें।

शुरुआत में समझने वाली अहम बात: आप किसी Docker लेबल से सर्टिफिकेट फ़ाइल अटैच नहीं कर सकते। Traefik लेबल रूटिंग को नियंत्रित करते हैं और TLS को सक्षम करते हैं, लेकिन सर्टिफिकेट खुद file provider से dynamic configuration के रूप में आना चाहिए। पहली बार यह बात लगभग हर किसी को उलझा देती है। हम इसे सही तरीके से करेंगे।

अगर आपके पास अभी तक कोई सर्टिफिकेट नहीं है, तो 5 मिनट में मुफ़्त में एक पाएँ।

इसका इस्तेमाल कब करें (बनाम Traefik का अपने-आप होने वाला ACME)

अगर अपने-आप होने वाला ACME आपके मामले में फ़िट बैठता है, तो Traefik का certificatesResolvers ज़्यादा आसान है। यह गाइड उस मामले के लिए है जहाँ “मेरे पास पहले से fullchain.pem + privkey.pem है और मुझे Traefik से उन्हें सर्व कराना है।“

आवश्यकताएँ

• Traefik v3 एक Docker कंटेनर के रूप में चल रहा हो (नीचे का कॉन्फ़िग Docker का इस्तेमाल करता है, लेकिन dynamic-config वाला हिस्सा किसी भी सेटअप पर लागू होता है)
• आपकी सर्टिफिकेट फ़ाइलें — इनमें से दो:
  • fullchain.pem — आपका सर्टिफिकेट + इंटरमीडिएट चेन
  • privkey.pem — आपकी निजी कुंजी
• एक डोमेन जो होस्ट की ओर इशारा करता हो (या आंतरिक उपयोग के लिए एक लोकल hosts-file एंट्री)

Traefik को किन फ़ाइलों की ज़रूरत है? Traefik को certFile में पूरी चेन और keyFile में कुंजी चाहिए। अगर आप केवल लीफ़ वाली cert.pem इस्तेमाल करते हैं, तो क्लाइंट को “incomplete chain” एरर मिलते हैं — Traefik file-provider सर्टिफ़िकेट्स के लिए इंटरमीडिएट अपने-आप नहीं जोड़ता। fullchain.pem इस्तेमाल करें। सर्टिफिकेट फ़ॉर्मैट समझाए गए →

Traefik का कॉन्फ़िग कैसे बँटा होता है

Traefik में दो तरह की configuration होती है, और सर्टिफिकेट दूसरी वाली में रहते हैं:

• Static configuration — स्टार्टअप पर सेट होती है (entrypoints, providers)। इसे बदलने के लिए रीस्टार्ट की ज़रूरत होती है। यह traefik.yml में या कंटेनर कमांड फ़्लैग में जाती है।
• Dynamic configuration — बिना रीस्टार्ट के लाइव रीलोड होती है (routers, services, TLS सर्टिफिकेट)। यही वह चीज़ है जिसे file provider पढ़ता है।

आपका सर्टिफिकेट dynamic कॉन्फ़िग है। इसीलिए कोई लेबल इसे नहीं ले जा सकता — लेबल Docker provider से पढ़े जाते हैं, लेकिन tls.certificates एक file-provider की अवधारणा है।

चरण 1: सर्टिफिकेट फ़ाइलें रखें

फ़ाइलों को एक ऐसी डायरेक्टरी में रखें जिसे आप कंटेनर में माउंट करेंगे:

mkdir -p ./traefik/certs
cp fullchain.pem ./traefik/certs/
cp privkey.pem   ./traefik/certs/

# निजी कुंजी को सुरक्षित करें
chmod 600 ./traefik/certs/privkey.pem
chmod 644 ./traefik/certs/fullchain.pem

चरण 2: dynamic configuration लिखें

./traefik/dynamic/certs.yml बनाएँ। यहीं आप अपने सर्टिफिकेट की घोषणा करते हैं:

# ./traefik/dynamic/certs.yml  (dynamic configuration — file provider)
tls:
  certificates:
    - certFile: /certs/fullchain.pem
      keyFile: /certs/privkey.pem

  # वैकल्पिक: इस सर्टिफिकेट को उस किसी भी होस्ट के लिए डिफ़ॉल्ट बनाएँ जो
  # किसी ज़्यादा खास सर्टिफिकेट से मेल नहीं खाता (जैसे कोई वाइल्डकार्ड या आंतरिक CA)।
  stores:
    default:
      defaultCertificate:
        certFile: /certs/fullchain.pem
        keyFile: /certs/privkey.pem

ये पाथ (/certs/...) कंटेनर के अंदर के पाथ हैं — हम इन्हें अगले चरण में माउंट करते हैं। Traefik SNI का इस्तेमाल करके हर रिक्वेस्ट के लिए सही सर्टिफिकेट चुनता है, सर्टिफिकेट के SAN को अनुरोधित होस्टनेम से मिलाकर। जब और कुछ मेल नहीं खाता, तब defaultCertificate फ़ॉलबैक होता है।

चरण 3: Traefik को कॉन्फ़िगर करें (static config + माउंट)

यहाँ एक पूरा docker-compose.yml है। entrypoints और file provider static कॉन्फ़िग हैं (कमांड फ़्लैग के रूप में पास किए गए); सर्टिफिकेट उसी dynamic फ़ाइल से लोड होता है जो आपने अभी लिखी।

services:
  traefik:
    image: traefik:v3.3
    container_name: traefik
    restart: unless-stopped
    command:
      # ─── Entrypoints ───────────────────────────────
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      # सभी HTTP → HTTPS को entrypoint स्तर पर रीडायरेक्ट करें
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      # ─── Providers ─────────────────────────────────
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      # File provider dynamic config डायरेक्टरी को वॉच करता है
      - "--providers.file.directory=/dynamic"
      - "--providers.file.watch=true"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "./traefik/certs:/certs:ro"
      - "./traefik/dynamic:/dynamic:ro"

  # ─── उदाहरण बैकएंड सेवा ──────────────────────
  whoami:
    image: traefik/whoami
    container_name: whoami
    labels:
      - "traefik.enable=true"
      # Router: होस्ट से मेल कराएँ, HTTPS entrypoint पर सर्व करें
      - "traefik.http.routers.whoami.rule=Host(`example.com`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      # इस router पर TLS सक्षम करें — सर्टिफिकेट
      # dynamic config से आता है, किसी लेबल से नहीं।
      - "traefik.http.routers.whoami.tls=true"

सबसे अहम लाइन है traefik.http.routers.whoami.tls=true। यह Traefik को बताती है कि “इस router को TLS पर सर्व करो।” इसके बाद Traefik file-provider स्टोर से SNI के ज़रिए मेल खाने वाला सर्टिफिकेट चुन लेता है। tls.certfile जैसा कोई लेबल नहीं है — routers के लिए यह मौजूद ही नहीं है।

चरण 4: शुरू करें और सत्यापित करें

docker compose up -d
docker compose logs -f traefik

देखें कि file provider आपका सर्टिफिकेट लोड कर रहा है। आपको TLS एरर नहीं दिखने चाहिए। फिर सत्यापित करें:

ब्राउज़र जाँच

https://example.com पर जाएँ। ताले (padlock) पर क्लिक करें:

• किसके द्वारा जारी — आपका CA (GetHTTPS के लिए Let’s Encrypt, या आपका आंतरिक CA)
• वैध — शुरू और समाप्ति की तारीख़ें
• डोमेन — URL से मेल खाता है

कमांड-लाइन जाँच

# पुष्टि करें कि Traefik आपका सर्टिफिकेट सर्व कर रहा है, न कि अपना सेल्फ़-साइन्ड डिफ़ॉल्ट
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

अगर आपको CN=TRAEFIK DEFAULT CERT दिखता है, तो Traefik अपने बिल्ट-इन प्लेसहोल्डर पर वापस चला गया — आपका सर्टिफिकेट लोड नहीं हुआ था। नीचे समस्या-निवारण सेक्शन देखें।

चरण 5 (वैकल्पिक): TLS को मज़बूत करें

प्रोटोकॉल संस्करणों और साइफ़र्स को नियंत्रित करने के लिए, अपने dynamic config में एक TLS options ब्लॉक जोड़ें और router से उसका संदर्भ दें। certs.yml में जोड़ें:

tls:
  options:
    modern:
      minVersion: VersionTLS12
      sniStrict: true

फिर router लेबल पर:

- "traefik.http.routers.whoami.tls.options=modern@file"

@file सफ़िक्स Traefik को बताता है कि यह option सेट file provider से आता है। यह आपको TLS 1.2 और 1.3 तक सीमित करता है और बिना मेल खाने वाले SNI के कनेक्शन को अस्वीकार कर देता है।

HSTS: एक बार जब आप आश्वस्त हो जाएँ कि HTTPS हर जगह काम कर रहा है, तो Traefik headers मिडलवेयर के ज़रिए Strict-Transport-Security हेडर जोड़ें। HSTS गाइड →

नवीनीकरण कैसे करें

आपके खुद के दिए गए सर्टिफिकेट को Traefik अपने-आप नवीनीकृत नहीं करता — अपना सर्टिफिकेट लाने का यही बदला है। जब आपका सर्टिफिकेट समाप्ति के पास पहुँचे (Let’s Encrypt के लिए 90 में से दिन 60):

1. GetHTTPS (या अपने नवीनीकरण टूल) से एक नया सर्टिफिकेट पाएँ।
2. फ़ाइलों को उसी जगह पर ओवरराइट करें:

   cp new-fullchain.pem ./traefik/certs/fullchain.pem
   cp new-privkey.pem   ./traefik/certs/privkey.pem

3. और कुछ नहीं। चूँकि --providers.file.watch=true सेट है, Traefik फ़ाइल में बदलाव का पता लगा लेता है और सर्टिफिकेट को हॉट-रीलोड कर देता है — कोई रीस्टार्ट नहीं, कोई डाउनटाइम नहीं। कस्टम सर्टिफ़िकेट्स के लिए यह Traefik की सबसे बेहतरीन ख़ूबियों में से एक है।

पूरी नवीनीकरण गाइड →

समस्या-निवारण

Traefik मेरे सर्टिफिकेट की जगह “TRAEFIK DEFAULT CERT” सर्व करता है

कारण: Traefik आपका सर्टिफिकेट लोड नहीं कर पाया, इसलिए वह अपने सेल्फ़-साइन्ड प्लेसहोल्डर पर वापस चला गया। लगभग हमेशा यह पाथ या माउंट की समस्या होती है।

समाधान:

# 1. पुष्टि करें कि फ़ाइलें कंटेनर के अंदर अपेक्षित पाथ पर मौजूद हैं
docker compose exec traefik ls -l /certs

# 2. पुष्टि करें कि dynamic फ़ाइल माउंटेड और पठनीय है
docker compose exec traefik cat /dynamic/certs.yml

# 3. असली वजह के लिए लॉग जाँचें
docker compose logs traefik | grep -i "certificate\|tls\|error"

certs.yml में certFile/keyFile के पाथ कंटेनर के पाथ (/certs/...) से मेल खाने चाहिए, न कि आपके होस्ट के पाथ से।

“unable to find certificate for domain” / गलत सर्टिफिकेट सर्व हुआ

कारण: किसी भी सर्टिफिकेट का SAN अनुरोधित होस्टनेम से मेल नहीं खाता, और कोई defaultCertificate सेट नहीं है।

समाधान: या तो अपने सर्टिफिकेट में होस्टनेम जोड़ें, या stores.default ब्लॉक (चरण 2) में एक defaultCertificate सेट करें ताकि Traefik के पास एक फ़ॉलबैक हो।

Router 404 लौटाता है, सर्टिफिकेट कभी जाँचा ही नहीं गया

कारण: router का नियम मेल नहीं खाता, या सेवा एक्सपोज़ नहीं है। जब तक रूटिंग मेल नहीं खाती, TLS अप्रासंगिक है।

समाधान:

# सत्यापित करें कि router मौजूद है और सक्षम है
docker compose exec traefik wget -qO- http://localhost:8080/api/http/routers 2>/dev/null | grep whoami

सुनिश्चित करें कि बैकएंड कंटेनर पर traefik.enable=true है और Host() नियम उस डोमेन से मेल खाता है जिसे आप टेस्ट कर रहे हैं।

certs.yml में बदलाव प्रभावी नहीं होते

कारण: file provider वॉच नहीं कर रहा, या आपने static config संपादित की (जिसके लिए रीस्टार्ट चाहिए)।

समाधान: पुष्टि करें कि --providers.file.watch=true static config में है। याद रखें: entrypoints/providers static हैं (रीस्टार्ट ज़रूरी); routers और tls.certificates dynamic हैं (हॉट-रीलोडेड)।

क्लाइंट से “x509: certificate signed by unknown authority”

कारण: अधूरी चेन — आपने certFile में fullchain.pem की जगह केवल लीफ़ वाली cert.pem इस्तेमाल की।

समाधान: certFile को पूरी चेन की ओर इंगित करें। अगर आपके पास केवल अलग-अलग फ़ाइलें हैं, तो उन्हें जोड़ें (पहले लीफ़, फिर इंटरमीडिएट):

cat cert.pem intermediate.pem > fullchain.pem

अक्सर पूछे जाने वाले प्रश्न

क्या मैं Docker लेबल से सर्टिफिकेट फ़ाइल निर्दिष्ट कर सकता हूँ?

नहीं। यह सबसे बड़ी ग़लतफ़हमी है। लेबल TLS को सक्षम करने के लिए traefik.http.routers.<name>.tls=true सेट करते हैं, लेकिन सर्टिफिकेट फ़ाइलों की घोषणा file provider के ज़रिए dynamic configuration में होनी चाहिए (tls.certificates)। कोई router लेबल नहीं है जो किसी .pem फ़ाइल की ओर इशारा करे।

अगर मेरे पास सर्टिफिकेट है तो क्या मुझे router पर tls=true चाहिए?

हाँ। tls.certificates में सर्टिफिकेट की घोषणा उसे उपलब्ध बनाती है, लेकिन वास्तव में HTTPS पर सर्व करने के लिए हर router को अब भी tls=true चाहिए (या TLS-सक्षम entrypoint पर सुनना चाहिए)। केवल सर्टिफिकेट परिभाषित करने से कोई router TLS पर स्विच नहीं होता।

क्या मैं अपने-आप होने वाले ACME और कस्टम सर्टिफ़िकेट्स को मिला सकता हूँ?

हाँ। Traefik कुछ routers के लिए certificatesResolver और दूसरों के लिए file-provider सर्टिफ़िकेट्स इस्तेमाल कर सकता है। प्रति रिक्वेस्ट, SNI के ज़रिए एक स्पष्ट tls.certificates मेल उस होस्टनेम के लिए ACME पर प्राथमिकता पाता है।

Kubernetes पर सर्टिफिकेट कहाँ जाते हैं?

file provider में नहीं — Kubernetes पर आप सर्टिफ़िकेट्स को TLS Secrets के रूप में देते हैं और IngressRoute/Ingress से उनका संदर्भ देते हैं। इस गाइड का file-provider तरीका Docker और स्टैंडअलोन (नॉन-K8s) सेटअप के लिए है।

क्या Traefik मेरे कस्टम सर्टिफिकेट को अपने-आप नवीनीकृत करता है?

नहीं। अपने-आप नवीनीकरण केवल उन सर्टिफ़िकेट्स पर लागू होता है जिन्हें Traefik स्वयं ACME के ज़रिए जारी करता है। अपने खुद के सर्टिफ़िकेट्स के लिए, आप फ़ाइलों को बदलते हैं — लेकिन --providers.file.watch=true की बदौलत, Traefik उन्हें शून्य डाउनटाइम के साथ हॉट-रीलोड कर देता है, जैसा ऊपर नवीनीकरण कैसे करें सेक्शन में बताया गया है।

क्या यह ECDSA/ECC सर्टिफ़िकेट्स के साथ काम करता है?

हाँ। Traefik ECDSA सर्टिफ़िकेट्स को बिल्कुल RSA की तरह सर्व करता है — वही certFile/keyFile कॉन्फ़िग। GetHTTPS छोटे, तेज़ हैंडशेक के लिए डिफ़ॉल्ट रूप से ECDSA P-256 जारी करता है।