Enabling Mutual TLS (mTLS)
1. Understanding mTLS Mode
| Mode | Description | Security Level | Use Case |
|---|---|---|---|
| disabled | MTLS is completely disabled. No encryption or authentication between services. | None | Development/testing environments where security is not a concern. |
| permissive | Services can communicate over both MTLS and plaintext. If mTLS is not supported, fallback to plaintext. | Low | Gradual migration from plaintext to mTLS in mixed environments. |
| strict | Only mTLS is allowed. All communication must be encrypted and authenticated. | High | Production environments requiring strong security and compliance. |
Example: Configuring mTLS Mode in Istio
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
name: default
namespace: istio-system
spec:
mtls:
mode: STRICT
Note: The
strict mode is recommended for production environments to ensure all service-to-service communication is encrypted and authenticated.
2. Enabling Automatic mTLS
| Configuration Option | Description | Default Value | Notes |
|---|---|---|---|
| autoMTLS | Enables automatic mTLS for all services in the mesh | false |
When enabled, Istio automatically configures mTLS between services |
| mTLSMode | Specifies the mTLS mode for automatic configuration | PERMISSIVE |
Can be DISABLE, PERMISSIVE, or STRICT |
Example: Enabling Automatic mTLS in a Service
apiVersion: v1
kind: Service
metadata:
name: my-service
annotations:
istio.io/autoMTLS: "true"
spec:
ports:
- port: 80
targetPort: 8080
Example: Configuring mTLS Mode in MeshConfig
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
values:
global:
proxy:
autoMTLS: true
mTLSMode: STRICT
Note: Enabling automatic mTLS requires that all services in the mesh support mTLS. If some services do not support mTLS, set
mTLSMode to PERMISSIVE to allow both mTLS and plaintext traffic.
Warning: Enabling automatic mTLS in a mesh with services that do not support mTLS can cause communication failures. Ensure all services are compatible before enabling.
3. Configuring Strict mTLS Mode
| Configuration Option | Description | Values | Notes |
|---|---|---|---|
| mode | Enables strict mTLS mode for all services in the mesh | STRICT |
Ensures all communication is encrypted and authenticated |
| clientCertificate | Path to client certificate file | /etc/certs/client.crt |
Required for client-side authentication |
| clientKey | Path to client private key file | /etc/certs/client.key |
Required for client-side authentication |
| caCertificate | Path to CA certificate file | /etc/certs/ca.crt |
Used to verify service certificates |
Example: mTLS Configuration in Istio
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
name: default
spec:
mtls:
mode: STRICT
selector:
matchLabels:
app: backend
Note: Enabling strict mTLS requires all services to have valid certificates and will fail if any service does not support mTLS.
4. Implementing Permissive mTLS Mode
Permissive mTLS mode allows services to communicate over both mTLS and plaintext, providing a smooth migration path for existing services that do not yet support mTLS.
| Mode | Description | Use Case | Security Level |
|---|---|---|---|
| permissive | Allows both mTLS and plaintext traffic | Gradual migration of legacy services | Medium (plaintext traffic not secured) |
Example: Configuring Permissive mTLS in Istio
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
name: default
namespace: istio-system
spec:
mtls:
mode: PERMISSIVE
Note: Permissive mode is useful for environments where not all services support mTLS yet. It should be transitioned to
STRICT mode once all services are mTLS-enabled.
5. Configuring mTLS at Namespace Level
| Property | Description | Values | Notes |
|---|---|---|---|
| istio.io/mutual-tls | Enables or disables mTLS for the namespace | true, false |
Set to true to enforce mTLS for all services in the namespace |
| istio.io/mutual-tls-mode | Specifies the mTLS mode for the namespace | STRICT, PERMISSIVE |
STRICT requires mTLS for all services; PERMISSIVE allows both mTLS and plaintext |
Example: Enabling mTLS at Namespace Level
apiVersion: v1
kind: Namespace
metadata:
name: production
labels:
istio.io/mutual-tls: "true"
istio.io/mutual-tls-mode: "STRICT"
Note: Setting
istio.io/mutual-tls to true enforces mTLS for all services within the namespace, regardless of individual service configurations.
6. Setting mTLS at Workload Level
| Property | Description | Default Value | Notes |
|---|---|---|---|
| mtls.enabled | Enables mutual TLS for the workload | false |
Set to true to enforce mTLS |
| mtls.strict | Enforces strict mTLS mode where all traffic is encrypted | false |
Requires both client and server to support mTLS |
| mtls.permissive | Allows both mTLS and plaintext traffic | false |
Useful for gradual migration |
Example: Enabling mTLS for a workload
apiVersion: v1
kind: Service
metadata:
name: example-service
annotations:
traffic.sidecar.istio.io/includeInboundPorts: "8080"
spec:
selector:
app: example-app
ports:
- port: 8080
name: http
Example: Configuring mTLS in a workload
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
name: default-mtls
spec:
mtls:
mode: STRICT
7. Understanding Certificate Rotation
| Aspect | Description | Notes |
|---|---|---|
| Certificate Rotation Mechanism | Automatic renewal |
Based on certificate expiration time and rotation policy |
| Rotation Trigger | Scheduled |
Rotates certificates before expiration to prevent downtime |
| Certificate Validity Period | 90 days |
Standard for mTLS in service meshes |
| Key Rotation | On-demand or scheduled |
Supports both manual and automated rotation |
| Rolling Updates | Graceful transition |
Ensures zero-downtime during rotation |
Example: Certificate Rotation Configuration
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
name: mtls-policy
spec:
mtls:
mode: STRICT
selector:
matchLabels:
app: frontend
portLevelMtls:
8080:
mode: PERMISSIVE
Note: Rotation policies can be configured at the mesh or per-service level.
Warning: Misconfigured rotation can lead to service disruption or security gaps.
Key Points
- Certificates must be rotated before expiration to maintain mTLS integrity.
- Automatic rotation reduces manual overhead and human error.
- Graceful transitions ensure service availability during rotation.
8. Configuring Certificate Lifetime
| Property | Values | Description |
|---|---|---|
| certificates.ttl | 24h |
Time-to-live for generated certificates |
| certificates.renewalWindow | 2h |
Window before expiry to start renewal process |
Example: mTLS Certificate Configuration
meshConfig:
defaultConfig:
proxyMetadata:
ISTIO_META_CERT_TTL: "24h"
ISTIO_META_CERT_RENEWAL_WINDOW: "2h"
Note: Certificates are automatically renewed before expiration to maintain mTLS connectivity.
9. Verifying mTLS Connections
| Verification Method | Description | Notes |
|---|---|---|
| istioctl proxy-config listener | Checks listener configuration for mTLS settings on a specific pod. | Use with -n <namespace> to specify the namespace. |
| istioctl proxy-config secret | Displays secrets used for mTLS, including certificates and keys. | Helps verify that the correct certificates are loaded. |
| istioctl proxy-config cluster | Inspects cluster configuration to ensure mTLS is enabled for upstream services. | Useful for checking if traffic is being encrypted between clusters. |
| istioctl analyze | Performs static analysis of Istio configuration to detect mTLS misconfigurations. | Can identify issues like missing mTLS policies or incorrect peer authentication settings. |
Note: Ensure that the
istioctl command is run from a context with sufficient permissions to access the Istio configuration and proxy settings.
10. Managing mTLS Migration
Migration Workflow
- Start in
permissivemode to allow both mTLS and plaintext traffic - Gradually enforce
strictmode once all services are compatible - Monitor traffic and logs for any disruptions or errors
- Validate service-to-service communication after full migration
| Mode | Description | Use Case | Security Level |
|---|---|---|---|
| permissive | Allows both mTLS and plaintext traffic | Gradual migration, mixed environments | Low |
| strict | Enforces mTLS for all traffic | Production environments, high security | High |
Example: mTLS Mode Configuration
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
name: default
namespace: istio-system
spec:
mtls:
mode: PERMISSIVE
Note: Use
PERMISSIVE mode during migration to avoid breaking existing services that do not support mTLS.
Warning: Switching to
STRICT mode without proper service compatibility can cause communication failures.
11. Troubleshooting mTLS Issues
| Issue | Possible Cause | Solution |
|---|---|---|
| Certificate validation fails | Certificates are expired or not trusted | Check certificate validity and ensure CA is trusted by all parties |
| Handshake timeout | Network policies blocking mTLS ports or misconfigured proxies | Verify proxy configuration and network access to mTLS ports (e.g., 15001) |
| Traffic not encrypted | mTLS disabled or not enforced in mesh policy | Ensure mTLS is enabled via PeerAuthentication or DestinationRule |
| Service-to-service communication fails | Incorrect service account or missing trust domain | Validate service accounts and ensure trustDomain matches across mesh components |
Example: mTLS Policy Debugging
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
name: default
spec:
mtls:
mode: STRICT
Note: Use
istioctl proxy-config to inspect mTLS status on proxies.
Warning: Disabling mTLS in production environments can expose sensitive data.
12. Implementing mTLS Debugging
Example: mTLS Debugging with Istio
apiVersion: v1
kind: ConfigMap
metadata:
name: istio
data:
mesh: |
enablePrometheusMerge: false
enableTracing: true
defaultConfig:
proxyMetadata:
ISTIO_META_PROXY_XDS_VIA_AGENT: "true"
| Component | Description | Debugging Method |
|---|---|---|
| Istio Proxy Logs | Logs from Envoy sidecar proxies | istioctl proxy-config log <pod-name> |
| mTLS Status | Check mTLS status for a specific service | istioctl proxy-config cluster <pod-name> | grep -i mtls |
| Certificate Inspection | Inspect certificates used in mTLS handshake | istioctl proxy-config secret <pod-name> |
Note: Ensure that the
istioctl CLI is installed and configured to communicate with your Istio control plane.
Warning: Debugging mTLS issues can expose sensitive certificate information. Ensure logs are handled securely and not exposed in production environments.