add diagrams to the requesting certificates pages based on Mael's e2e…

… diagram Signed-off-by: Tim Ramlot <[email protected]>
cert-manager · Sep 30, 2023 · 54fb651 · 54fb651
1 parent 5a1ca93
commit 54fb651
Show file tree

Hide file tree

Showing 15 changed files with 678 additions and 1 deletion.
diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md
@@ -370,3 +370,9 @@ data:
   key.der: <DER binary format of private key>
   ...
 ```
+
+## Understanding the internal workings and debugging
+
+<object data="/images/request-certificate-flow/certificate-flow.svg"></object>
+
+[1] https://cert-manager.io/docs/usage/certificaterequest
diff --git 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"]
-```
+```
+
+## Understanding the internal workings and debugging
+
+<object data="/images/request-certificate-flow/certificate-request-flow.svg"></object>
diff --git 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
+
+<object data="/images/request-certificate-flow/gateway-shim-flow.svg"></object>
+
+[1] https://cert-manager.io/docs/usage/certificate
diff --git 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
+
+<object data="/images/request-certificate-flow/ingress-shim-flow.svg"></object>
+
+[1] https://cert-manager.io/docs/usage/certificate
diff --git a/content/docs/usage/kube-csr.md b/content/docs/usage/kube-csr.md
@@ -164,3 +164,7 @@ are not approved by default, so you will likely need to approve it manually:
 ```bash
 $ kubectl certificate approve <name>
 ```
+
+## Understanding the internal workings and debugging
+
+<object data="/images/request-certificate-flow/certificate-signing-request-flow.svg"></object>
diff --git a/public/images/request-certificate-flow/certificate-flow.drawio b/public/images/request-certificate-flow/certificate-flow.drawio
diff --git a/public/images/request-certificate-flow/certificate-flow.svg b/public/images/request-certificate-flow/certificate-flow.svg
diff --git a/public/images/request-certificate-flow/certificate-request-flow.drawio b/public/images/request-certificate-flow/certificate-request-flow.drawio
@@ -0,0 +1,68 @@
+<mxfile host="app.diagrams.net" modified="2023-09-07T13:04:55.858Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36" etag="m-YSrKKAoumVdo2iFwSu" version="21.7.2" type="device">
+  <diagram id="AW3OrBCQwjyOdo3bwChp" name="Page-1">
+    <mxGraphModel dx="1434" dy="782" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="MYaeiiRs0e1uR92Mewc--26" value="" style="rounded=0;whiteSpace=wrap;html=1;align=center;fontFamily=Courier New;strokeColor=none;fillColor=#EEEEEE;" parent="1" vertex="1">
+          <mxGeometry x="50" y="463" width="430" height="226" as="geometry" />
+        </mxCell>
+        <mxCell id="TSZrMiCZuQzLwb3cwMG9-14" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;fontFamily=Courier New;endArrow=classic;endFill=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" parent="1" source="t6sPMXpjrEnL9vdagRKG-4" target="t6sPMXpjrEnL9vdagRKG-2" edge="1">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="450" y="540" as="targetPoint" />
+            <mxPoint x="274" y="540" as="sourcePoint" />
+            <Array as="points">
+              <mxPoint x="220" y="450" />
+              <mxPoint x="278" y="450" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="ZZ92xPVQZ7XZ2kMUYkGM-23" value="kind: CertificateRequest&lt;br&gt;metadata:&lt;br&gt;&amp;nbsp; name: cert-1-ab0123&lt;br&gt;spec:&lt;br&gt;&amp;nbsp; issuerRef: issuer-1&lt;br&gt;&amp;nbsp; request: |&lt;br&gt;&lt;b&gt;&amp;nbsp; &amp;nbsp;&amp;nbsp;&lt;span&gt;-----BEGIN CERTIFICATE REQUEST-----&lt;br&gt;&amp;nbsp; &amp;nbsp; ...&lt;br&gt;&lt;/span&gt;&lt;/b&gt;&lt;div&gt;&lt;b&gt;&amp;nbsp; &amp;nbsp; -----END CERTIFICATE REQUEST-----&lt;/b&gt;&lt;/div&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="text;html=1;strokeColor=#d79b00;fillColor=#ffe6cc;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontFamily=Courier New;spacingTop=0;spacingBottom=0;spacing=5;" parent="1" vertex="1">
+          <mxGeometry x="50" y="100" width="344" height="150" as="geometry" />
+        </mxCell>
+        <mxCell id="SW6BRf9NdE8UDbDrH991-5" value="a controller generates a CertificateRequest" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Courier New;" parent="1" vertex="1">
+          <mxGeometry x="210" y="63" width="180" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="SW6BRf9NdE8UDbDrH991-19" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;fontFamily=Courier New;endArrow=classic;endFill=1;" parent="1" edge="1">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="205" y="70" as="sourcePoint" />
+            <mxPoint x="205" y="100" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="MYaeiiRs0e1uR92Mewc--34" value="ISSUER IMPLEMENTATION" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;dashed=1;fontColor=#757575;fontFamily=Courier New;" parent="1" vertex="1">
+          <mxGeometry x="57" y="469" width="200" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="MYaeiiRs0e1uR92Mewc--25" value="" style="endArrow=none;html=1;startArrow=classic;startFill=1;fontFamily=Courier New;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" parent="1" source="TSZrMiCZuQzLwb3cwMG9-9" target="t6sPMXpjrEnL9vdagRKG-11" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="242.37" y="654" as="sourcePoint" />
+            <mxPoint x="230.37" y="600" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="TSZrMiCZuQzLwb3cwMG9-9" value="kind: CertificateRequest&lt;br&gt;metadata:&lt;br&gt;&amp;nbsp; name:&amp;nbsp;cert-1-ab0123&lt;br&gt;&lt;div&gt;status:&lt;/div&gt;&lt;div&gt;&amp;nbsp; conditions:&lt;br&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;&amp;nbsp; &amp;nbsp; - type:&amp;nbsp;&lt;/span&gt;&lt;b style=&quot;background-color: initial; border-color: var(--border-color);&quot;&gt;Approved&lt;/b&gt;&lt;br&gt;&lt;/div&gt;&lt;div&gt;&lt;div style=&quot;border-color: var(--border-color);&quot;&gt;&amp;nbsp; &amp;nbsp; &amp;nbsp; status:&amp;nbsp;&lt;b style=&quot;border-color: var(--border-color);&quot;&gt;&quot;True&quot;&lt;/b&gt;&lt;/div&gt;&lt;div style=&quot;border-color: var(--border-color);&quot;&gt;&amp;nbsp; &amp;nbsp; &amp;nbsp; reason:&amp;nbsp;&lt;b style=&quot;border-color: var(--border-color);&quot;&gt;policy.cert-manager.io&lt;/b&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&amp;nbsp; &amp;nbsp; - type: &lt;b&gt;Ready&lt;/b&gt;&lt;/div&gt;&lt;div&gt;&amp;nbsp; &amp;nbsp; &amp;nbsp; status: &lt;b&gt;&quot;True&quot;&lt;/b&gt;&lt;/div&gt;&lt;div&gt;&amp;nbsp; &amp;nbsp; &amp;nbsp; reason: &lt;b&gt;Issued&lt;/b&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&amp;nbsp; certificate: |&lt;/div&gt;&lt;b&gt;&amp;nbsp; &amp;nbsp; -----BEGIN CERTIFICATE-----&lt;br&gt;&amp;nbsp; &amp;nbsp; (leaf)&lt;br&gt;&amp;nbsp; &amp;nbsp; -----END CERTIFICATE-----&lt;br&gt;&lt;/b&gt;&lt;b&gt;&amp;nbsp; &amp;nbsp; -----BEGIN CERTIFICATE-----&lt;br&gt;&amp;nbsp; &amp;nbsp; (intermediate)&lt;br&gt;&amp;nbsp; &amp;nbsp; -----END CERTIFICATE-----&lt;/b&gt;&lt;br&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="text;html=1;strokeColor=#d79b00;fillColor=#ffe6cc;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontFamily=Courier New;spacingTop=0;spacingBottom=0;spacing=5;" parent="1" vertex="1">
+          <mxGeometry x="108.06" y="710" width="340.37" height="270" as="geometry" />
+        </mxCell>
+        <mxCell id="t6sPMXpjrEnL9vdagRKG-2" value="Validate CertificateRequest" style="text;html=1;strokeColor=#6c8ebf;fillColor=#dae8fc;align=center;verticalAlign=top;whiteSpace=wrap;rounded=0;fontFamily=Courier New;spacingTop=0;spacingBottom=0;spacing=5;dashed=1;dashPattern=12 12;" parent="1" vertex="1">
+          <mxGeometry x="96.5" y="499" width="363.5" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="t6sPMXpjrEnL9vdagRKG-4" value="kind: CertificateRequest&lt;br&gt;metadata:&lt;br&gt;&amp;nbsp; name:&amp;nbsp;cert-1-ab0123&lt;br&gt;&lt;div&gt;status:&lt;/div&gt;&lt;div&gt;&amp;nbsp; conditions:&lt;/div&gt;&lt;div&gt;&lt;div&gt;&amp;nbsp; &amp;nbsp; - type: &lt;b&gt;Approved&lt;/b&gt;&lt;/div&gt;&lt;div&gt;&amp;nbsp; &amp;nbsp; &amp;nbsp; status: &lt;b&gt;&quot;True&quot;&lt;/b&gt;&lt;/div&gt;&lt;div&gt;&amp;nbsp; &amp;nbsp; &amp;nbsp; reason:&amp;nbsp;&lt;b&gt;policy.cert-manager.io&lt;/b&gt;&lt;/div&gt;&lt;/div&gt;" style="text;html=1;strokeColor=#d79b00;fillColor=#ffe6cc;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontFamily=Courier New;spacingTop=0;spacingBottom=0;spacing=5;" parent="1" vertex="1">
+          <mxGeometry x="50" y="300" width="340" height="130" as="geometry" />
+        </mxCell>
+        <mxCell id="t6sPMXpjrEnL9vdagRKG-5" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;fontFamily=Courier New;endArrow=classic;endFill=1;exitX=0.436;exitY=0.999;exitDx=0;exitDy=0;exitPerimeter=0;" parent="1" source="ZZ92xPVQZ7XZ2kMUYkGM-23" edge="1">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="200" y="310" as="targetPoint" />
+            <mxPoint x="220.48" y="250" as="sourcePoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="t6sPMXpjrEnL9vdagRKG-6" value="a cert-manager approver approves the CertificateRequest" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Courier New;" parent="1" vertex="1">
+          <mxGeometry x="208" y="265" width="230" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="t6sPMXpjrEnL9vdagRKG-10" value="Generate a Certificate using the CertificateRequest as input&lt;br&gt;&lt;br&gt;⚠️the public key is the only certificate attribute that is guaranteed to match the request" style="text;html=1;strokeColor=#6c8ebf;fillColor=#dae8fc;align=center;verticalAlign=top;whiteSpace=wrap;rounded=0;fontFamily=Courier New;spacingTop=0;spacingBottom=0;spacing=5;dashed=1;dashPattern=12 12;" parent="1" vertex="1">
+          <mxGeometry x="96.5" y="539" width="363.5" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="t6sPMXpjrEnL9vdagRKG-11" value="Sign Certificate" style="text;html=1;strokeColor=#6c8ebf;fillColor=#dae8fc;align=center;verticalAlign=top;whiteSpace=wrap;rounded=0;fontFamily=Courier New;spacingTop=0;spacingBottom=0;spacing=5;dashed=1;dashPattern=12 12;" parent="1" vertex="1">
+          <mxGeometry x="96.5" y="639" width="363.5" height="30" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>