# [Installing cert-manager](https://cert-manager.io/docs/installation/helm/#installing-cert-manager)

> [!Tip]
> 專為 Kubernetes 設計的自動化證書管理工具。它能夠在 Kubernetes 集群中自動申請、簽發、續期和管理 TLS/SSL 證書，支援多種證書來源，如 Let's Encrypt（支援 ACME 協議）、HashiCorp Vault、Venafi 及自簽證書等。
> 核心功能包括：
> - 自動處理證書的申請與續期，避免因證書過期導致服務中斷。
> - 證書和私鑰會被存儲在 Kubernetes Secret 中，方便應用及 Ingress 控制器使用。
> - 通過 Kubernetes 的自定義資源 (CRDs) 定義簽發者（Issuer）和證書（Certificate），實現 Kubernetes 原生的證書管理。
> - 支援多種證書簽發方式和頒發機構，適用於內外網多種場景。
> 總的來說，cert-manager 是 Kubernetes 環境中管理 TLS 證書的首選工具，能大幅提升 Kubernetes 集群中應用的安全性與管理效率。

## 使用 Helm install 指令安裝 cert-manager

helm install \
  cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --version v1.18.2 \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

## uninstall

helm uninstall cert-manager -n cert-manager

---

# Issuer 與 ClusterIssuer 比較說明

`Issuer` 和 `ClusterIssuer` 都是用來定義 Kubernetes 中憑證簽發者（CA, Certificate Authority）的自訂資源（Custom Resource），兩者主要差異在於作用範圍不同：

| 項目 | Issuer | ClusterIssuer |
|--------------|--------------------------------|-------------------------------|
| **作用範圍** | 限定在單一命名空間 (Namespace) | 整個 Kubernetes 集群 (Cluster-wide) |
| **使用範圍** | 該命名空間內的資源 | 所有命名空間中的資源 |
| **設定管理** | 必須在特定命名空間中設定和管理 | 不需命名空間屬性，集群層級管理 |
| **使用情境** | 限制某個命名空間使用 | 希望所有命名空間共用同一簽發機制 |

---

## Issuer 與 ClusterIssuer

- **Issuer**
命名空間等級的簽發者設定，僅在特定命名空間內生效與管理。

- **ClusterIssuer**
整個集群等級的簽發者設定，作用範圍涵蓋所有命名空間，適合統一管理及共用簽發機制。

---

## 選擇建議

- 若只想限制某個命名空間內使用憑證簽發者，則選擇 **Issuer**
- 想讓整個集群中的應用都能共用同一組簽發者設定時，建議使用 **ClusterIssuer**

---

# [http validation](https://cert-manager.io/docs/tutorials/acme/http-validation/)

> [!Tip]
> 使用 Let's Encrypt 為 Ingress 建立 SSL 憑證，該 CA 不支援簽發給私有 domain（例如內網專用域名或非公開域名）的憑證，因為 Let's Encrypt 需要驗證域名的公網可訪問性（HTTP-01 或 DNS-01 驗證）。所以私有 domain 在無法公開驗證的情境下，無法使用 Let's Encrypt 簽署憑證

> [!Note]
> 需要註冊網域、DNS設定(公有雲DNS、CloudFlare)、k8s 完成網站部署

## 建立 ClusterIssuer

> [!Important]
> 為了頒發任何證書，需要配置 Issuer 或 ClusterIssuer

> [!Note]
> [證書請求速率限制](https://letsencrypt.org/docs/rate-limits/) 先使用 staging 測試，應用程式部署正式環境，再使用 production

### staging

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    # The ACME server URL
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: [e-mail] # 替換成自己的電子郵件
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-staging-private-key
    # Enable the HTTP-01 challenge provider
    solvers:
    - http01:
        ingress:
          ingressClassName: nginx

### production

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-production
spec:
  acme:
    # The ACME server URL
    server: https://acme-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: [e-mail] # 替換成自己的電子郵件
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-production-private-key
    # Enable the HTTP-01 challenge provider
    solvers:
    - http01:
        ingress:
          ingressClassName: nginx

---

## 申請憑證 certificate (擇一)

> [!Tip]
> [證書資源](https://cert-manager.io/docs/usage/certificate/) 指定用來產生憑證簽署請求（CSR）的欄位，接著由你所參考的簽發者類型來完成簽發。Certificate 透過指定 certificate.spec.issuerRef 欄位，來決定要向哪個簽發者申請憑證。

**cert-manager Certificate 與 Ingress TLS 配置說明**

cert-manager 的 **Certificate** 資源和 Let’s Encrypt 配合，透過 ACME 協議，獨立管理 TLS 憑證，而 Ingress 只是透過已存在的 Secret 來使用該憑證。

**這種方式能做到什麼？**

- 將憑證申請（Certificate）獨立於 Ingress 配置管理，不直接在 Ingress 上申請憑證。
- 由 cert-manager 使用 ClusterIssuer 自動申請 Let’s Encrypt 憑證並存放在 Kubernetes Secret 中。
- Ingress 中的 TLS 配置再使用該 Secret，完成 HTTPS 流量加密。
- 更靈活管理憑證生命周期，憑證作為獨立資源更易於複用、管理和追蹤。

### certificate

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: staging-example-com
  namespace: app
spec:
  dnsNames:
    - staging.example.com
  secretName: staging-example-com-tls
  issuerRef:
    name: letsencrypt-staging # 正式環境改為 letsencrypt-production
    kind: ClusterIssuer

### ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: staging-example-com
  namespace: app
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - staging.example.com
      secretName: staging-example-com-tls # cert-manager 會將建立的憑證儲存在 k8s secrets
  rules:
  - host: staging.example.com
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: myservice
            port:
              number: 80

---

## Kubernetes Ingress 自動取得憑證 (擇一)

Kubernetes 環境中，可以透過 Ingress 資源與 cert-manager 的搭配，自動申請及管理 Let’s Encrypt 的 SSL/TLS 憑證。流程如下：

1. **指定 ClusterIssuer**
在 Ingress 資源中透過 annotation 指定 cert-manager 使用的 ClusterIssuer，例如：
- `letsencrypt-staging`：通常用於測試環境
- `letsencrypt-production`：正式環境會使用該名稱

2. **Cert-manager 的作用**
cert-manager 會利用 Let’s Encrypt 的 ACME 協議，自動處理憑證的申請與簽發流程。
包含：
- 自動回答網頁驗證（HTTP-01 challenge）
- 與 Let’s Encrypt 伺服器互動完成簽發作業

3. **憑證存放位置**
簽發成功後，憑證及私鑰會被存放在 Kubernetes 的 Secret 中，範例為：staging-example-com-private-key

4. **Ingress TLS 設定**
Ingress 規則中設定 TLS，指定：
- 使用的 host（例如 `staging.example.com`）
- 對應的 Secret 作為憑證來源

5. **流量與 HTTPS**
流量通過 nginx ingress controller，即會使用自動申請的 SSL/TLS 憑證，實現 HTTPS 加密連線。

6. **憑證自動續期**
cert-manager 會自動監控該憑證的有效期限，並且在快過期時觸發自動續期，降低管理與維護的負擔。

此機制，Kubernetes 可以輕鬆且安全地管理 HTTPS 憑證，避免手動配置錯誤與過期問題。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: app
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-staging" # 與 ClusterIssuer 名稱一致，正式環境可改為 letsencrypt-production
    cert-manager.io/acme-http01-edit-in-place: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - staging.example.com
      secretName: staging-example-com-tls # cert-manager 會將建立的憑證儲存在 k8s secrets
  rules:
  - host: staging.example.com
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: myservice
            port:
              number: 80

---

## 兩種方式比較

使用 Certificate 狀態明確控制 與 Ingress 直接 annotation 方式

| 項目 | 使用 Certificate 資源 | Ingress 直接 annotation 方式 |
|--------------|---------------------------------------------|-------------------------------------------|
| **憑證資源管理** | 憑證獨立於 Ingress，有 Certificate 資源，方便監控與核查。 | 沒有獨立憑證資源，依賴 cert-manager 的 Ingress Shim 自動建立憑證。 |
| **靈活性** | 較高，可複用憑證於多個 Ingress，或分離管理。 | 較依賴 Ingress 結構，憑證綁定於特定 Ingress。 |
| **配置複雜度** | 較複雜，需要同時管理 Certificate 與 Ingress。 | 配置較簡單，只需為 Ingress 加上 annotation。 |
| **啟動時機** | 憑證申請可先行，與 Ingress 生命週期可分離。 | 憑證申請依賴 Ingress，Ingress 建立後才觸發申請。 |
| **Debug 便利度** | 更易查看憑證與挑戰狀態，例如用 `kubectl describe certificate`。 | 需查看 Ingress 事件及 cert-manager 日誌，較少明確資源顯示。 |
| **適用場景** | 需求較複雜、多憑證管理，或需要提前申請憑證時。 | 簡單應用場景，僅需快速建立 HTTPS。 |

---

## 總結

- 兩種方式皆利用 cert-manager 透過 Let’s Encrypt 的 ACME HTTP-01 挑戰驗證所有權，並發放憑證。
- 使用獨立 Certificate 資源的方式提供較高的控制力與管理彈性，方便跟蹤管理憑證，適合中大型或多憑證場景。
- 在 Ingress annotation 上直接觸發申請較簡單直接，快速可用，適合簡單場景或快速部署。
- 主要差異在憑證管理粒度、生命週期分離程度，以及調試和維護的便利度。
- 這些差異決定適用情境與維護流程。兩種方式在 Kubernetes 與 cert-manager 生態中都非常常見且有用，依具體需求決定採用哪種較佳。