Configuring Trust Domains
1. Understanding Trust Domains
| Property | Description | Example |
|---|---|---|
| trustDomain | Unique identifier for a trust domain in the service mesh | "trust-domain-1" |
| caType | Specifies the type of certificate authority (e.g., internal, external) |
"internal" |
| caConfig | Configuration options for the CA, including root certificate and key paths | { "rootCertPath": "/certs/root.crt", "keyPath": "/certs/key.pem" } |
Example: Trust Domain Configuration
trustDomain: trust-domain-1
caType: internal
caConfig:
rootCertPath: /certs/root.crt
keyPath: /certs/key.pem
Note: Trust domains are used to isolate and secure communication between services within a service mesh.
Key Concepts
- Each trust domain has a unique identifier.
- Certificates are issued by a CA within the trust domain.
- Services in different trust domains cannot communicate directly without proper cross-domain trust setup.
2. Configuring Primary Trust Domain
| Property | Value | Description |
|---|---|---|
| trustDomain.name | "primary" |
Name of the primary trust domain |
| trustDomain.issuer | "https://primary-issuer.example.com" |
URL of the trust domain's issuer |
| trustDomain.certificateAuthority | "primary-ca" |
Name of the CA used for issuing certificates |
Example: Primary Trust Domain Configuration
trustDomain:
name: "primary"
issuer: "https://primary-issuer.example.com"
certificateAuthority: "primary-ca"
Note: The primary trust domain must be configured before any other trust domains in the mesh.
3. Implementing Trust Domain Federation
Trust Domain Federation allows multiple service meshes or trust domains to securely communicate with each other, enabling cross-domain service discovery and secure communication.
| Property | Description | Values | Notes |
|---|---|---|---|
| federation.trustDomain | Identifier for the trust domain | "mesh1.example.com" |
Must be unique across federated domains |
| federation.issuer | Issuer identifier for the trust domain | "https://issuer.mesh1.example.com" |
Used for JWT validation in cross-domain communication |
| federation.certificateAuthority | CA endpoint for issuing certificates | "https://ca.mesh1.example.com" |
Must support cross-domain certificate issuance |
| federation.peers | List of trusted federated domains | ["mesh2.example.com", "mesh3.example.com"] |
Each peer must have matching trust domain configuration |
Example: Federation Configuration
federation:
trustDomain: "mesh1.example.com"
issuer: "https://issuer.mesh1.example.com"
certificateAuthority: "https://ca.mesh1.example.com"
peers:
- "mesh2.example.com"
- "mesh3.example.com"
Note: Federation requires mutual trust and matching configurations between domains to ensure secure cross-domain communication.
Warning: Misconfiguring federation can lead to security vulnerabilities and service disruptions across domains.
Federation Requirements
- Shared root CA or cross-signed certificates
- Matching trust domain identifiers
- Compatible JWT issuer configurations
- Network connectivity between domains
4. Managing Trust Domain Aliases
| Alias | Trust Domain | Description |
|---|---|---|
| trust-domain-alias-1 | example.com |
Alias for the primary trust domain used in service-to-service communication |
| trust-domain-alias-2 | legacy.example.com |
Alias for legacy systems migrating to the new trust domain |
Example: Configuring Trust Domain Aliases in a Service Mesh
trustDomain:
name: "example.com"
aliases:
- "trust-domain-alias-1"
- "trust-domain-alias-2"Note: Trust domain aliases help in migrating services from one trust domain to another without requiring code changes.
5. Configuring Cross-Cluster Trust
| Property | Description | Default Value | Notes |
|---|---|---|---|
| trustDomain | Unique identifier for the trust domain | default |
Must be unique across all clusters in the mesh |
| caType | CA type used for trust domain | consul |
Options: consul, custom |
| caAddress | Address of the CA server | localhost:8501 |
Required if caType is custom |
Example: Cross-Cluster Trust Configuration
{
"connect": {
"ca": {
"type": "consul",
"address": "https://consul-server.example.com:8501"
},
"trustDomain": "cluster-a.example.com"
}
}
Note: Ensure that all clusters in the mesh use the same
trustDomain to establish mutual trust.
Warning: Misconfiguring
trustDomain can lead to certificate validation failures and service connectivity issues.
| Configuration | Cluster A | Cluster B | Notes |
|---|---|---|---|
| trustDomain | cluster-a.example.com |
cluster-b.example.com |
Must be unique per cluster |
| caType | consul |
consul |
Same CA type for trust establishment |
| caAddress | https://consul-server.example.com:8501 |
https://consul-server.example.com:8501 |
Same CA address for cross-cluster trust |
6. Setting Up Trust Domain Migration
Example: Trust Domain Migration Configuration
trustDomain:
name: "mesh.example.com"
migration:
enabled: true
sourceDomain: "old.mesh.example.com"
targetDomain: "mesh.example.com"
transitionPeriod: "24h"| Property | Description | Default Value | Notes |
|---|---|---|---|
| trustDomain.name | Name of the trust domain | None | Must be unique across mesh |
| trustDomain.migration.enabled | Enables migration mode | false | Set to true during migration |
| trustDomain.migration.sourceDomain | Old trust domain name | None | Required if migration enabled |
| trustDomain.migration.targetDomain | New trust domain name | None | Must match current trustDomain.name |
| trustDomain.migration.transitionPeriod | Duration of migration window | 24h | ISO 8601 duration format |
Note: Migration mode allows services to communicate across trust domains during the transition period.
Warning: Ensure all services support both old and new trust domains during migration.
Migration Process Overview
- Enable migration mode in configuration
- Update service configurations to trust both domains
- Gradually shift traffic to new domain
- Disable migration mode once complete
7. Implementing Trust Bundle Distribution
| Method | Description | Notes |
|---|---|---|
| File-based Distribution | trust-bundle.crt mounted as a volume |
Simple but requires manual updates |
| CA Rotation | Using cert-manager or hashicorp/vault |
Automated renewal with rotation support |
| Service Mesh CA | Integrated CA within mesh (e.g., istiod) |
Centralized trust management |
Example: File-based Trust Bundle
apiVersion: v1
kind: ConfigMap
metadata:
name: trust-bundle
data:
trust-bundle.crt: |
-----BEGIN CERTIFICATE-----
MIIF...
-----END CERTIFICATE-----
Example: CA Rotation with cert-manager
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: trust-issuer
spec:
ca:
secretName: root-ca
Note: Trust bundle distribution must be consistent across all mesh components to ensure secure communication.
Warning: Manual updates to trust bundles can cause downtime or security gaps.
8. Managing Trust Domain Boundaries
| Boundary Type | Description | Configuration | Notes |
|---|---|---|---|
| trustDomain | Unique identifier for a trust domain | "trustdomain.example" |
Must be globally unique across all services in the mesh |
| trustDomainBundle | Bundle of trust domain certificates and keys | trustdomain.example/bundle |
Used for validating service identities and establishing trust |
| trustDomainAlias | Alternative name for a trust domain | "alias.example" |
Allows services to reference trust domains by different names |
Example: Defining a Trust Domain Boundary
trustDomain:
name: "trustdomain.example"
aliases:
- "alias.example"
certificates:
- "trustdomain.example/bundle"Note: Trust domain boundaries define the scope of trust within a service mesh. All services within a trust domain must share a common root certificate authority (CA) to establish mutual TLS communication.
9. Verifying Trust Domain Configuration
Example: Verify trust domain configuration with CLI
istioctl proxy-config bootstrap <pod-name> -n <namespace> | grep trustDomain
| Configuration | Value | Description |
|---|---|---|
| trustDomain | spiffe://trust-domain-1 |
Unique identifier for the trust domain |
| trustDomainAliases | ["spiffe://alias-1"] |
Alternative identifiers for the trust domain |
Note: The trust domain must be consistent across all services in the mesh to ensure secure communication.
Warning: Changing the trust domain after services are running may cause communication failures.
10. Troubleshooting Trust Domain Issues
| Issue | Possible Cause | Solution |
|---|---|---|
| Certificate validation errors | Certificates not issued by the correct CA | Verify trust domain CA matches the certificate authority used to issue certificates |
| Service-to-service communication fails | Trust domain mismatch between services | Ensure all services in the mesh are configured to trust the same domain and use matching certificates |
| Traffic not routed correctly | Incorrect trust domain configuration in routing rules | Review and update routing policies to align with the trust domain structure |
| Authentication failures | Expired or invalid certificates in trust domain | Rotate certificates and ensure they are valid within the trust domain scope |
Note: Ensure that the certificate's Subject Alternative Name (SAN) includes the service name and that it is valid within the trust domain.
11. Implementing Trust Domain Policies
| Policy Type | Description | Configuration Example | Notes |
|---|---|---|---|
| trustDomain | Defines the trust domain name for the service mesh | "trustDomain": "mesh.local" |
Must be unique per mesh |
| trustDomainBundle | Contains the trust bundle for cross-domain communication | |
Used for mTLS between trust domains |
| policyEnforcement | Controls whether policies are enforced or not | "policyEnforcement": "enforced" |
Values: enforced, permissive, disabled |
Example: Trust Domain Policy Configuration
{
"trustDomain": "mesh.local",
"policyEnforcement": "enforced",
"trustDomainBundle": {
"bundle": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}
}Note: Trust domain policies are critical for secure cross-service communication in a multi-domain mesh setup.
Warning: Misconfiguring trust domains can lead to service communication failures or security vulnerabilities.
12. Managing Trust Domain Security
| Aspect | Description | Notes |
|---|---|---|
| trustDomain | "primary" |
Unique identifier for the trust domain |
| caType | "consul" |
CA provider used for trust domain |
| caConfig | |
Configuration for CA integration |
Example: Trust Domain Configuration
{
"mesh": {
"trustDomain": "primary",
"caConfig": {
"address": "https://consul.example.com",
"caCert": "/path/to/ca.crt"
}
}
}
Note: Ensure the CA certificate is accessible to all services in the trust domain.
Warning: Changing trust domain settings may require service restarts to re-establish trust.