Envoy · Schema
Envoy Bootstrap Configuration
The bootstrap configuration for an Envoy proxy instance, defining the static and dynamic resources, admin interface, and runtime settings needed to start the proxy.
Cloud-NativeLoad BalancingProxyService Mesh
Properties
| Name | Type | Description |
|---|---|---|
| node | object | Node identity to present to the management server and for instance identification. |
| static_resources | object | Statically specified resources including listeners, clusters, and secrets. |
| dynamic_resources | object | xDS configuration sources for dynamic resources. |
| admin | object | Configuration for the local administration HTTP server. |
| stats_config | object | Configuration for internal processing of statistics. |
| stats_sinks | array | Optional set of statistics sinks. |
| stats_flush_interval | string | Duration between stats sink flushes (e.g., '5s'). |
| tracing | object | Configuration for an external tracing provider. |
| overload_manager | object | Configuration for the overload manager. |
| layered_runtime | object | Configuration for the runtime configuration provider. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://www.envoyproxy.io/schemas/bootstrap",
"title": "Envoy Bootstrap Configuration",
"description": "The bootstrap configuration for an Envoy proxy instance, defining the static and dynamic resources, admin interface, and runtime settings needed to start the proxy.",
"type": "object",
"properties": {
"node": {
"type": "object",
"description": "Node identity to present to the management server and for instance identification.",
"properties": {
"id": {
"type": "string",
"description": "An opaque node identifier for the Envoy node."
},
"cluster": {
"type": "string",
"description": "The cluster that the Envoy node belongs to."
},
"metadata": {
"type": "object",
"description": "Opaque metadata extending the node identifier.",
"additionalProperties": true
},
"locality": {
"$ref": "#/$defs/Locality"
},
"user_agent_name": {
"type": "string",
"description": "Free-form string that identifies the entity requesting config."
},
"extensions": {
"type": "array",
"description": "List of extensions and their versions supported by the node.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"category": {
"type": "string"
},
"version": {
"type": "object"
}
}
}
}
}
},
"static_resources": {
"type": "object",
"description": "Statically specified resources including listeners, clusters, and secrets.",
"properties": {
"listeners": {
"type": "array",
"description": "Statically configured listeners.",
"items": {
"$ref": "#/$defs/Listener"
}
},
"clusters": {
"type": "array",
"description": "Statically configured upstream clusters.",
"items": {
"$ref": "#/$defs/Cluster"
}
},
"secrets": {
"type": "array",
"description": "Statically configured secrets.",
"items": {
"type": "object"
}
}
}
},
"dynamic_resources": {
"type": "object",
"description": "xDS configuration sources for dynamic resources.",
"properties": {
"lds_config": {
"$ref": "#/$defs/ConfigSource",
"description": "Listener Discovery Service (LDS) configuration source."
},
"cds_config": {
"$ref": "#/$defs/ConfigSource",
"description": "Cluster Discovery Service (CDS) configuration source."
},
"ads_config": {
"$ref": "#/$defs/ApiConfigSource",
"description": "Aggregated Discovery Service (ADS) configuration."
}
}
},
"admin": {
"type": "object",
"description": "Configuration for the local administration HTTP server.",
"properties": {
"access_log_path": {
"type": "string",
"description": "Path to the admin access log file."
},
"access_log": {
"type": "array",
"description": "Configuration for admin access logging.",
"items": {
"type": "object"
}
},
"profile_path": {
"type": "string",
"description": "Path to save profiling data."
},
"address": {
"$ref": "#/$defs/Address",
"description": "The address the admin server listens on."
}
}
},
"stats_config": {
"type": "object",
"description": "Configuration for internal processing of statistics.",
"properties": {
"stats_tags": {
"type": "array",
"description": "Tags to add to all statistics.",
"items": {
"type": "object",
"properties": {
"tag_name": {
"type": "string"
},
"regex": {
"type": "string"
},
"fixed_value": {
"type": "string"
}
}
}
},
"use_all_default_tags": {
"type": "boolean",
"description": "Use the default list of stat tags."
},
"stats_matcher": {
"type": "object",
"description": "Controls which stats are emitted.",
"properties": {
"reject_all": {
"type": "boolean"
},
"exclusion_list": {
"type": "object",
"properties": {
"patterns": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"inclusion_list": {
"type": "object",
"properties": {
"patterns": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
}
},
"stats_sinks": {
"type": "array",
"description": "Optional set of statistics sinks.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"typed_config": {
"type": "object"
}
}
}
},
"stats_flush_interval": {
"type": "string",
"description": "Duration between stats sink flushes (e.g., '5s').",
"pattern": "^[0-9]+(\\.[0-9]+)?s$"
},
"tracing": {
"type": "object",
"description": "Configuration for an external tracing provider.",
"properties": {
"http": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"typed_config": {
"type": "object"
}
}
}
}
},
"overload_manager": {
"type": "object",
"description": "Configuration for the overload manager.",
"properties": {
"refresh_interval": {
"type": "string"
},
"resource_monitors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"typed_config": {
"type": "object"
}
}
}
},
"actions": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"layered_runtime": {
"type": "object",
"description": "Configuration for the runtime configuration provider.",
"properties": {
"layers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"static_layer": {
"type": "object"
},
"disk_layer": {
"type": "object",
"properties": {
"symlink_root": {
"type": "string"
},
"subdirectory": {
"type": "string"
}
}
},
"admin_layer": {
"type": "object"
},
"rtds_layer": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"rtds_config": {
"$ref": "#/$defs/ConfigSource"
}
}
}
}
}
}
}
}
},
"$defs": {
"Locality": {
"type": "object",
"description": "Identifies location of where the Envoy node is running.",
"properties": {
"region": {
"type": "string",
"description": "Region this zone belongs to."
},
"zone": {
"type": "string",
"description": "Availability zone identifier."
},
"sub_zone": {
"type": "string",
"description": "Sub-zone within the zone."
}
}
},
"Address": {
"type": "object",
"description": "Addresses specify either a logical or physical address and port.",
"properties": {
"socket_address": {
"type": "object",
"properties": {
"protocol": {
"type": "string",
"enum": ["TCP", "UDP"],
"default": "TCP"
},
"address": {
"type": "string",
"description": "The address to bind to (IP or hostname)."
},
"port_value": {
"type": "integer",
"description": "The port to bind to.",
"minimum": 0,
"maximum": 65535
}
},
"required": ["address", "port_value"]
},
"pipe": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Unix domain socket path."
},
"mode": {
"type": "integer",
"description": "File mode for the socket."
}
}
}
}
},
"Listener": {
"type": "object",
"description": "An Envoy listener configuration.",
"properties": {
"name": {
"type": "string",
"description": "Unique name for this listener."
},
"address": {
"$ref": "#/$defs/Address",
"description": "The address the listener listens on."
},
"filter_chains": {
"type": "array",
"description": "A list of filter chains to apply to connections.",
"items": {
"$ref": "#/$defs/FilterChain"
}
},
"listener_filters": {
"type": "array",
"description": "Listener-level filters applied before filter chain matching.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"typed_config": {
"type": "object"
}
}
}
},
"per_connection_buffer_limit_bytes": {
"type": "integer",
"description": "Soft limit on size of the listener's new connection read and write buffers."
},
"traffic_direction": {
"type": "string",
"description": "Traffic direction for this listener.",
"enum": ["UNSPECIFIED", "INBOUND", "OUTBOUND"]
}
},
"required": ["name", "address", "filter_chains"]
},
"FilterChain": {
"type": "object",
"description": "A filter chain wraps a set of match criteria, an option TLS context, and a set of filters.",
"properties": {
"filter_chain_match": {
"type": "object",
"description": "Criteria for matching a connection to this filter chain.",
"properties": {
"destination_port": {
"type": "integer"
},
"server_names": {
"type": "array",
"items": {
"type": "string"
}
},
"transport_protocol": {
"type": "string"
},
"application_protocols": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"filters": {
"type": "array",
"description": "Network filters applied to the connection.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"typed_config": {
"type": "object"
}
},
"required": ["name"]
}
},
"transport_socket": {
"type": "object",
"description": "Transport socket configuration (e.g., TLS).",
"properties": {
"name": {
"type": "string"
},
"typed_config": {
"type": "object"
}
}
}
}
},
"Cluster": {
"type": "object",
"description": "An upstream cluster configuration.",
"properties": {
"name": {
"type": "string",
"description": "Name of the cluster."
},
"type": {
"type": "string",
"description": "Service discovery type.",
"enum": ["STATIC", "STRICT_DNS", "LOGICAL_DNS", "EDS", "ORIGINAL_DST"]
},
"connect_timeout": {
"type": "string",
"description": "Connection timeout (e.g., '5s')."
},
"lb_policy": {
"type": "string",
"description": "Load balancing policy.",
"enum": ["ROUND_ROBIN", "LEAST_REQUEST", "RING_HASH", "RANDOM", "MAGLEV", "CLUSTER_PROVIDED"]
},
"load_assignment": {
"$ref": "#/$defs/ClusterLoadAssignment",
"description": "Endpoint assignment for STATIC and EDS clusters."
},
"eds_cluster_config": {
"type": "object",
"description": "EDS configuration for this cluster.",
"properties": {
"eds_config": {
"$ref": "#/$defs/ConfigSource"
},
"service_name": {
"type": "string"
}
}
},
"health_checks": {
"type": "array",
"description": "Health checking configuration.",
"items": {
"$ref": "#/$defs/HealthCheck"
}
},
"circuit_breakers": {
"type": "object",
"description": "Circuit breaking configuration.",
"properties": {
"thresholds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"priority": {
"type": "string",
"enum": ["DEFAULT", "HIGH"]
},
"max_connections": {
"type": "integer"
},
"max_pending_requests": {
"type": "integer"
},
"max_requests": {
"type": "integer"
},
"max_retries": {
"type": "integer"
}
}
}
}
}
},
"outlier_detection": {
"type": "object",
"description": "Outlier detection configuration for removing unhealthy hosts.",
"properties": {
"consecutive_5xx": {
"type": "integer"
},
"interval": {
"type": "string"
},
"base_ejection_time": {
"type": "string"
},
"max_ejection_percent": {
"type": "integer"
}
}
},
"transport_socket": {
"type": "object",
"description": "Transport socket configuration for upstream connections.",
"properties": {
"name": {
"type": "string"
},
"typed_config": {
"type": "object"
}
}
},
"dns_lookup_family": {
"type": "string",
"description": "DNS lookup family for STRICT_DNS and LOGICAL_DNS clusters.",
"enum": ["AUTO", "V4_ONLY", "V6_ONLY", "V4_PREFERRED", "ALL"]
}
},
"required": ["name", "type"]
},
"ClusterLoadAssignment": {
"type": "object",
"description": "Endpoint assignments for a cluster.",
"properties": {
"cluster_name": {
"type": "string",
"description": "Name of the cluster."
},
"endpoints": {
"type": "array",
"description": "List of locality-level endpoint groups.",
"items": {
"type": "object",
"properties": {
"locality": {
"$ref": "#/$defs/Locality"
},
"lb_endpoints": {
"type": "array",
"items": {
"type": "object",
"properties": {
"endpoint": {
"type": "object",
"properties": {
"address": {
"$ref": "#/$defs/Address"
}
}
},
"health_status": {
"type": "string",
"enum": ["UNKNOWN", "HEALTHY", "UNHEALTHY", "DRAINING", "TIMEOUT", "DEGRADED"]
},
"load_balancing_weight": {
"type": "integer",
"minimum": 1
}
}
}
},
"priority": {
"type": "integer"
}
}
}
}
}
},
"HealthCheck": {
"type": "object",
"description": "Health check configuration.",
"properties": {
"timeout": {
"type": "string",
"description": "The time to wait for a health check response."
},
"interval": {
"type": "string",
"description": "The interval between health checks."
},
"unhealthy_threshold": {
"type": "integer",
"description": "Number of unhealthy checks before a host is marked unhealthy."
},
"healthy_threshold": {
"type": "integer",
"description": "Number of healthy checks before a host is marked healthy."
},
"http_health_check": {
"type": "object",
"properties": {
"host": {
"type": "string"
},
"path": {
"type": "string"
},
"expected_statuses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "integer"
},
"end": {
"type": "integer"
}
}
}
}
}
},
"tcp_health_check": {
"type": "object",
"properties": {
"send": {
"type": "object"
},
"receive": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"grpc_health_check": {
"type": "object",
"properties": {
"service_name": {
"type": "string"
}
}
}
}
},
"ConfigSource": {
"type": "object",
"description": "Configuration source for xDS API.",
"properties": {
"path": {
"type": "string",
"description": "Path on the filesystem to source from."
},
"path_config_source": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"watched_directory": {
"type": "object"
}
}
},
"api_config_source": {
"$ref": "#/$defs/ApiConfigSource"
},
"ads": {
"type": "object",
"description": "Use ADS for this resource."
},
"resource_api_version": {
"type": "string",
"enum": ["AUTO", "V2", "V3"]
}
}
},
"ApiConfigSource": {
"type": "object",
"description": "API configuration source for xDS.",
"properties": {
"api_type": {
"type": "string",
"description": "API type (REST, gRPC, delta gRPC).",
"enum": ["DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE", "REST", "GRPC", "DELTA_GRPC", "AGGREGATED_GRPC", "AGGREGATED_DELTA_GRPC"]
},
"transport_api_version": {
"type": "string",
"enum": ["AUTO", "V2", "V3"]
},
"cluster_names": {
"type": "array",
"description": "Cluster names for REST API sources.",
"items": {
"type": "string"
}
},
"grpc_services": {
"type": "array",
"description": "gRPC services for gRPC API sources.",
"items": {
"type": "object",
"properties": {
"envoy_grpc": {
"type": "object",
"properties": {
"cluster_name": {
"type": "string"
}
}
},
"google_grpc": {
"type": "object"
},
"timeout": {
"type": "string"
}
}
}
},
"refresh_delay": {
"type": "string",
"description": "Polling interval for REST APIs."
},
"set_node_on_first_message_only": {
"type": "boolean"
}
}
},
"RouteConfiguration": {
"type": "object",
"description": "Route configuration for HTTP connection manager.",
"properties": {
"name": {
"type": "string",
"description": "Name of the route configuration."
},
"virtual_hosts": {
"type": "array",
"description": "List of virtual hosts that make up the route table.",
"items": {
"$ref": "#/$defs/VirtualHost"
}
},
"internal_only_headers": {
"type": "array",
"description": "Headers that will be removed from external requests.",
"items": {
"type": "string"
}
},
"response_headers_to_add": {
"type": "array",
"description": "Headers to add to responses.",
"items": {
"$ref": "#/$defs/HeaderValueOption"
}
},
"response_headers_to_remove": {
"type": "array",
"description": "Headers to remove from responses.",
"items": {
"type": "string"
}
},
"request_headers_to_add": {
"type": "array",
"description": "Headers to add to requests.",
"items": {
"$ref": "#/$defs/HeaderValueOption"
}
}
},
"required": ["name", "virtual_hosts"]
},
"VirtualHost": {
"type": "object",
"description": "A virtual host configuration.",
"properties": {
"name": {
"type": "string",
"description": "Logical name of the virtual host."
},
"domains": {
"type": "array",
"description": "List of domains that will match this virtual host.",
"items": {
"type": "string"
}
},
"routes": {
"type": "array",
"description": "List of routes that will be matched in order.",
"items": {
"$ref": "#/$defs/Route"
}
},
"require_tls": {
"type": "string",
"enum": ["NONE", "EXTERNAL_ONLY", "ALL"]
},
"rate_limits": {
"type": "array",
"items": {
"type": "object"
}
},
"cors": {
"type": "object",
"description": "CORS policy for the virtual host."
},
"retry_policy": {
"$ref": "#/$defs/RetryPolicy"
}
},
"required": ["name", "domains", "routes"]
},
"Route": {
"type": "object",
"description": "A route entry.",
"properties": {
"name": {
"type": "string",
"description": "Name of the route."
},
"match": {
"type": "object",
"description": "Route matching parameters.",
"properties": {
"prefix": {
"type": "string"
},
"path": {
"type": "string"
},
"safe_regex": {
"type": "object",
"properties": {
"google_re2": {
"type": "object"
},
"regex": {
"type": "string"
}
}
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"string_match": {
"type": "object"
}
}
}
},
"case_sensitive": {
"type": "boolean"
}
}
},
"route": {
"type": "object",
"description": "Route action: forward to upstream cluster.",
"properties": {
"cluster": {
"type": "string"
},
"weighted_clusters": {
"type": "object",
"properties": {
"clusters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"weight": {
"type": "integer"
}
}
}
}
}
},
"timeout": {
"type": "string"
},
"retry_policy": {
"$ref": "#/$defs/RetryPolicy"
},
"prefix_rewrite": {
"type": "string"
},
"host_rewrite_literal": {
"type": "string"
}
}
},
"redirect": {
"type": "object",
"description": "Route action: return redirect.",
"properties": {
"host_redirect": {
"type": "string"
},
"path_redirect": {
"type": "string"
},
"prefix_rewrite": {
"type": "string"
},
"response_code": {
"type": "integer"
},
"https_redirect": {
"type": "boolean"
}
}
},
"direct_response": {
"type": "object",
"description": "Route action: return direct response.",
"properties": {
"status": {
"type": "integer"
},
"body": {
"type": "object",
"properties": {
"inline_string": {
"type": "string"
},
"filename": {
"type": "string"
}
}
}
}
}
},
"required": ["match"]
},
"RetryPolicy": {
"type": "object",
"description": "HTTP retry policy.",
"properties": {
"retry_on": {
"type": "string",
"description": "Conditions under which retry takes place (e.g., '5xx,connect-failure')."
},
"num_retries": {
"type": "integer",
"description": "Maximum number of retries."
},
"per_try_timeout": {
"type": "string",
"description": "Timeout per retry attempt."
},
"retry_back_off": {
"type": "object",
"properties": {
"base_interval": {
"type": "string"
},
"max_interval": {
"type": "string"
}
}
}
}
},
"HeaderValueOption": {
"type": "object",
"description": "Header name/value pair plus option to control append behavior.",
"properties": {
"header": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": ["key", "value"]
},
"append": {
"type": "boolean"
}
}
}
}
}