Mtls Configuration

1---
2name: mtls-configuration
3description: Configure mutual TLS (mTLS) for zero-trust service-to-service communication. Use when implementing zero-trust networking, certificate management, or securing internal service communication.
4---
5 
6# mTLS Configuration
7 
8Comprehensive guide to implementing mutual TLS for zero-trust service mesh communication.
9 
10## Do not use this skill when
11 
12- The task is unrelated to mtls configuration
13- You need a different domain or tool outside this scope
14 
15## Instructions
16 
17- Clarify goals, constraints, and required inputs.
18- Apply relevant best practices and validate outcomes.
19- Provide actionable steps and verification.
20- If detailed examples are required, open `resources/implementation-playbook.md`.
21 
22## Use this skill when
23 
24- Implementing zero-trust networking
25- Securing service-to-service communication
26- Certificate rotation and management
27- Debugging TLS handshake issues
28- Compliance requirements (PCI-DSS, HIPAA)
29- Multi-cluster secure communication
30 
31## Core Concepts
32 
33### 1. mTLS Flow
34 
35```
36┌─────────┐                              ┌─────────┐
37│ Service │                              │ Service │
38│    A    │                              │    B    │
39└────┬────┘                              └────┬────┘
40     │                                        │
41┌────┴────┐      TLS Handshake          ┌────┴────┐
42│  Proxy  │◄───────────────────────────►│  Proxy  │
43│(Sidecar)│  1. ClientHello             │(Sidecar)│
44│         │  2. ServerHello + Cert      │         │
45│         │  3. Client Cert             │         │
46│         │  4. Verify Both Certs       │         │
47│         │  5. Encrypted Channel       │         │
48└─────────┘                              └─────────┘
49```
50 
51### 2. Certificate Hierarchy
52 
53```
54Root CA (Self-signed, long-lived)
55    │
56    ├── Intermediate CA (Cluster-level)
57    │       │
58    │       ├── Workload Cert (Service A)
59    │       └── Workload Cert (Service B)
60    │
61    └── Intermediate CA (Multi-cluster)
62            │
63            └── Cross-cluster certs
64```
65 
66## Templates
67 
68### Template 1: Istio mTLS (Strict Mode)
69 
70```yaml
71# Enable strict mTLS mesh-wide
72apiVersion: security.istio.io/v1beta1
73kind: PeerAuthentication
74metadata:
75  name: default
76  namespace: istio-system
77spec:
78  mtls:
79    mode: STRICT
80---
81# Namespace-level override (permissive for migration)
82apiVersion: security.istio.io/v1beta1
83kind: PeerAuthentication
84metadata:
85  name: default
86  namespace: legacy-namespace
87spec:
88  mtls:
89    mode: PERMISSIVE
90---
91# Workload-specific policy
92apiVersion: security.istio.io/v1beta1
93kind: PeerAuthentication
94metadata:
95  name: payment-service
96  namespace: production
97spec:
98  selector:
99    matchLabels:
100      app: payment-service
101  mtls:
102    mode: STRICT
103  portLevelMtls:
104    8080:
105      mode: STRICT
106    9090:
107      mode: DISABLE  # Metrics port, no mTLS
108```
109 
110### Template 2: Istio Destination Rule for mTLS
111 
112```yaml
113apiVersion: networking.istio.io/v1beta1
114kind: DestinationRule
115metadata:
116  name: default
117  namespace: istio-system
118spec:
119  host: "*.local"
120  trafficPolicy:
121    tls:
122      mode: ISTIO_MUTUAL
123---
124# TLS to external service
125apiVersion: networking.istio.io/v1beta1
126kind: DestinationRule
127metadata:
128  name: external-api
129spec:
130  host: api.external.com
131  trafficPolicy:
132    tls:
133      mode: SIMPLE
134      caCertificates: /etc/certs/external-ca.pem
135---
136# Mutual TLS to external service
137apiVersion: networking.istio.io/v1beta1
138kind: DestinationRule
139metadata:
140  name: partner-api
141spec:
142  host: api.partner.com
143  trafficPolicy:
144    tls:
145      mode: MUTUAL
146      clientCertificate: /etc/certs/client.pem
147      privateKey: /etc/certs/client-key.pem
148      caCertificates: /etc/certs/partner-ca.pem
149```
150 
151### Template 3: Cert-Manager with Istio
152 
153```yaml
154# Install cert-manager issuer for Istio
155apiVersion: cert-manager.io/v1
156kind: ClusterIssuer
157metadata:
158  name: istio-ca
159spec:
160  ca:
161    secretName: istio-ca-secret
162---
163# Create Istio CA secret
164apiVersion: v1
165kind: Secret
166metadata:
167  name: istio-ca-secret
168  namespace: cert-manager
169type: kubernetes.io/tls
170data:
171  tls.crt: <base64-encoded-ca-cert>
172  tls.key: <base64-encoded-ca-key>
173---
174# Certificate for workload
175apiVersion: cert-manager.io/v1
176kind: Certificate
177metadata:
178  name: my-service-cert
179  namespace: my-namespace
180spec:
181  secretName: my-service-tls
182  duration: 24h
183  renewBefore: 8h
184  issuerRef:
185    name: istio-ca
186    kind: ClusterIssuer
187  commonName: my-service.my-namespace.svc.cluster.local
188  dnsNames:
189    - my-service
190    - my-service.my-namespace
191    - my-service.my-namespace.svc
192    - my-service.my-namespace.svc.cluster.local
193  usages:
194    - server auth
195    - client auth
196```
197 
198### Template 4: SPIFFE/SPIRE Integration
199 
200```yaml
201# SPIRE Server configuration
202apiVersion: v1
203kind: ConfigMap
204metadata:
205  name: spire-server
206  namespace: spire
207data:
208  server.conf: |
209    server {
210      bind_address = "0.0.0.0"
211      bind_port = "8081"
212      trust_domain = "example.org"
213      data_dir = "/run/spire/data"
214      log_level = "INFO"
215      ca_ttl = "168h"
216      default_x509_svid_ttl = "1h"
217    }
218 
219    plugins {
220      DataStore "sql" {
221        plugin_data {
222          database_type = "sqlite3"
223          connection_string = "/run/spire/data/datastore.sqlite3"
224        }
225      }
226 
227      NodeAttestor "k8s_psat" {
228        plugin_data {
229          clusters = {
230            "demo-cluster" = {
231              service_account_allow_list = ["spire:spire-agent"]
232            }
233          }
234        }
235      }
236 
237      KeyManager "memory" {
238        plugin_data {}
239      }
240 
241      UpstreamAuthority "disk" {
242        plugin_data {
243          key_file_path = "/run/spire/secrets/bootstrap.key"
244          cert_file_path = "/run/spire/secrets/bootstrap.crt"
245        }
246      }
247    }
248---
249# SPIRE Agent DaemonSet (abbreviated)
250apiVersion: apps/v1
251kind: DaemonSet
252metadata:
253  name: spire-agent
254  namespace: spire
255spec:
256  selector:
257    matchLabels:
258      app: spire-agent
259  template:
260    spec:
261      containers:
262        - name: spire-agent
263          image: ghcr.io/spiffe/spire-agent:1.8.0
264          volumeMounts:
265            - name: spire-agent-socket
266              mountPath: /run/spire/sockets
267      volumes:
268        - name: spire-agent-socket
269          hostPath:
270            path: /run/spire/sockets
271            type: DirectoryOrCreate
272```
273 
274### Template 5: Linkerd mTLS (Automatic)
275 
276```yaml
277# Linkerd enables mTLS automatically
278# Verify with:
279# linkerd viz edges deployment -n my-namespace
280 
281# For external services without mTLS
282apiVersion: policy.linkerd.io/v1beta1
283kind: Server
284metadata:
285  name: external-api
286  namespace: my-namespace
287spec:
288  podSelector:
289    matchLabels:
290      app: my-app
291  port: external-api
292  proxyProtocol: HTTP/1  # or TLS for passthrough
293---
294# Skip TLS for specific port
295apiVersion: v1
296kind: Service
297metadata:
298  name: my-service
299  annotations:
300    config.linkerd.io/skip-outbound-ports: "3306"  # MySQL
301```
302 
303## Certificate Rotation
304 
305```bash
306# Istio - Check certificate expiry
307istioctl proxy-config secret deploy/my-app -o json | \
308  jq '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' | \
309  tr -d '"' | base64 -d | openssl x509 -text -noout
310 
311# Force certificate rotation
312kubectl rollout restart deployment/my-app
313 
314# Check Linkerd identity
315linkerd identity -n my-namespace
316```
317 
318## Debugging mTLS Issues
319 
320```bash
321# Istio - Check if mTLS is enabled
322istioctl authn tls-check my-service.my-namespace.svc.cluster.local
323 
324# Verify peer authentication
325kubectl get peerauthentication --all-namespaces
326 
327# Check destination rules
328kubectl get destinationrule --all-namespaces
329 
330# Debug TLS handshake
331istioctl proxy-config log deploy/my-app --level debug
332kubectl logs deploy/my-app -c istio-proxy | grep -i tls
333 
334# Linkerd - Check mTLS status
335linkerd viz edges deployment -n my-namespace
336linkerd viz tap deploy/my-app --to deploy/my-backend
337```
338 
339## Best Practices
340 
341### Do's
342- **Start with PERMISSIVE** - Migrate gradually to STRICT
343- **Monitor certificate expiry** - Set up alerts
344- **Use short-lived certs** - 24h or less for workloads
345- **Rotate CA periodically** - Plan for CA rotation
346- **Log TLS errors** - For debugging and audit
347 
348### Don'ts
349- **Don't disable mTLS** - For convenience in production
350- **Don't ignore cert expiry** - Automate rotation
351- **Don't use self-signed certs** - Use proper CA hierarchy
352- **Don't skip verification** - Verify the full chain
353 
354## Resources
355 
356- [Istio Security](https://istio.io/latest/docs/concepts/security/)
357- [SPIFFE/SPIRE](https://spiffe.io/)
358- [cert-manager](https://cert-manager.io/)
359- [Zero Trust Architecture (NIST)](https://www.nist.gov/publications/zero-trust-architecture)
360