Skip to content

Commit 98d2de6

Browse files
committed
List and table styles to mtls-certificate-rotation-service-mesh-authentication article
1 parent b69fb20 commit 98d2de6

3 files changed

Lines changed: 180 additions & 70 deletions

File tree

‎_TODO.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -343,5 +343,5 @@ https://mermaid.js.org/config/directives.html
343343
fullWidth={false}
344344
classes={{
345345
tbody:
346-
'[&_td:nth-child(2)]:text-green [&_td:nth-child(3)]:text-warning [&_td:nth-child(4)]:text-danger',
346+
'[&_td:nth-child(2)]:text-success [&_td:nth-child(3)]:text-warning [&_td:nth-child(4)]:text-danger',
347347
}}

‎src/content/articles/mtls-certificate-rotation-service-mesh-authentication/index.mdx‎

Lines changed: 29 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -22,18 +22,22 @@ A team enables Istio mTLS across their 50-service mesh. Initial rollout goes smo
2222

2323
Recovery takes four hours because the on-call engineer has never manually rotated Istio certificates and the runbook doesn't exist yet.
2424

25-
If this sounds familiar, you're not alone. Enabling mTLS is a configuration change; operating it reliably is an ongoing commitment to understanding certificate lifecycles, building automation for rotation, and monitoring for expiration failures.
25+
If this sounds familiar, you're not alone. <Highlighter>Enabling mTLS is a configuration change; operating it reliably is an ongoing commitment to understanding certificate lifecycles, building automation for rotation, and monitoring for expiration failures.</Highlighter>
2626

2727
## The Operational Reality of mTLS
2828

2929
Standard TLS — what you use when visiting any HTTPS website — is a one-way trust relationship. The server proves its identity to the client by presenting a certificate. The client validates that certificate against its trust store. The server has no idea who the client is at the transport layer.
3030

3131
Mutual TLS adds a second handshake step: after the client validates the server's certificate, the server requests and validates a certificate from the client. Both parties cryptographically prove their identity before any application data flows.
3232

33-
The operational cost difference is significant. With standard TLS, you manage certificates for servers — maybe dozens or hundreds. With mTLS, __every__ service needs a certificate, and every service needs to validate certificates from every other service it communicates with. In a 100-service mesh, that's potentially thousands of certificate validation paths to maintain.
33+
The operational cost difference is significant. With standard TLS, you manage certificates for servers — maybe dozens or hundreds. With mTLS, _every_ service needs a certificate, and every service needs to validate certificates from every other service it communicates with. In a 100-service mesh, that's potentially thousands of certificate validation paths to maintain.
3434

3535
<Table
36-
variant="vertical-column-delineation-table"
36+
variant="grid-and-accent-header-table"
37+
fullWidth={false}
38+
classes={{
39+
tbody: '!text-content',
40+
}}
3741
content={{
3842
thead: {
3943
th: ['Aspect', 'Standard TLS', 'Mutual TLS'],
@@ -79,22 +83,25 @@ __CA rotation__ is harder. When you rotate an intermediate or root CA, you're ch
7983
The safe order for CA rotation:
8084

8185
<List
82-
variant="numbered-with-background-list"
86+
variant="timeline-list"
87+
classes={{
88+
wrapper: "sm:ml-6 sm:mr-12 mb-6",
89+
}}
8390
items={[
8491
{
85-
text: 'Add the new CA to all trust bundles (services now trust both old and new)',
92+
lead: 'Add the new CA to all trust bundles (services now trust both old and new)',
8693
},
8794
{
88-
text: 'Verify all services have received the updated trust bundle',
95+
lead: 'Verify all services have received the updated trust bundle',
8996
},
9097
{
91-
text: 'Start issuing certificates from the new CA',
98+
lead: 'Start issuing certificates from the new CA',
9299
},
93100
{
94-
text: 'Wait for all workload certificates to rotate to the new CA',
101+
lead: 'Wait for all workload certificates to rotate to the new CA',
95102
},
96103
{
97-
text: 'Remove the old CA from trust bundles',
104+
lead: 'Remove the old CA from trust bundles',
98105
},
99106
]}
100107
/>
@@ -103,6 +110,7 @@ This sequence diagram shows the rotation flow:
103110

104111
<Diagram
105112
src={caRotationDiagram}
113+
size="full"
106114
title="CA rotation sequence showing the safe order of operations."
107115
description="Sequence diagram with three participants: Workload, Certificate Authority, and Trust Store. The first phase is Step 1, Add New CA to Trust. The Certificate Authority sends a new CA certificate to the Trust Store, and the Trust Store updates the Workload with a trust bundle that includes both the old and new CA. The second phase is Step 2, Verify Distribution, where the Workload confirms it has received the new trust bundle. The third phase is Step 3, Issue New Certs, where the Workload sends a CSR for a new certificate to the Certificate Authority, and the Certificate Authority returns a certificate signed by the new CA. The fourth phase is Step 4, Verify Full Rotation, where the Workload asks the Certificate Authority whether any certificates signed by the old CA remain, and the response is that none remain. The fifth phase is Step 5, Remove Old CA, where the Trust Store removes the old CA and the Workload receives an updated trust bundle containing only the new CA. The diagram emphasizes that trust must be updated before new certificates are issued, and the old CA must only be removed after all workloads have rotated."
108116
/>
@@ -146,7 +154,8 @@ groups:
146154
Different certificate levels need different alert thresholds:
147155
148156
<Table
149-
variant="vertical-column-delineation-table"
157+
variant="numbered-review-table"
158+
fullWidth={false}
150159
content={{
151160
thead: {
152161
th: ['Certificate Type', 'Typical TTL', 'Warning', 'Critical'],
@@ -184,31 +193,35 @@ mTLS failures produce cryptic errors. The TLS handshake fails, and you get a gen
184193
### Common Failure Modes
185194
186195
<List
187-
variant="check-icons-list"
196+
variant="zebra-list"
188197
items={[
189198
{
190199
lead: 'Certificate expired',
191-
text: 'The most common cause of mTLS outages. Error messages include `x509: certificate has expired`. Check expiration with `openssl x509 -enddate -noout -in cert.pem`. Fix by forcing rotation or restarting the workload to trigger certificate renewal.',
200+
text: 'The most common cause of mTLS outages. Error messages include <span class="font-mono">x509: certificate has expired</span>. Check expiration with <span class="font-mono">openssl x509 -enddate -noout -in cert.pem</span>. Fix by forcing rotation or restarting the workload to trigger certificate renewal.',
192201
},
193202
{
194203
lead: 'Trust chain broken',
195-
text: 'The certificate is valid but the CA that signed it isn\'t in the trust store. You\'ll see `x509: certificate signed by unknown authority`. This happens during CA rotation if trust bundles aren\'t updated before new certificates are issued.',
204+
text: 'The certificate is valid but the CA that signed it isn\'t in the trust store. You\'ll see <span class="font-mono">x509: certificate signed by unknown authority</span>. This happens during CA rotation if trust bundles aren\'t updated before new certificates are issued.',
196205
},
197206
{
198207
lead: 'SAN mismatch',
199-
text: 'The certificate is valid but doesn\'t include the hostname being used. Error: `x509: certificate is valid for X, not Y`. This commonly happens when DNS names change or when certificates are issued with incomplete SAN lists.',
208+
text: 'The certificate is valid but doesn\'t include the hostname being used. Error: <span class="font-mono">x509: certificate is valid for X, not Y</span>. This commonly happens when DNS names change or when certificates are issued with incomplete SAN lists.',
200209
},
201210
{
202211
lead: 'Wrong key usage',
203-
text: 'The certificate exists but wasn\'t issued for mTLS. If it only has `serverAuth` in Extended Key Usage, it can\'t be used as a client certificate. Reissue with both `serverAuth` and `clientAuth`.',
212+
text: 'The certificate exists but wasn\'t issued for mTLS. If it only has <span class="font-mono">serverAuth</span> in Extended Key Usage, it can\'t be used as a client certificate. Reissue with both <span class="font-mono">serverAuth</span> and <span class="font-mono">clientAuth</span>.',
204213
},
205214
]}
206215
/>
207216
208217
I once spent two hours debugging a "connection reset by peer" that turned out to be a certificate with `serverAuth` only — no `clientAuth`. The error message mentioned nothing about key usage. The fix was a one-line change to the certificate spec, but finding it required systematically ruling out every other possibility.
209218

210219
<Table
211-
variant="vertical-column-delineation-table"
220+
variant="grid-and-accent-header-table"
221+
fullWidth={false}
222+
classes={{
223+
tbody: '!text-content',
224+
}}
212225
content={{
213226
thead: {
214227
th: ['Symptom', 'Likely Cause', 'First Check'],

0 commit comments

Comments
 (0)