List and table styles to kubernetes-secrets-external-secrets-operator-csi-vault article

Author: webstackdev

src/content/articles/kubernetes-secrets-external-secrets-operator-csi-vault/index.mdx

@@ -18,16 +18,17 @@ import patternDecisionDiagram from "./diagrams/pattern-decision-tree.jpg"
 
 It's 3 AM and Vault is down. Your on-call engineer gets paged because deployments are failing — pods stuck in ContainerCreating, blocking a critical hotfix. Meanwhile, another team's services keep humming along despite the same outage. The difference isn't luck. It's how secrets get into pods.
 
-Both teams use Vault. Both followed the documentation. But one team chose External Secrets Operator, which syncs secrets periodically and caches them as native Kubernetes secrets. The other chose the Secrets Store CSI Driver, which fetches secrets on-demand when pods start. When Vault went down, ESO's cached secrets kept working. CSI's synchronous fetches failed, and pods couldn't start. This isn't about which tool is better — it's about understanding the failure mode you've chosen __before__ it matters.
+Both teams use Vault. Both followed the documentation. But one team chose External Secrets Operator, which syncs secrets periodically and caches them as native Kubernetes secrets. The other chose the Secrets Store CSI Driver, which fetches secrets on-demand when pods start. When Vault went down, ESO's cached secrets kept working. CSI's synchronous fetches failed, and pods couldn't start. This isn't about which tool is better — it's about understanding the failure mode you've chosen _before_ it matters.
 
 ## The Two Patterns That Matter
 
-External secrets management in Kubernetes has consolidated around two dominant patterns. External Secrets Operator runs as a controller in your cluster, periodically syncing secrets from Vault (or AWS Secrets Manager, Azure Key Vault, etc.) into native Kubernetes Secret objects. The Secrets Store CSI Driver takes a different approach: it mounts secrets directly into pods as volumes, fetching them from the external manager when pods start.
+<Highlighter>External secrets management in Kubernetes has consolidated around two dominant patterns.</Highlighter> External Secrets Operator runs as a controller in your cluster, periodically syncing secrets from Vault (or AWS Secrets Manager, Azure Key Vault, etc.) into native Kubernetes Secret objects. The Secrets Store CSI Driver takes a different approach: it mounts secrets directly into pods as volumes, fetching them from the external manager when pods start.
 
 Both work fine when your secret manager is healthy. The difference is what happens when it isn't. ESO decouples secret fetching from pod lifecycle — the controller syncs independently, and pods consume cached Kubernetes Secrets. CSI couples them tightly — pods can't start until secrets are fetched. This architectural difference determines everything about how your applications behave during an outage.
 
 <Table
   variant="vertical-column-delineation-table"
+  fullWidth={false}
   content={{
     thead: {
       th: ['Pattern', 'Existing Pods', 'New Pods', 'Recovery'],
@@ -77,7 +78,10 @@ The pod __cannot start__ until this volume mount succeeds. If Vault is unavailab
 This has cascading implications that aren't obvious until you experience them:
 
 <List
-  variant="check-icons-list"
+  variant="timeline-list"
+  classes={{
+    wrapper: "sm:ml-6 sm:mr-12 mb-6",
+  }}
   items={[
     {
       text: 'New deployments block entirely — no pods can start',
@@ -108,6 +112,7 @@ The decision between ESO and CSI comes down to two questions: Can your applicati
 
 <Diagram
   src={patternDecisionDiagram}
+  size="full"
   title="Pattern decision tree."
   description="Flowchart guiding the choice between Kubernetes secret injection patterns based on failure tolerance. The process starts at Choose Secret Pattern and asks whether the application can tolerate minutes of staleness. If yes, the recommendation is ESO. If no, the chart asks whether the team accepts pod failures when the secret manager is down. If yes, the recommendation is CSI Driver. If no, the chart asks whether custom fallback logic is needed. If yes, the recommendation is Init Container. If no, the recommendation is ESO plus a short refresh interval. The diagram highlights that the main decision criteria are tolerance for stale secrets, tolerance for blocked pod startup during secret-manager outages, and whether the team is willing to build custom fallback behavior."
 />
@@ -130,8 +135,8 @@ For most organizations, ESO is the right default. It's operationally simpler, Gi
 
 The mistake isn't choosing either pattern. It's not understanding which failure mode you've chosen. The team that slept through the 3 AM Vault outage didn't get lucky — they understood that ESO's cached secrets would keep their services running. The team that got paged made a valid choice too; for their payment system, blocking on fresh credentials was the right call. Their runbooks reflected it.
 
-Whatever you choose, document it. When the next outage happens, your incident responders shouldn't be learning your secret injection architecture for the first time.
-
 <Callout type="success">
 Start with ESO for the majority of workloads, with a 15-minute refresh interval, and monitor sync status with alerts on stale ExternalSecrets. Add CSI for specific high-security applications where staleness is unacceptable. This gives you operational simplicity with escape hatches for edge cases.
 </Callout>
+
+Whatever you choose, document it. When the next outage happens, your incident responders shouldn't be learning your secret injection architecture for the first time.

src/content/articles/kubernetes-secrets-external-secrets-operator-csi-vault/pdf.mdx

@@ -29,24 +29,27 @@ import threeSecretDiagram from "./diagrams/three-secret-injection-patterns.jpg"
 
 It's 3 AM and Vault is down. Your on-call engineer gets paged because deployments are failing — pods stuck in ContainerCreating, blocking a critical hotfix. Meanwhile, another team's services keep humming along despite the same outage. The difference isn't luck. It's how secrets get into pods.
 
-Kubernetes secrets have a fundamental problem: they're base64-encoded, not encrypted. They sit in etcd alongside your cluster state, readable by anyone with RBAC access to the namespace. External secret managers like Vault, AWS Secrets Manager, and Azure Key Vault solve the security problem by keeping secrets outside the cluster — but they create a new problem. Your pods now depend on an external service, and that dependency has failure modes you need to understand __before__ the 3 AM page.
+Kubernetes secrets have a fundamental problem: they're base64-encoded, not encrypted. They sit in etcd alongside your cluster state, readable by anyone with RBAC access to the namespace. External secret managers like Vault, AWS Secrets Manager, and Azure Key Vault solve the security problem by keeping secrets outside the cluster — but they create a new problem. Your pods now depend on an external service, and that dependency has failure modes you need to understand _before_ the 3 AM page.
 
 Three patterns dominate secret injection:
 
 <List
-  variant="check-icons-list"
+  variant="badge-list"
+  classes={{
+    titleClass: "block w-full text-center",
+  }}
   items={[
     {
-      lead: 'External Secrets Operator',
-      text: 'syncs secrets on a schedule and caches them as native Kubernetes secrets.',
+      title: 'External Secrets Operator',
+      lead: 'Syncs secrets on a schedule and caches them as native Kubernetes secrets.',
     },
     {
-      lead: 'Secrets Store CSI Driver',
-      text: 'fetches secrets on-demand when pods start.',
+      title: 'Secrets Store CSI Driver',
+      lead: 'Fetches secrets on-demand when pods start.',
     },
     {
-      lead: 'Init containers',
-      text: 'give you complete control but require you to implement everything yourself.',
+      title: 'Init containers',
+      lead: 'Gives you complete control but require you to implement everything yourself.',
     },
   ]}
 />
@@ -55,6 +58,7 @@ Each pattern fails differently when the secret manager goes away. Consider a 30-
 
 <Table
   variant="vertical-column-delineation-table"
+  fullWidth={false}
   content={{
     thead: {
       th: ['Pattern', 'Existing Pods', 'New Pods', 'Recovery'],
@@ -83,6 +87,8 @@ ESO's pods keep running with their last-synced secrets, and new pods start succe
 
 <Diagram
   src={threeSecretDiagram}
+  magnifyButtonPosition="top-left"
+  size="full"
   title="Three secret injection patterns."
   description="Flowchart comparing three ways Kubernetes workloads receive secrets from an external secret manager. At the top, an external group labeled External Secret Manager contains Vault, AWS Secrets Manager, or another provider. Inside a grouped Kubernetes Cluster section, the first pattern labeled Pattern 1: ESO shows ESO Controller writing to a Kubernetes Secret, which is then consumed by a pod through envFrom or volumeMount. The second pattern labeled Pattern 2: CSI Driver shows the CSI Driver DaemonSet providing a pod volume mount. The third pattern labeled Pattern 3: Init Container shows an Init Container writing secret data into a shared emptyDir, which the Main Container then reads. The external manager connects to ESO through a path labeled Periodic sync and connects to both the CSI Driver and Init Container through paths labeled On pod start. The diagram emphasizes that ESO caches into native Kubernetes Secrets, CSI fetches during pod startup, and init containers implement a custom startup-time retrieval path."
 />
@@ -164,7 +170,11 @@ Even with encryption at rest, native secrets have operational limitations. There
 External Secrets Operator is a Kubernetes operator that syncs secrets from external managers — Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager — into native Kubernetes secrets. The operator runs in your cluster, periodically fetches secrets from the external source, and creates or updates Kubernetes Secret objects that your pods consume normally.
 
 <Table
-  variant="vertical-column-delineation-table"
+  variant="grid-and-accent-header-table"
+  fullWidth={false}
+  classes={{
+    tbody: '!text-content',
+  }}
   content={{
     thead: {
       th: ['Aspect', 'Native Secrets', 'External Manager'],
@@ -338,6 +348,7 @@ The key insight with ESO is the decoupling between secret fetching and pod lifec
 
 <Diagram
   src={esoSyncDiagram}
+  size="full"
   title="ESO sync flow."
   description="Sequence diagram showing how External Secrets Operator synchronizes secret values into Kubernetes. The participants are ExternalSecret, ESO Controller, Secret Manager, Kubernetes Secret, and Pod. The flow begins when the ESO Controller watches an ExternalSecret resource. Inside a loop that repeats every refreshInterval, the controller fetches secret values from the external Secret Manager, receives the values in response, and then creates or updates a Kubernetes Secret. Separately, a Pod mounts that Kubernetes Secret and receives the secret data. A note over the ESO Controller and Secret Manager explains that if the Secret Manager is down, the Kubernetes Secret keeps its last value. The diagram highlights that ESO fetches asynchronously on a controller schedule and that pods consume cached Kubernetes Secret data rather than making direct startup-time calls to the external manager."
 />
@@ -472,14 +483,15 @@ spec:
 ```
 Code: Pod with CSI secret volume.
 
-The pod __cannot start__ until the volume mounts successfully — which means until secrets are fetched from Vault. This is the key difference from ESO: the dependency is synchronous.
+The pod _cannot start_ until the volume mounts successfully — which means until secrets are fetched from Vault. This is the key difference from ESO: the dependency is synchronous.
 
 The CSI driver optionally supports rotation. Enable it by setting `--enable-secret-rotation=true` on the driver DaemonSet and adding `rotationPollInterval` to your SecretProviderClass. When enabled, the driver periodically re-fetches secrets and updates the mounted files. Your application must detect file changes (using inotify or periodic re-reads) to pick up rotated values — the driver updates files, but it can't restart your process.
 
 The flow differs fundamentally from ESO: secrets are fetched synchronously during pod startup, not asynchronously by a controller.
 
 <Diagram
   src={csiDriverDiagram}
+  size="full"
   title="CSI driver secret fetch flow."
   description="Sequence diagram showing how the Secrets Store CSI Driver fetches secrets during pod startup. The participants are Pod, CSI Driver, Vault Provider, and HashiCorp Vault. The flow begins when the Pod sends a mount volume request to the CSI Driver. The CSI Driver asks the Vault Provider to fetch secrets. The provider authenticates to Vault and reads the requested values. Vault returns the secret values to the provider, the provider returns secret data to the CSI Driver, and the CSI Driver mounts the secrets as files into the Pod. A note explains that the pod starts only after the secrets are mounted. An alternate failure path shows the provider attempting to authenticate to Vault when Vault is unavailable. Vault returns a connection failure, the provider returns an error to the CSI Driver, the CSI Driver reports that the mount fails, and a note states that the Pod stays Pending. The diagram emphasizes that CSI secret retrieval is synchronous and directly coupled to pod startup."
 />
@@ -687,7 +699,8 @@ The __init container__ pattern makes sense when you need behavior that ESO and C
 With three patterns to choose from, the decision comes down to two questions: how fresh do your secrets need to be, and what failure mode can your application tolerate?
 
 <Table
-  variant="vertical-column-delineation-table"
+  variant="numbered-review-table"
+  fullWidth={false}
   content={{
     thead: {
       th: ['Criteria', 'ESO', 'CSI Driver', 'Init Container', 'Native'],
@@ -728,38 +741,44 @@ With three patterns to choose from, the decision comes down to two questions: ho
   }}
 />
 
+The table captures raw capabilities, but choosing a pattern requires weighting those capabilities against your operational reality. A team with strong GitOps practices and tolerance for minutes of staleness will land in a different place than a team running payment infrastructure where a stale database credential means failed transactions. The deciding factor is usually the failure mode: ESO fails silently with stale data, CSI fails loudly by blocking pod startup, and init containers fail however you code them to. Each is the right answer for different risk profiles.
+
 <List
-  variant="check-icons-list"
+  variant="card-grid-list"
   items={[
     {
       lead: 'ESO',
-      text: 'fits most workloads. It\'s the simplest operationally: install the operator, create ExternalSecrets, and secrets flow into your cluster. GitOps works naturally because ExternalSecrets are declarative resources. You accept potential staleness — your secrets are only as fresh as your `refreshInterval`. For web applications, APIs, and most microservices, minutes of staleness is fine.',
+      text: 'Fits most workloads. It\'s the simplest operationally: install the operator, create ExternalSecrets, and secrets flow into your cluster. GitOps works naturally because ExternalSecrets are declarative resources. You accept potential staleness — your secrets are only as fresh as your `refreshInterval`. For web applications, APIs, and most microservices, minutes of staleness is fine.',
     },
     {
       lead: 'CSI Driver',
-      text: 'fits workloads that need fresh secrets at startup and can tolerate blocking failures. Payment processing, credential rotation during incident response, or compliance requirements that prohibit caching secrets in Kubernetes — these are CSI use cases. You accept brittleness: when Vault is down, pods don\'t start.',
+      text: 'Fits workloads that need fresh secrets at startup and can tolerate blocking failures. Payment processing, credential rotation during incident response, or compliance requirements that prohibit caching secrets in Kubernetes — these are CSI use cases. You accept brittleness: when Vault is down, pods don\'t start.',
     },
     {
       lead: 'Init containers',
-      text: 'fit edge cases where ESO and CSI don\'t provide enough control. Legacy applications that need secrets in unusual formats, multi-source fallback logic, or integration with systems that don\'t have ESO/CSI providers. You\'re writing and maintaining the logic yourself.',
+      text: 'Fits edge cases where ESO and CSI don\'t provide enough control. Legacy applications that need secrets in unusual formats, multi-source fallback logic, or integration with systems that don\'t have ESO/CSI providers. You\'re writing and maintaining the logic yourself.',
     },
     {
       lead: 'Native secrets',
-      text: 'fit non-sensitive configuration and development environments. With encryption at rest configured, they\'re acceptable for data that doesn\'t require rotation or audit trails.',
+      text: 'Fits non-sensitive configuration and development environments. With encryption at rest configured, they\'re acceptable for data that doesn\'t require rotation or audit trails.',
     },
   ]}
 />
 
 <Diagram
   src={patternDecisionDiagram}
+  size="full"
   title="Pattern decision tree."
   description="Flowchart guiding the choice between Kubernetes secret injection patterns based on failure tolerance. The process starts at Choose Secret Pattern and asks whether the application can tolerate minutes of staleness. If yes, the recommendation is ESO. If no, the chart asks whether the team accepts pod failures when the secret manager is down. If yes, the recommendation is CSI Driver. If no, the chart asks whether custom fallback logic is needed. If yes, the recommendation is Init Container. If no, the recommendation is ESO plus a short interval. The diagram highlights that the main decision points are tolerance for stale secrets, tolerance for blocked pod startup, and willingness to build custom fallback behavior."
 />
 
 ### Recommendations by Use Case
 
 <List
-  variant="check-icons-list"
+  variant="zebra-list"
+  classes={{
+    wrapper: "sm:ml-6 sm:mr-12 mb-6",
+  }}
   items={[
     {
       lead: 'Web applications and APIs',
@@ -797,7 +816,7 @@ Whichever pattern you choose, getting secrets into pods is only half the problem
 Whichever pattern you choose, the security fundamentals remain the same: authenticate with short-lived credentials, scope access narrowly, and restrict network paths.
 
 <List
-  variant="check-icons-list"
+  variant="numbered-with-background-list"
   items={[
     {
       lead: 'Vault configuration',
@@ -915,7 +934,14 @@ spec:
 Code: Secret injection alerts.
 
 <Table
-  variant="vertical-column-delineation-table"
+  variant="numbered-review-table"
+  fullWidth={false}
+  classes={{
+    thead:
+      '[&_th:nth-child(3)]:!text-center [&_th:nth-child(4)]:text-center',
+    tbody:
+      '[&_td:nth-child(3)]:!text-warning-offset [&_td:nth-child(4)]:text-danger [&_td:nth-child(3)]:!text-center [&_td:nth-child(4)]:text-center',
+  }}
   content={{
     thead: {
       th: ['Metric', 'Warning', 'Critical', 'Response'],