From a52cf3f70b949562bf3c17ac3f2a3cb600a3cd2f Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Tue, 17 Oct 2023 13:52:39 +0200 Subject: [PATCH] fix bugs in diagrams & improve titles Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- content/docs/usage/certificate.md | 2 +- content/docs/usage/certificaterequest.md | 2 +- content/docs/usage/gateway.md | 2 +- content/docs/usage/ingress.md | 2 +- content/docs/usage/kube-csr.md | 2 +- .../certificate-flow.drawio | 149 +++++++++--------- .../certificate-flow.svg | 2 +- .../gateway-shim-flow.drawio | 34 ++-- .../gateway-shim-flow.svg | 2 +- .../ingress-shim-flow.drawio | 10 +- .../ingress-shim-flow.svg | 2 +- 11 files changed, 105 insertions(+), 104 deletions(-) diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index af6b9311d54..3882fba3c36 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -374,7 +374,7 @@ data: ... ``` -## Inner workings diagram +## Inner workings diagram for developers diff --git a/content/docs/usage/certificaterequest.md b/content/docs/usage/certificaterequest.md index 1a00b112f25..2c43845d1e4 100644 --- a/content/docs/usage/certificaterequest.md +++ b/content/docs/usage/certificaterequest.md @@ -263,6 +263,6 @@ and `bar`: resourceNames: ["myissuers.my-example.io/foo.myapp", "myissuers.my-example.io/bar.myapp"] ``` -## Inner workings diagram +## Inner workings diagram for developers diff --git a/content/docs/usage/gateway.md b/content/docs/usage/gateway.md index cc6a093b927..905344a66ed 100644 --- a/content/docs/usage/gateway.md +++ b/content/docs/usage/gateway.md @@ -440,7 +440,7 @@ Certificate resources: 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. -## Inner workings diagram +## Inner workings diagram for developers diff --git a/content/docs/usage/ingress.md b/content/docs/usage/ingress.md index 7bcd98632cc..b002c62841c 100644 --- a/content/docs/usage/ingress.md +++ b/content/docs/usage/ingress.md @@ -217,7 +217,7 @@ guide](../installation/README.md). 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. -## Inner workings diagram +## Inner workings diagram for developers diff --git a/content/docs/usage/kube-csr.md b/content/docs/usage/kube-csr.md index 2cee76f9cbc..ac1646db8b4 100644 --- a/content/docs/usage/kube-csr.md +++ b/content/docs/usage/kube-csr.md @@ -168,6 +168,6 @@ are not approved by default, so you will likely need to approve it manually: $ kubectl certificate approve ``` -## Inner workings diagram +## Inner workings diagram for developers diff --git a/public/images/request-certificate-debug/certificate-flow.drawio b/public/images/request-certificate-debug/certificate-flow.drawio index aae0008481f..3f77bca5854 100644 --- a/public/images/request-certificate-debug/certificate-flow.drawio +++ b/public/images/request-certificate-debug/certificate-flow.drawio @@ -1,9 +1,24 @@ - + - + + + + + + + + + + + + + + + + @@ -96,7 +111,7 @@ - + @@ -109,13 +124,13 @@ - - + + - - + + - + @@ -129,8 +144,8 @@ - - + + @@ -138,102 +153,79 @@ - - - - - + + - - + + - + - + - + - + - - - + + + - - + + - - - - - - - - - - + - - - - - - - - + + - + - - - - + - - + + - - - - + - - + + - - - + + + + - - + + - - + + @@ -241,17 +233,11 @@ - - - - - - - - + + - + @@ -275,10 +261,25 @@ - + + + + + + + + + + + + + + + + diff --git a/public/images/request-certificate-debug/certificate-flow.svg b/public/images/request-certificate-debug/certificate-flow.svg index 11bc5717ec7..0c675475a28 100644 --- a/public/images/request-certificate-debug/certificate-flow.svg +++ b/public/images/request-certificate-debug/certificate-flow.svg @@ -1,3 +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 +
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...
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.1) requestmanager creates CertificateRequest
      with revision = "1" (the next revision)
(a.1) requestmanager creates CertificateRequest...
(a.2) requestmanager signs the CSR
      using the private key
(a.2) requestmanager signs the CSR...
(a.1)
(a.1)
(a.2)
(a.2)
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: sec-1
status:
  nextPrivateKeySecret: sec-1-01ab4f
  revision: 1
  conditions:
    - type: Issuing
      status: "False"
      reason: Issued
kind: Certificate...
(c) issuing
    controller
    sets
    revision = 1
    and
    Issuing = False
(c) 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
REMOVED AFTER USE
REMOVED AFTER U...
kind: Certificate
spec:
  issuerRef: issuer-1
  secretName: sec-1
status:
  revision: 1
  conditions:
    - type: Ready
      status: "True"
      reason: Issued
    - type: Issuing
      status: "False"
      reason: Issued
kind: Certificate...
(b.3) issuing controller
      copies tls.key
      from temporary
      private key
(b.3) issuing controller...
ready controller
sets readiness
ready controller...
DOES NOT EXIST YET
DOES NOT EXI...
ISSUER
ISSUER
CertificateRequest
Flow [1]
CertificateRequest...
(b.1) issuing controller
      creates or updates sec-1
(b.1) issuing controller...
(b.2) issuing controller
      sets tls.crt
      and ca.crt(if returned by CA)
(b.2) issuing controller...Text is not SVG - cannot display \ No newline at end of file diff --git a/public/images/request-certificate-debug/gateway-shim-flow.drawio b/public/images/request-certificate-debug/gateway-shim-flow.drawio index 51908f0f2bf..7afa227611e 100644 --- a/public/images/request-certificate-debug/gateway-shim-flow.drawio +++ b/public/images/request-certificate-debug/gateway-shim-flow.drawio @@ -1,6 +1,6 @@ - + - + @@ -8,7 +8,7 @@ - + @@ -20,26 +20,26 @@ - + - + - + - - + + - - + + - + @@ -51,10 +51,10 @@ - + - - + + @@ -66,8 +66,8 @@ - - + + @@ -97,7 +97,7 @@ - + diff --git a/public/images/request-certificate-debug/gateway-shim-flow.svg b/public/images/request-certificate-debug/gateway-shim-flow.svg index e08d309947e..cb9aba8d42f 100644 --- a/public/images/request-certificate-debug/gateway-shim-flow.svg +++ b/public/images/request-certificate-debug/gateway-shim-flow.svg @@ -1,3 +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 +
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:
          - kind: Secret
            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: "False"
      reason: Issued
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-debug/ingress-shim-flow.drawio b/public/images/request-certificate-debug/ingress-shim-flow.drawio index 06213da87e3..dc9bbb3bf3b 100644 --- a/public/images/request-certificate-debug/ingress-shim-flow.drawio +++ b/public/images/request-certificate-debug/ingress-shim-flow.drawio @@ -1,6 +1,6 @@ - + - + @@ -73,8 +73,8 @@ - - + + @@ -94,7 +94,7 @@ - + diff --git a/public/images/request-certificate-debug/ingress-shim-flow.svg b/public/images/request-certificate-debug/ingress-shim-flow.svg index 3540a4809d2..a32812ad01b 100644 --- a/public/images/request-certificate-debug/ingress-shim-flow.svg +++ b/public/images/request-certificate-debug/ingress-shim-flow.svg @@ -1,3 +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 +
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: "False"
      reason: Issued
kind: Certificate...
Certificate Flow [1]
Certificate Flow [1]Text is not SVG - cannot display \ No newline at end of file