mtls-configuration

Use it when:: You want services in a Kubernetes service mesh to prove their identity to each other, or a TLS handshake between them is failing.
It does:: Explains the mTLS handshake, where each side checks the other's certificate, and a certificate chain from a root CA down to short-lived workload certificates.
You get:: Istio PeerAuthentication and DestinationRule YAML, cert-manager and SPIRE configs, Linkerd policies, and commands to check certificates and debug handshakes.
Key advice:: Move from permissive to strict mode gradually, keep workload certificates to 24 hours or less and automate rotation.

TL;DR

Mutual TLS means both sides of a connection present a certificate, not only the server, so each service can verify who is calling. The SKILL.md shows the handshake between two sidecar proxies and a hierarchy of a long-lived root CA, intermediate CAs per cluster or across clusters, and workload certificates. Its rules: start permissive and tighten to strict, alert on expiry, rotate the CA, log TLS errors; never disable mTLS for convenience, ignore expiry, use self-signed certificates instead of a proper CA hierarchy or skip chain verification. A reference file has the templates: Istio strict mode mesh-wide with a permissive override for a legacy namespace and a per-port exception for metrics, DestinationRules for mTLS inside the mesh, one-way TLS to an external API and mutual TLS to a partner's, a cert-manager issuer with 24-hour certificates, a SPIRE server and agent, and Linkerd's automatic mTLS with server policies and skipped ports. It ends with commands to read a proxy's certificate, force rotation by restarting a deployment and debug handshakes with istioctl, kubectl logs and linkerd viz.

Summarizes the skill at 4bde316.

npx skills add https://github.com/wshobson/agents --skill mtls-configuration

skills.sh page Source on GitHub All skills from wshobson/agents

Total Downloads: 10,700 on skills.sh, Nov 9, 2026
Repo stars: 42,334 wshobson/agents
First seen: Jan 20, 2026 on skills.sh

Weekly Downloads

151

-19% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	186
Sep 28	219
Oct 5	280
Oct 12	221
Oct 19	180
Oct 26	182
Nov 2	170
Nov 9	151

Category	category:security category:cloud category:software-engineering Compliance, guardrails, skill vetting and browser fingerprinting. Deploy, provision, observe and debug cloud apps. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:guidelines Knowledge and rules the agent applies while it works: best practices, design principles, API references.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	security infrastructure
Stack	stack:kubernetes stack:istio stack:linkerd stack:cert-manager stack:spire

SKILL.md

From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.

Frontmatter

name: mtls-configuration
description: Configure mutual TLS (mTLS) for zero-trust service-to-service communication. Use when implementing zero-trust networking, certificate management, or securing internal service communication.

mTLS Configuration

Comprehensive guide to implementing mutual TLS for zero-trust service mesh communication.

When to Use This Skill

Implementing zero-trust networking
Securing service-to-service communication
Certificate rotation and management
Debugging TLS handshake issues
Compliance requirements (PCI-DSS, HIPAA)
Multi-cluster secure communication

Core Concepts

1. mTLS Flow

┌─────────┐                              ┌─────────┐
│ Service │                              │ Service │
│    A    │                              │    B    │
└────┬────┘                              └────┬────┘
     │                                        │
┌────┴────┐      TLS Handshake          ┌────┴────┐
│  Proxy  │◄───────────────────────────►│  Proxy  │
│(Sidecar)│  1. ClientHello             │(Sidecar)│
│         │  2. ServerHello + Cert      │         │
│         │  3. Client Cert             │         │
│         │  4. Verify Both Certs       │         │
│         │  5. Encrypted Channel       │         │
└─────────┘                              └─────────┘

2. Certificate Hierarchy

Root CA (Self-signed, long-lived)
    │
    ├── Intermediate CA (Cluster-level)
    │       │
    │       ├── Workload Cert (Service A)
    │       └── Workload Cert (Service B)
    │
    └── Intermediate CA (Multi-cluster)
            │
            └── Cross-cluster certs

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

Start with PERMISSIVE - Migrate gradually to STRICT
Monitor certificate expiry - Set up alerts
Use short-lived certs - 24h or less for workloads
Rotate CA periodically - Plan for CA rotation
Log TLS errors - For debugging and audit

Don'ts

Don't disable mTLS - For convenience in production
Don't ignore cert expiry - Automate rotation
Don't use self-signed certs - Use proper CA hierarchy
Don't skip verification - Verify the full chain