Istio · Schema
Istio DestinationRule
A DestinationRule defines policies that apply to traffic intended for a service after routing has occurred. These rules specify configuration for load balancing, connection pool size, and outlier detection to detect and evict unhealthy hosts from the load balancing pool.
CNCFKubernetesMicroservicesOpen SourceService Mesh
Properties
| Name | Type | Description |
|---|---|---|
| host | string | The name of the service from the service registry. Rules defined for services that do not exist in the registry will be ignored. |
| trafficPolicy | object | Traffic policies to apply for the specific destination. |
| subsets | array | One or more named sets that represent individual versions of a service. |
| exportTo | array | A list of namespaces to which this DestinationRule is exported. |
| workloadSelector | object | Criteria used to select the specific set of pods/VMs on which this DestinationRule configuration should be applied. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/api-evangelist/istio/blob/main/json-schema/destination-rule.json",
"title": "Istio DestinationRule",
"description": "A DestinationRule defines policies that apply to traffic intended for a service after routing has occurred. These rules specify configuration for load balancing, connection pool size, and outlier detection to detect and evict unhealthy hosts from the load balancing pool.",
"type": "object",
"properties": {
"host": {
"type": "string",
"description": "The name of the service from the service registry. Rules defined for services that do not exist in the registry will be ignored."
},
"trafficPolicy": {
"$ref": "#/$defs/TrafficPolicy",
"description": "Traffic policies to apply for the specific destination."
},
"subsets": {
"type": "array",
"items": {
"$ref": "#/$defs/Subset"
},
"description": "One or more named sets that represent individual versions of a service."
},
"exportTo": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of namespaces to which this DestinationRule is exported."
},
"workloadSelector": {
"type": "object",
"properties": {
"matchLabels": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "One or more labels that indicate a specific set of pods/VMs on which a policy should be applied."
}
},
"description": "Criteria used to select the specific set of pods/VMs on which this DestinationRule configuration should be applied."
}
},
"required": ["host"],
"$defs": {
"TrafficPolicy": {
"type": "object",
"properties": {
"connectionPool": {
"type": "object",
"description": "Settings controlling the volume of connections to an upstream service.",
"properties": {
"tcp": {
"type": "object",
"properties": {
"maxConnections": {
"type": "integer",
"description": "Maximum number of HTTP1/TCP connections to a destination host."
},
"connectTimeout": {
"type": "string",
"description": "TCP connection timeout."
},
"tcpKeepalive": {
"type": "object",
"properties": {
"probes": { "type": "integer" },
"time": { "type": "string" },
"interval": { "type": "string" }
}
}
}
},
"http": {
"type": "object",
"properties": {
"h2UpgradePolicy": {
"type": "string",
"enum": ["DEFAULT", "DO_NOT_UPGRADE", "UPGRADE"],
"description": "Specify if http1.1 connections should be upgraded to http2."
},
"http1MaxPendingRequests": {
"type": "integer",
"description": "Maximum number of requests that will be queued while waiting for a ready connection pool connection."
},
"http2MaxRequests": {
"type": "integer",
"description": "Maximum number of active requests to a destination."
},
"maxRequestsPerConnection": {
"type": "integer",
"description": "Maximum number of requests per connection to a backend."
},
"maxRetries": {
"type": "integer",
"description": "Maximum number of retries that can be outstanding to all hosts in a cluster at a given time."
},
"idleTimeout": {
"type": "string",
"description": "The idle timeout for upstream connection pool connections."
}
}
}
}
},
"loadBalancer": {
"type": "object",
"description": "Settings controlling the load balancer algorithms.",
"properties": {
"simple": {
"type": "string",
"enum": ["UNSPECIFIED", "LEAST_CONN", "RANDOM", "PASSTHROUGH", "ROUND_ROBIN", "LEAST_REQUEST"],
"description": "Standard load balancing algorithm."
},
"consistentHash": {
"type": "object",
"description": "Consistent hash-based load balancing for soft session affinity.",
"properties": {
"httpHeaderName": {
"type": "string",
"description": "Hash based on a specific HTTP header."
},
"httpCookie": {
"type": "object",
"properties": {
"name": { "type": "string" },
"path": { "type": "string" },
"ttl": { "type": "string" }
}
},
"useSourceIp": {
"type": "boolean",
"description": "Hash based on the source IP address."
},
"httpQueryParameterName": {
"type": "string",
"description": "Hash based on a specific HTTP query parameter."
},
"minimumRingSize": {
"type": "integer",
"description": "Minimum hash ring size."
}
}
},
"localityLbSetting": {
"type": "object",
"description": "Locality load balancer settings.",
"properties": {
"distribute": {
"type": "array",
"items": { "type": "object" }
},
"failover": {
"type": "array",
"items": { "type": "object" }
},
"failoverPriority": {
"type": "array",
"items": { "type": "string" }
},
"enabled": {
"type": "boolean"
}
}
},
"warmupDurationSecs": {
"type": "string",
"description": "Duration for which newly added endpoints are in warm-up mode."
}
}
},
"outlierDetection": {
"type": "object",
"description": "Settings controlling eviction of unhealthy hosts from the load balancing pool.",
"properties": {
"consecutive5xxErrors": {
"type": "integer",
"description": "Number of 5xx errors before a host is ejected."
},
"consecutiveGatewayErrors": {
"type": "integer",
"description": "Number of gateway errors before a host is ejected."
},
"interval": {
"type": "string",
"description": "Time interval between ejection sweep analysis."
},
"baseEjectionTime": {
"type": "string",
"description": "Minimum ejection duration."
},
"maxEjectionPercent": {
"type": "integer",
"description": "Maximum percentage of hosts in the load balancing pool that can be ejected."
},
"minHealthPercent": {
"type": "integer",
"description": "Outlier detection will be enabled when healthy hosts percentage drops below this threshold."
},
"splitExternalLocalOriginErrors": {
"type": "boolean",
"description": "Determines whether to distinguish local origin failures from external errors."
}
}
},
"tls": {
"$ref": "#/$defs/ClientTLSSettings",
"description": "TLS related settings for connections to the upstream service."
},
"portLevelSettings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"port": {
"type": "object",
"properties": {
"number": { "type": "integer" }
}
},
"connectionPool": { "type": "object" },
"loadBalancer": { "type": "object" },
"outlierDetection": { "type": "object" },
"tls": { "$ref": "#/$defs/ClientTLSSettings" }
}
},
"description": "Traffic policies specific to individual ports."
},
"tunnel": {
"type": "object",
"description": "Configuration for tunneling TCP over other transport layers.",
"properties": {
"protocol": {
"type": "string",
"description": "Protocol used for tunneling (e.g. CONNECT, POST)."
},
"targetHost": {
"type": "string",
"description": "Target host for the tunnel."
},
"targetPort": {
"type": "integer",
"description": "Target port for the tunnel."
}
}
}
}
},
"Subset": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the subset."
},
"labels": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Labels apply a filter over the endpoints of a service in the service registry."
},
"trafficPolicy": {
"$ref": "#/$defs/TrafficPolicy",
"description": "Traffic policies that apply to this subset."
}
},
"required": ["name"]
},
"ClientTLSSettings": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": ["DISABLE", "SIMPLE", "MUTUAL", "ISTIO_MUTUAL"],
"description": "Indicates whether connections to this port should be secured using TLS."
},
"clientCertificate": {
"type": "string",
"description": "Path to the file holding the client-side TLS certificate."
},
"privateKey": {
"type": "string",
"description": "Path to the file holding the client's private key."
},
"caCertificates": {
"type": "string",
"description": "Path to the file containing certificate authority certificates."
},
"credentialName": {
"type": "string",
"description": "The name of the secret that holds the TLS certs."
},
"subjectAltNames": {
"type": "array",
"items": { "type": "string" },
"description": "A list of alternate names to verify the subject identity in the certificate."
},
"sni": {
"type": "string",
"description": "SNI string to present to the server during TLS handshake."
},
"insecureSkipVerify": {
"type": "boolean",
"description": "If true, the TLS client will not verify the server certificate."
}
}
}
}
}