cert-manager: Init cert-manager plugin

Signed-off-by: yolossn <[email protected]>
headlamp-k8s · Dec 30, 2024 · 3ee42a1 · 3ee42a1
1 parent 42a9484
commit 3ee42a1
Show file tree

Hide file tree

Showing 27 changed files with 5,094 additions and 7,608 deletions.
diff --git a/cert-manager/README.md b/cert-manager/README.md
@@ -16,9 +16,155 @@ For more information on developing Headlamp plugins, please refer to:
 - [UI Component Storybook](https://headlamp.dev/docs/latest/development/frontend/#storybook), pre-existing components you can use when creating your plugin.
 - [Plugin Examples](https://github.com/headlamp-k8s/headlamp/tree/main/plugins/examples), Example plugins you can look at to see how it's done.
 
-certificaterequests.cert-manager.io
-certificates.cert-manager.io
-challenges.acme.cert-manager.io
-clusterissuers.cert-manager.io
-issuers.cert-manager.io
-orders.acme.cert-manager.io
+## Cert-manager CRDs:
+
+- certificates.cert-manager.io
+- certificaterequests.cert-manager.io
+- orders.acme.cert-manager.io
+- challenges.acme.cert-manager.io
+- clusterissuers.cert-manager.io
+- issuers.cert-manager.io
+- clusterissuers.cert-manager.io
+
+## Lifecycle:
+
+Certificate -> CertificateRequest -> Order -> Challenge -> Secret
+
+1. **Certificate** (Starting Point)
+
+   - This is the main custom resource the user creates
+   - It defines what the user wants: domain names, which issuer to use, and where to store the resulting certificate
+   - States: Pending → Ready or Failed
+
+2. **CertificateRequest**
+
+   - Created automatically by the Certificate controller
+   - Contains the Certificate Signing Request (CSR) and issuer reference
+   - Acts as a one-time request for a certificate
+   - States: Pending → Ready or Failed
+
+3. **Order** (ACME specific)
+
+   - Generated by the CertificateRequest when using ACME issuers (like Let's Encrypt)
+   - Manages the domain validation process
+   - States: Pending → Processing → Valid/Invalid → Ready
+
+4. **Challenge** (ACME specific)
+
+   - Created by the Order resource
+   - Proves domain ownership to the ACME server
+   - Two main types:
+   - HTTP01: Places a file on the web server
+   - DNS01: Creates a TXT record in the DNS
+   - States: Pending → Present → Valid/Invalid
+
+5. **Secret**
+   - Final output containing:
+   - The private key
+   - The signed certificate
+   - The CA certificate chain
+   - Created/updated once the Challenge is successful
+
+The flow works like this:
+
+1. The user creates a Certificate resource
+2. Cert-manager creates a CertificateRequest
+3. For ACME issuers, an Order is created
+4. The Order creates one or more Challenges
+5. Once Challenges are validated, the certificate is issued
+6. The certificate is stored in a Kubernetes Secret
+
+This process is automated and will repeat when the certificate needs renewal (typically around 30 days before expiration).
+
+State diagram
+
+```mermaid
+graph TD
+    Start((●)) --> Cert[Certificate]
+
+    %% Content and states for Certificate
+    CertNote["Defines desired state:
+    - Domain names
+    - Issuer reference
+    - Secret name
+
+    States:
+    - Pending
+    - Ready
+    - Failed"]
+    Cert --- CertNote
+
+    %% Main flow with feedback
+    Cert -->|creates| CR[CertificateRequest]
+    CR -->|updates status| Cert
+    Cert -->|creates| Secret[Secret]
+
+    %% Content and states for CertificateRequest
+    CRNote["Contains:
+    - CSR
+    - Issuer ref
+
+    States:
+    - Pending
+    - Ready
+    - Failed"]
+    CR --- CRNote
+
+    %% Order and Challenge flow
+    CR -->|generates| Order[Order]
+    Order -->|updates status| CR
+
+    %% Content and states for Order
+    OrderNote["Purpose:
+    - Domain validation
+    - Certificate retrieval
+
+    States:
+    - Pending
+    - Valid
+    - Invalid
+    - Processing
+    - Ready"]
+    Order --- OrderNote
+
+    Order -->|creates| Challenge[Challenge]
+    Challenge -->|updates status| Order
+
+    %% Content and states for Challenge
+    ChallengeNote["Purpose:
+    - Domain ownership proof
+    - HTTP01/DNS01
+
+    States:
+    - Pending
+    - Present
+    - Valid
+    - Invalid"]
+    Challenge --- ChallengeNote
+
+    %% Content for Secret
+    SecretNote["Contains:
+    - TLS private key
+    - Signed certificate
+    - CA chain
+
+    States:
+    - Present/Absent"]
+    Secret --- SecretNote
+
+    %% Styling
+    style Start fill:#666,stroke:#666
+    style Cert fill:#333,stroke:#666,color:#fff
+    style CR fill:#333,stroke:#666,color:#fff
+    style Order fill:#333,stroke:#666,color:#fff
+    style Challenge fill:#333,stroke:#666,color:#fff
+    style Secret fill:#333,stroke:#666,color:#fff
+
+    %% Note styling
+    style CertNote fill:#ffffd0,stroke:#bbb
+    style CRNote fill:#ffffd0,stroke:#bbb
+    style OrderNote fill:#ffffd0,stroke:#bbb
+    style ChallengeNote fill:#ffffd0,stroke:#bbb
+    style SecretNote fill:#ffffd0,stroke:#bbb
+
+```