diff --git a/api/BUILD b/api/BUILD index e70d9731..a2d22307 100644 --- a/api/BUILD +++ b/api/BUILD @@ -1,18 +1,49 @@ load("//bazel:api_build_system.bzl", "api_proto_library") api_proto_library( - name = "node", - srcs = ["node.proto"], + name = "address", + srcs = ["address.proto"], +) + +api_proto_library( + name = "base", + srcs = ["base.proto"], +) + +api_proto_library( + name = "health_check", + srcs = ["health_check.proto"], + deps = [":base"], +) + +api_proto_library( + name = "ssl_context", + srcs = ["ssl_context.proto"], +) + +api_proto_library( + name = "cds", + srcs = ["cds.proto"], + deps = [ + ":address", + ":base", + ":health_check", + ":ssl_context", + ], ) api_proto_library( name = "lds", srcs = ["lds.proto"], - deps = [":node"], + deps = [ + ":address", + ":base", + ":ssl_context", + ], ) api_proto_library( name = "rds", srcs = ["rds.proto"], - deps = [":node"], + deps = [":base"], ) diff --git a/api/address.proto b/api/address.proto new file mode 100644 index 00000000..ad2bd53f --- /dev/null +++ b/api/address.proto @@ -0,0 +1,21 @@ +syntax = "proto3"; + +import "google/protobuf/wrappers.proto"; + +// [V2-API-DIFF] Addresses now have .proto structure. +message Address { + message SocketAddress { + // For listeners, bind to 0.0.0.0 or :: to support the use of prefix/suffix + // matching in FilterChainMatch. For clusters, an address may be either an + // IP or hostname to be resolved via DNS. + google.protobuf.StringValue address = 1; + google.protobuf.UInt32Value port = 2; + } + message Pipe { + google.protobuf.StringValue path = 1; + } + oneof address { + SocketAddress socket_address = 1; + Pipe pipe = 2; + } +} diff --git a/api/node.proto b/api/base.proto similarity index 85% rename from api/node.proto rename to api/base.proto index 9eb12f55..7428d737 100644 --- a/api/node.proto +++ b/api/base.proto @@ -1,6 +1,7 @@ syntax = "proto3"; import "google/protobuf/struct.proto"; +import "google/protobuf/wrappers.proto"; // Identifies location of where either Envoy runs or where upstream hosts run. message Locality { @@ -22,3 +23,7 @@ message Node { google.protobuf.Struct metadata = 2; Locality locality = 3; } + +message Duration { + google.protobuf.UInt32Value milliseconds = 1; +} diff --git a/api/cds.proto b/api/cds.proto new file mode 100644 index 00000000..4b3e9eca --- /dev/null +++ b/api/cds.proto @@ -0,0 +1,179 @@ +syntax = "proto3"; + +import "api/address.proto"; +import "api/base.proto"; +import "api/health_check.proto"; +import "api/ssl_context.proto"; + +import "google/protobuf/wrappers.proto"; + +service ClusterDiscoveryService { + // Return list of all clusters, this proxy will load balance to. + rpc StreamClusters(ClusterDiscoveryRequest) + returns (stream ClusterDiscoveryResponse) { + } +} + +message ClusterDiscoveryRequest { + Node node = 1; +} + +message ClusterDiscoveryResponse { + repeated Cluster cluster = 1; +} + +// Circuit breaking settings can be specified individually for each defined +// priority. +message CircuitBreakers { + message Thresholds { + // The maximum number of connections that Envoy will make to the upstream + // cluster. If not specified, the default is 1024. See the circuit + // breaking overview for more information. + google.protobuf.UInt32Value max_connections = 1; + // The maximum number of pending requests that Envoy will allow to the + // upstream cluster. If not specified, the default is 1024. See the circuit + // breaking overview for more information. + google.protobuf.UInt32Value max_pending_requests = 2; + // The maximum number of parallel requests that Envoy will make to the + // upstream cluster. If not specified, the default is 1024. See the circuit + // breaking overview for more information. + google.protobuf.UInt32Value max_requests = 3; + // The maximum number of parallel retries that Envoy will allow to the + // upstream cluster. If not specified, the default is 3. See the circuit + // breaking overview for more information. + google.protobuf.UInt32Value max_retries = 4; + } + + Thresholds default_priority = 1; + Thresholds high_priority = 2; +} + + +message TcpProtocolOptions { +} + +message Http1ProtocolOptions { +} + +message Http2ProtocolOptions { + // Default is false. + bool disable_dynamic_table = 1; + uint32 per_stream_buffer_limit_bytes = 2; +} + +message GrpcProtocolOptions { + uint32 per_stream_buffer_limit_bytes = 1; +} + +message Cluster { + // Supplies the name of the cluster which must be unique across all clusters. + // The cluster name is used when emitting statistics. The cluster name can be + // at most 60 characters long, and must not contain :. + google.protobuf.StringValue name = 1; + + // The service discovery type to use for resolving the cluster. + enum DiscoveryType { + STATIC = 0; + STRICT_DNS = 1; + LOGICAL_DNS = 2; + EDS = 3; + } + DiscoveryType type = 2; + + // The timeout for new network connections to hosts in the cluster. + Duration connect_timeout = 3; + // Soft limit on size of the cluster’s connections read and write buffers. If + // unspecified, an implementation defined default is applied (1MiB). + google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 4; + + // The load balancer type to use when picking a host in the cluster. + enum LbPolicy { + ROUND_ROBIN = 0; + LEAST_REQUEST = 1; + RING_HASH = 2; + RANDOM = 3; + } + LbPolicy lb_policy = 5; + + // If the service discovery type is static, strict_dns, or logical_dns + // the hosts array is required. + repeated Address hosts = 6; + + // Optional active health checking configuration for the cluster. If no + // configuration is specified no health checking will be done and all cluster + // members will be considered healthy at all times. + repeated HealthCheck health_check = 7; + + // Optional maximum requests for a single upstream connection. This parameter + // is respected by both the HTTP/1.1 and HTTP/2 connection pool + // implementations. If not specified, there is no limit. Setting this + // parameter to 1 will effectively disable keep alive. + google.protobuf.UInt32Value max_requests_per_connection = 8; + + // Optional circuit breaking settings for the cluster. + CircuitBreakers circuit_breakers = 9; + + // The TLS configuration for connections to the upstream cluster. If no TLS + // configuration is specified, TLS will not be used for new connections. + UpstreamSslContext ssl_context = 10; + + oneof protocol_options { + TcpProtocolOptions tcp_protocol_options = 11; + Http1ProtocolOptions http_protocol_options = 12; + Http2ProtocolOptions http2_protocol_options = 13; + GrpcProtocolOptions grpc_protocol_options = 14; + } + + // If the dns refresh rate is specified and the cluster type is either + // strict_dns, or logical_dns, this value is used as the cluster’s dns refresh + // rate. If this setting is not specified, the value defaults to 5000. For + // cluster types other than strict_dns and logical_dns this setting is + // ignored. + Duration dns_refresh_rate = 15; + + // If specified, outlier detection will be enabled for this upstream cluster. + message OutlierDetection { + // The number of consecutive 5xx responses before a consecutive 5xx ejection + // occurs. Defaults to 5. + google.protobuf.UInt32Value consecutive_5xx = 1; + // The time interval between ejection analysis sweeps. This can result in + // both new ejections as well as hosts being returned to service. Defaults + // to 10000ms or 10s. + Duration interval = 2; + // The base time that a host is ejected for. The real time is equal to the + // base time multiplied by the number of times the host has been ejected. + // Defaults to 30000ms or 30s. + Duration base_ejection_time = 3; + // The maximum % of an upstream cluster that can be ejected due to outlier + // detection. Defaults to 10%. + google.protobuf.UInt32Value max_ejection_percent = 4; + // The % chance that a host will be actually ejected when an outlier status + // is detected through consecutive 5xx. This setting can be used to disable + // ejection or to ramp it up slowly. Defaults to 100. + google.protobuf.UInt32Value enforcing_consecutive_5xx = 5; + // The % chance that a host will be actually ejected when an outlier status + // is detected through success rate statistics. This setting can be used to + // disable ejection or to ramp it up slowly. Defaults to 100. + google.protobuf.UInt32Value enforcing_success_rate = 6; + // The number of hosts in a cluster that must have enough request volume to + // detect success rate outliers. If the number of hosts is less than this + // setting, outlier detection via success rate statistics is not performed + // for any host in the cluster. Defaults to 5. + google.protobuf.UInt32Value success_rate_minimum_hosts = 7; + // The minimum number of total requests that must be collected in one + // interval (as defined by interval_ms above) to include this host in + // success rate based outlier detection. If the volume is lower than this + // setting, outlier detection via success rate statistics is not performed + // for that host. Defaults to 100. + google.protobuf.UInt32Value success_rate_request_volume = 8; + // This factor is used to determine the ejection threshold for success rate + // outlier ejection. The ejection threshold is the difference between the + // mean success rate, and the product of this factor and the standard + // deviation of the mean success rate: mean - (stdev * + // success_rate_stdev_factor). This factor is divided by a thousand to get a + // double. That is, if the desired factor is 1.9, the runtime value should + // be 1900. Defaults to 1900. + google.protobuf.UInt32Value success_rate_stdev_factor = 9; + } + OutlierDetection outlier_detection = 16; +} diff --git a/api/health_check.proto b/api/health_check.proto new file mode 100644 index 00000000..37f874f6 --- /dev/null +++ b/api/health_check.proto @@ -0,0 +1,58 @@ +syntax = "proto3"; + +import "api/base.proto"; + +import "google/protobuf/wrappers.proto"; + +message HealthCheck { + // The time to wait for a health check response. If the timeout is reached the + // health check attempt will be considered a failure. + Duration timeout = 1; + // The interval between health checks. + Duration interval = 2; + // An optional jitter amount in millseconds. If specified, during every + // internal Envoy will add 0 to interval_jitter to the wait time. + Duration interval_jitter = 3; + + // The number of unhealthy health checks required before a host is marked + // unhealthy. Note that for http health checking if a host responds with 503 + // this threshold is ignored and the host is considered unhealthy immediately. + google.protobuf.UInt32Value unhealthy_threshold = 4; + // The number of healthy health checks required before a host is marked + // healthy. Note that during startup, only a single successful health check is + // required to mark a host healthy. + google.protobuf.UInt32Value healthy_threshold = 5; + + // Non-serving port for health checking. + google.protobuf.UInt32Value alt_port = 6; + // Reuse health check connection between health checks. Default is true. + google.protobuf.BoolValue reuse_connection = 7; + + // Describes the encoding of the payload bytes in the payload + message Payload { + oneof payload { + google.protobuf.StringValue text = 1; + google.protobuf.BytesValue binary = 2; + } + } + message HttpHealthCheck { + // The value of the host header in the HTTPS health check request. If left + // empty (default value), the IP on behalf of which this health check is + // performed will be used. + string host = 1; + // This parameter is required if the type is http. It species the HTTP path + // that will be requested during health checking. For example /healthcheck. + string path = 2; + Payload send = 3; + Payload receive = 4; + } + message TcpHealthCheck { + // Empty payloads imply a connect-only health check. + Payload send = 1; + Payload receive = 2; + } + oneof health_checker { + HttpHealthCheck http_health_check = 8; + TcpHealthCheck tcp_health_check = 9; + } +} diff --git a/api/lds.proto b/api/lds.proto index ae6b0d37..6bd77c1d 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -4,7 +4,9 @@ syntax = "proto3"; -import "api/node.proto"; +import "api/address.proto"; +import "api/base.proto"; +import "api/ssl_context.proto"; import "google/protobuf/struct.proto"; import "google/protobuf/wrappers.proto"; @@ -26,93 +28,6 @@ message ListenerDiscoverResponse { repeated Listener listeners = 1; } -// [V2-API-DIFF] Addresses now have .proto structure. -message ListenerAddress { - message SocketAddress { - // Bind to 0.0.0.0 or :: to support the use of prefix/suffix matching in - // FilterChainMatch. - google.protobuf.StringValue address = 1; - google.protobuf.UInt32Value port = 2; - } - message Pipe { - google.protobuf.StringValue path = 1; - } - oneof address { - SocketAddress socket_address = 1; - Pipe pipe = 2; - } -} - -message DataSource { - oneof specifier { - google.protobuf.StringValue filename = 1; - google.protobuf.BytesValue inline = 2; - } -} - -// SSL certs can be loaded from file or delivered inline [V2-API-DIFF]. Individual fields may -// be loaded from either. -message SslCertificate { - DataSource cert_chain = 1; - DataSource private_key = 2; - DataSource ocsp_staple = 3; - repeated DataSource signed_certificate_timestamp = 4; -} - -message ClientSslContext { - // SSL certificate data containing certificate authority certificates to use - // in verifying a presented client side certificate. If not specified and a - // client certificate is presented it will not be verified. - DataSource ca_cert = 1; - - // If specified, Envoy will verify (pin) the hash of the presented client side - // certificate. - google.protobuf.StringValue verify_certificate_hash = 2; - - // An optional list of subject alt names. If specified, Envoy will verify that - // the client certificate’s subject alt name matches one of the specified - // values. - repeated google.protobuf.StringValue verify_subject_alt_name = 3; - - // Client must present a signed time-stamped OCSP response. - google.protobuf.BoolValue require_ocsp_staple = 4; - - // Client must present signed certificate time-stamp. - google.protobuf.BoolValue require_signed_certificate_timestamp = 5; -} - -// [V2-API-DIFF] This has been reworked to support alternative modes of -// certificate/key delivery, for consistency with the upstream SSL context and -// to segregate the client/server aspects of the SSL context. -message SslContext { - // Multiple SSL certificates can be associated with the same context, e.g. to - // allow both RSA and ECDSA certificates for the same SNI [V2-API-DIFF]. - repeated SslCertificate ssl_certificates = 1; - - ClientSslContext client_ssl_context = 2; - - // Supplies the list of ALPN protocols that the listener should expose. - repeated google.protobuf.StringValue alpn_protocols = 3; - - enum TLSProtocol { - TLS_AUTO = 0; - TLSv1_0 = 1; - TLSv1_1 = 2; - TLSv1_2 = 3; - TLSv1_3 = 4; - } - // Allowed TLS protocols. - TLSProtocol tls_minimum_protocol_version = 4; - TLSProtocol tls_maximum_protocol_version = 5; - - // If specified, the TLS listener will only support the specified cipher list. - repeated google.protobuf.StringValue cipher_suites = 6; - - // If specified, the TLS connection will only support the specified ECDH - // curves. If not specified, the default curves (X25519, P-256) will be used. - repeated google.protobuf.StringValue ecdh_curves = 7; -} - message Filter { // The type of filter to instantiate. Most filters implement a specific type, // though it is theoretically possible for a filter to be written such that it @@ -149,11 +64,11 @@ message FilterChainMatch { google.protobuf.UInt32Value suffix_len = 5; } -// Grouping of FilterChainMatch criteria, SslContext, the actual filter chain +// Grouping of FilterChainMatch criteria, DownstreamSslContext, the actual filter chain // and related parameters. message FilterChain { FilterChainMatch filter_chain_match = 1; - SslContext ssl_context = 2; + DownstreamSslContext ssl_context = 2; // A list of individual network filters that make up the filter chain for // connections established with the listener. Order matters as the filters are // processed sequentially as connection events happen. Note: If the filter @@ -171,7 +86,7 @@ message FilterChain { message Listener { // The address that the listener should listen on. - ListenerAddress address = 1; + Address address = 1; // A list of filter chains to consider for this listener. The FilterChain with // the most specific FilterChainMatch criteria is used on a connection. The diff --git a/api/rds.proto b/api/rds.proto index 6e99d274..9917e214 100644 --- a/api/rds.proto +++ b/api/rds.proto @@ -4,7 +4,7 @@ syntax = "proto3"; -import "api/node.proto"; +import "api/base.proto"; import "google/protobuf/struct.proto"; import "google/protobuf/wrappers.proto"; diff --git a/api/ssl_context.proto b/api/ssl_context.proto new file mode 100644 index 00000000..5e73190c --- /dev/null +++ b/api/ssl_context.proto @@ -0,0 +1,95 @@ +syntax = "proto3"; + +import "google/protobuf/wrappers.proto"; + +message DataSource { + oneof specifier { + google.protobuf.StringValue filename = 1; + google.protobuf.BytesValue inline = 2; + } +} + +message TlsParameters { + enum TlsProtocol { + TLS_AUTO = 0; + TLSv1_0 = 1; + TLSv1_1 = 2; + TLSv1_2 = 3; + TLSv1_3 = 4; + } + // Allowed TLS protocols. + TlsProtocol tls_minimum_protocol_version = 1; + TlsProtocol tls_maximum_protocol_version = 2; + + // If specified, the TLS listener will only support the specified cipher list. + repeated google.protobuf.StringValue cipher_suites = 3; + + // If specified, the TLS connection will only support the specified ECDH + // curves. If not specified, the default curves (X25519, P-256) will be used. + repeated google.protobuf.StringValue ecdh_curves = 4; +} + +// SSL certs can be loaded from file or delivered inline [V2-API-DIFF]. Individual fields may +// be loaded from either. +message SslCertificate { + DataSource cert_chain = 1; + DataSource private_key = 2; + DataSource ocsp_staple = 3; + repeated DataSource signed_certificate_timestamp = 4; +} + +message CertificateValidationContext { + // SSL certificate data containing certificate authority certificates to use + // in verifying a presented certificate. If not specified and a certificate is + // presented it will not be verified. + DataSource ca_cert = 1; + + // If specified, Envoy will verify (pin) the hash of the presented + // certificate. + repeated google.protobuf.StringValue verify_certificate_hash = 2; + + // An optional list of subject alt names. If specified, Envoy will verify that + // the certificate’s subject alt name matches one of the specified values. + repeated google.protobuf.StringValue verify_subject_alt_name = 3; + + // Must present a signed time-stamped OCSP response. + google.protobuf.BoolValue require_ocsp_staple = 4; + + // Must present signed certificate time-stamp. + google.protobuf.BoolValue require_signed_certificate_timestamp = 5; +} + +message UpstreamSslContext { + // Client certificate to present to backend. + SslCertificate client_certificate = 1; + + // SNI string to use when creating TLS backend connections. + google.protobuf.StringValue sni = 2; + + // Protocols to negotiate over ALPN + repeated google.protobuf.StringValue alpn_protocols = 3; + + // How to validate the backend certificate. + CertificateValidationContext server_validation_context = 4; + + // TLS protocol versions, cipher suites etc. + TlsParameters tls_params = 5; +} + +// [V2-API-DIFF] This has been reworked to support alternative modes of +// certificate/key delivery, for consistency with the upstream SSL context and +// to segregate the client/server aspects of the SSL context. +message DownstreamSslContext { + // Multiple SSL certificates can be associated with the same context, e.g. to + // allow both RSA and ECDSA certificates for the same SNI [V2-API-DIFF]. + repeated SslCertificate ssl_certificates = 1; + + // Supplies the list of ALPN protocols that the listener should expose. + repeated google.protobuf.StringValue alpn_protocols = 2; + + // How to validate the client certificate. + CertificateValidationContext client_validation_context = 3; + + // TLS protocol versions, cipher suites etc. + TlsParameters tls_params = 4; +}