diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index ca29de1e474..be365816ae7 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -370,3 +370,9 @@ data: key.der: ... ``` + +## Understanding the internal workings and debugging + + + +[1] https://cert-manager.io/docs/usage/certificaterequest diff --git a/content/docs/usage/certificaterequest.md b/content/docs/usage/certificaterequest.md index 8d39d914997..f68012f0266 100644 --- a/content/docs/usage/certificaterequest.md +++ b/content/docs/usage/certificaterequest.md @@ -258,4 +258,8 @@ and `bar`: ```yaml resourceNames: ["myissuers.my-example.io/foo.myapp", "myissuers.my-example.io/bar.myapp"] -``` \ No newline at end of file +``` + +## Understanding the internal workings and debugging + + diff --git a/content/docs/usage/gateway.md b/content/docs/usage/gateway.md index ae852ef6b72..384f0dbd90c 100644 --- a/content/docs/usage/gateway.md +++ b/content/docs/usage/gateway.md @@ -436,3 +436,9 @@ Certificate resources: - `cert-manager.io/private-key-rotation-policy`: (optional) this annotation allows you to configure `spec.privateKey.rotationPolicy` field to set the rotation policy of the private key for a Certificate. Valid values are `Never` and `Always`. If unset a rotation policy `Never` will be used. + +## Understanding the internal workings and debugging + + + +[1] https://cert-manager.io/docs/usage/certificate diff --git a/content/docs/usage/ingress.md b/content/docs/usage/ingress.md index af82abbd0aa..9e28c829582 100644 --- a/content/docs/usage/ingress.md +++ b/content/docs/usage/ingress.md @@ -213,3 +213,9 @@ guide](../installation/README.md). ## Troubleshooting If you do not see a `Certificate` resource being created after applying the ingress-shim annotations check that at least `cert-manager.io/issuer` or `cert-manager.io/cluster-issuer` is set. If you want to use `kubernetes.io/tls-acme: "true"` make sure to have checked all steps above and you might want to look for errors in the cert-manager pod logs if not resolved. + +## Understanding the internal workings and debugging + + + +[1] https://cert-manager.io/docs/usage/certificate diff --git a/public/images/request-certificate-flow/certificate-flow.drawio b/public/images/request-certificate-flow/certificate-flow.drawio new file mode 100644 index 00000000000..aae0008481f --- /dev/null +++ b/public/images/request-certificate-flow/certificate-flow.drawio @@ -0,0 +1,285 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/public/images/request-certificate-flow/certificate-flow.svg b/public/images/request-certificate-flow/certificate-flow.svg new file mode 100644 index 00000000000..11bc5717ec7 --- /dev/null +++ b/public/images/request-certificate-flow/certificate-flow.svg @@ -0,0 +1,3 @@ + + +
kind: CertificateRequest
metadata:
  name: cert-1-ab0123
  annotations:
    cert-manager.io/certificate-revision: "1"
spec:
  issuerRef: issuer-1
  request: |
    -----BEGIN CERTIFICATE REQUEST-----
    ...
    -----END CERTIFICATE REQUEST-----

kind: CertificateRequest...
kind: Issuer
metadata:
  name: issuer-1
spec: ...
kind: Issuer...
user creates the Certificate "cert-1"
user creates the Certificate "cert-1"
triggercontroller marks for reissuance
triggercontroller marks f...
kind: Certificate
metadata:
  name: cert-1
spec:
  dnsNames:
    - example.com
    - foo.example.com
  issuerRef: issuer-1
  secretName: sec-1
kind: Certificate...
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: sec-1
status:
  conditions:
  - type: Issuing
    status: "True"
    reason: Pending
kind: Certificate...
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: sec-1
status:
  nextPrivateKeySecret: sec-1-01ab4f
  conditions:
  - type: Issuing
    status: "True"
    reason: Pending
kind: Certificate...
keymanager creates a temporary private key
keymanager creates a tempora...
kind: Secret
metadata:
  name: sec-1-01ab4f
stringData:
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    AaBbCcDd0
    -----END PRIVATE KEY-----

kind: Secret...
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: sec-1
status:
  nextPrivateKeySecret: sec-1-01ab4f
  revision: nil
  conditions:
  - type: Issuing
    status: "True"
    reason: Pending
kind: Certificate...
(a) requestmanager creates CertificateRequest
    with revision = "1" (the next revision)
(a) requestmanager creates CertificateRequest...
(b) requestmanager signs the CSR      using the private key
(b) requestmanager signs the CSR      usi...
(a)
(a)
(b)
(b)
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: sec-1
status:
  nextPrivateKeySecret: sec-1-01ab4f
  revision: 1
  conditions:
    - type: Issuing
      status: "True"
      reason: Pending
  certificate: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----
kind: Certificate...
(b) issuing
    controller              bubbles up the          certificate
(b) issuing...
(a) issuing
    controller
    sets
    revision = 1
(a) issuing...
TEMPORARY SECRET
TEMPORARY SECRET
kind: Secret
metadata:
  name: sec-1-01ab4f
stringData:
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    AaBbCcDd0
    -----END PRIVATE KEY-----

kind: Secret...
kind: Secret
metadata:
  name: sec-1
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----
  ca.crt: ""
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    AaBbCcDd0
    -----END PRIVATE KEY-----
kind: Secret...
TEMPORARY SECRET
TEMPORARY SECRET
kind: CertificateRequest
metadata:
  name: cert-1-ab0123
  annotations:
    cert-manager.io/certificate-revision: "1"
status:
  conditions:
    - type: Ready
      status: "True"
      reason: Issued
  certificate: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----

kind: CertificateRequest...
STAYS FOREVER
(by default)
STAYS FOREVER...
(d) issuing controller
    sets tls.crt
    and ca.crt(if returned by CA)
(d) issuing controller...
REMOVED AFTER USE
REMOVED AFTER U...
(c) issuing
    controller
    creates sec-1
(c) issuing...
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: sec-1
status:
  revision: 1
  conditions:
    - type: Ready
      status: "True"
      reason: Issued
    - type: Issuing
      status: "True"
      reason: Pending
  certificate: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----
kind: Certificate...
(e) issuing controller
    copies tls.key
    from temporary
    private key
(e) issuing controller...
ready controller
sets readiness
ready controller...
DOES NOT EXIST YET
DOES NOT EXI...
ISSUER
ISSUER
CertificateRequest
Flow [1]
CertificateRequest...Text is not SVG - cannot display \ No newline at end of file diff --git a/public/images/request-certificate-flow/certificate-request-flow.drawio b/public/images/request-certificate-flow/certificate-request-flow.drawio new file mode 100644 index 00000000000..06e17205a11 --- /dev/null +++ b/public/images/request-certificate-flow/certificate-request-flow.drawio @@ -0,0 +1,68 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/public/images/request-certificate-flow/certificate-request-flow.svg b/public/images/request-certificate-flow/certificate-request-flow.svg new file mode 100644 index 00000000000..912ce1cc3f4 --- /dev/null +++ b/public/images/request-certificate-flow/certificate-request-flow.svg @@ -0,0 +1,3 @@ + + +
kind: CertificateRequest
metadata:
  name: cert-1-ab0123
spec:
  issuerRef: issuer-1
  request: |
    -----BEGIN CERTIFICATE REQUEST-----
    ...
    -----END CERTIFICATE REQUEST-----

kind: CertificateRequest...
a controller generates a CertificateRequest
a controller generates a Certi...
ISSUER IMPLEMENTATION
ISSUER IMPLEMENTATION
kind: CertificateRequest
metadata:
  name: cert-1-ab0123
status:
  conditions:
    - type: Approved
      status: "True"
      reason: policy.cert-manager.io
    - type: Ready
      status: "True"
      reason: Issued
  certificate: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----

kind: CertificateRequest...
Validate CertificateRequest
Validate CertificateRequest
kind: CertificateRequest
metadata:
  name: cert-1-ab0123
status:
  conditions:
    - type: Approved
      status: "True"
      reason: policy.cert-manager.io
kind: CertificateRequest...
a cert-manager approver approves the CertificateRequest
a cert-manager approver approves the C...
Generate a Certificate using the CertificateRequest as input

⚠️the public key is the only certificate attribute that is guaranteed to match the request
Generate a Certificate using the CertificateRequest as inpu...
Sign Certificate
Sign CertificateText is not SVG - cannot display \ No newline at end of file diff --git a/public/images/request-certificate-flow/gateway-shim-flow.drawio b/public/images/request-certificate-flow/gateway-shim-flow.drawio new file mode 100644 index 00000000000..51908f0f2bf --- /dev/null +++ b/public/images/request-certificate-flow/gateway-shim-flow.drawio @@ -0,0 +1,107 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/public/images/request-certificate-flow/gateway-shim-flow.svg b/public/images/request-certificate-flow/gateway-shim-flow.svg new file mode 100644 index 00000000000..e08d309947e --- /dev/null +++ b/public/images/request-certificate-flow/gateway-shim-flow.svg @@ -0,0 +1,3 @@ + + +
kind: Issuer
metadata:
  name: issuer-1
spec: ...
kind: Issuer...
gateway-shim creates the Certificate "cert-1"
gateway-shim creates the Certificat...
kind: Certificate
metadata:
  name: cert-1
spec:
  dnsNames:
    - example.com
  issuerRef: issuer-1
  secretName: cert-1
kind: Certificate...
DOES NOT EXIST YET
DOES NOT EXI...
CERT-MANAGER ISSUER
CERT-MANAGER ISSUER
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
  name: gateway-1
  annotations:
    cert-manager.io/issuer: issuer-1
spec:
  listeners:
    - hostname: example.com
      tls:
        mode: Terminate
        certificateRefs:
          - name: cert-1
apiVersion: gateway.networking.k8s.io/v1alpha2kind: Gate...
user creates a Gateway "gateway-1" with cert-manager annotations
user creates a Gateway "gateway-...
kind: Secret
metadata:
  name: cert-1
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    AaBbCcDd0
    -----END PRIVATE KEY-----
kind: Secret...
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: cert-1
status:
  revision: 1
  conditions:
    - type: Ready
      status: "True"
      reason: Issued
    - type: Issuing
      status: "True"
      reason: Pending
  certificate: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----
kind: Certificate...
Certificate Flow [1]
Certificate Flow [1]Text is not SVG - cannot display \ No newline at end of file diff --git a/public/images/request-certificate-flow/ingress-shim-flow.drawio b/public/images/request-certificate-flow/ingress-shim-flow.drawio new file mode 100644 index 00000000000..06213da87e3 --- /dev/null +++ b/public/images/request-certificate-flow/ingress-shim-flow.drawio @@ -0,0 +1,104 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/public/images/request-certificate-flow/ingress-shim-flow.svg b/public/images/request-certificate-flow/ingress-shim-flow.svg new file mode 100644 index 00000000000..3540a4809d2 --- /dev/null +++ b/public/images/request-certificate-flow/ingress-shim-flow.svg @@ -0,0 +1,3 @@ + + +
kind: Issuer
metadata:
  name: issuer-1
spec: ...
kind: Issuer...
ingress-shim creates the Certificate "cert-1"
ingress-shim creates the Certificat...
kind: Certificate
metadata:
  name: cert-1
spec:
  dnsNames:
    - example.com
    - foo.example.com
  issuerRef: issuer-1
  secretName: cert-1
kind: Certificate...
DOES NOT EXIST YET
DOES NOT EXI...
CERT-MANAGER ISSUER
CERT-MANAGER ISSUER
kind: Ingress
metadata:
  name: ingress-1
  annotations:
    cert-manager.io/issuer: issuer-1
tls:
  - hosts:
    - example.com
    - foo.example.com
    secretName: cert-1
kind: Ingress...
user creates an Ingress "ingress-1" with cert-manager annotations
user creates an Ingress "ingress...
kind: Secret
metadata:
  name: cert-1
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    AaBbCcDd0
    -----END PRIVATE KEY-----
kind: Secret...
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: cert-1
status:
  revision: 1
  conditions:
    - type: Ready
      status: "True"
      reason: Issued
    - type: Issuing
      status: "True"
      reason: Pending
  certificate: |
    -----BEGIN CERTIFICATE-----
    (leaf)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    (intermediate)
    -----END CERTIFICATE-----
kind: Certificate...
Certificate Flow [1]
Certificate Flow [1]Text is not SVG - cannot display \ No newline at end of file