path: root/contrib/libs/yandex-cloud-api-protos/yandex/cloud/apploadbalancer/v1/backend_group.proto

syntax = "proto3";

package yandex.cloud.apploadbalancer.v1;

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
import "yandex/cloud/apploadbalancer/v1/payload.proto";
import "yandex/cloud/apploadbalancer/v1/tls.proto";
import "yandex/cloud/validation.proto";

option go_package = "github.com/yandex-cloud/go-genproto/yandex/cloud/apploadbalancer/v1;apploadbalancer";
option java_package = "yandex.cloud.api.apploadbalancer.v1";

// A backend group resource.
// For details about the concept, see [documentation](/docs/application-load-balancer/concepts/backend-group).
message BackendGroup {
  reserved 8;
  // ID of the backend group. Generated at creation time.
  string id = 1;

  // Name of the backend group. The name is unique within the folder. The string length in characters is 3-63.
  string name = 2;

  // Description of the backend group. The string is 0-256 characters long.
  string description = 3;

  // ID of the folder that the backend group belongs to.
  string folder_id = 4;

  // Backend group labels as `key:value` pairs.
  // For details about the concept, see [documentation](/docs/overview/concepts/services#labels).
  // The maximum number of labels is 64.
  map<string, string> labels = 5;

  // Backends that the backend group consists of.
  oneof backend {
    // List of HTTP backends that the backend group consists of.
    HttpBackendGroup http = 6;

    // List of gRPC backends that the backend group consists of.
    GrpcBackendGroup grpc = 7;

    // List of stream (TCP) backends that the backend group consists of.
    StreamBackendGroup stream = 10;
  }

  // Creation timestamp.
  google.protobuf.Timestamp created_at = 9;
}

// A stream (TCP) backend group resource.
message StreamBackendGroup {
  // List of stream (TCP) backends.
  repeated StreamBackend backends = 1;

  // Session affinity configuration for the backend group.
  //
  // For details about the concept, see
  // [documentation](/docs/application-load-balancer/concepts/backend-group#session-affinity).
  //
  // If session affinity is configured, the backend group should contain exactly one active backend (i.e. with positive
  // [HttpBackend.backend_weight]), its [HttpBackend.backend_type] should be [TargetGroupsBackend], and its
  // [LoadBalancingConfig.load_balancing_mode] should be `MAGLEV_HASH`. If any of these conditions are not met, session
  // affinity will not work.
  oneof session_affinity {
    // Connection-based session affinity configuration.
    //
    // For now, a connection is defined only by an IP address of the client.
    ConnectionSessionAffinity connection = 2;
  }
}

// An HTTP backend group resource.
message HttpBackendGroup {
  // List of HTTP backends.
  repeated HttpBackend backends = 1;

  // Session affinity configuration for the backend group.
  //
  // For details about the concept, see
  // [documentation](/docs/application-load-balancer/concepts/backend-group#session-affinity).
  //
  // If session affinity is configured, the backend group should contain exactly one active backend (i.e. with positive
  // [HttpBackend.backend_weight]), its [HttpBackend.backend_type] should be [TargetGroupsBackend], and its
  // [LoadBalancingConfig.load_balancing_mode] should be `MAGLEV_HASH`. If any of these conditions are not met, session
  // affinity will not work.
  oneof session_affinity {
    // Connection-based session affinity configuration.
    //
    // For now, a connection is defined only by an IP address of the client.
    ConnectionSessionAffinity connection = 2;

    // HTTP-header-field-based session affinity configuration.
    HeaderSessionAffinity header = 3;

    // Cookie-based session affinity configuration.
    CookieSessionAffinity cookie = 4;
  }
}

// A gRPC backend group resource.
message GrpcBackendGroup {
  // List of gRPC backends.
  repeated GrpcBackend backends = 1;

  // Session affinity configuration for the backend group.
  //
  // For details about the concept, see
  // [documentation](/docs/application-load-balancer/concepts/backend-group#session-affinity).
  //
  // If session affinity is configured, the backend group should contain exactly one active backend (i.e. with positive
  // [GrpcBackend.backend_weight]), and its [LoadBalancingConfig.load_balancing_mode] should be `MAGLEV_HASH`. If any of
  // these conditions are not met, session affinity will not work.
  oneof session_affinity {
    // Connection-based session affinity configuration.
    //
    // For now, a connection is defined only by an IP address of the client.
    ConnectionSessionAffinity connection = 2;

    // HTTP-header-field-based session affinity configuration.
    HeaderSessionAffinity header = 3;

    // Cookie-based session affinity configuration.
    CookieSessionAffinity cookie = 4;
  }
}

// A resource for HTTP-header-field-based session affinity configuration.
message HeaderSessionAffinity {
  // Name of the HTTP header field that is used for session affinity.
  string header_name = 1 [(length) = "1-256"];
}

// A resource for cookie-based session affinity configuration.
message CookieSessionAffinity {
  // Name of the cookie that is used for session affinity.
  string name = 1 [(length) = "1-256"];

  // Maximum age of cookies that are generated for sessions.
  //
  // If set to `0`, session cookies are used, which are stored by clients in temporary memory and are deleted
  // on client restarts.
  //
  // If not set, the balancer does not generate cookies and only uses incoming ones for establishing session affinity.
  google.protobuf.Duration ttl = 2;
}

// A resource for connection-based session affinity configuration.
message ConnectionSessionAffinity {
  // Specifies whether an IP address of the client is used to define a connection for session affinity.
  bool source_ip = 1;
}

// A load balancing mode resource.
// For details about the concept, see
// [documentation](/docs/application-load-balancer/concepts/backend-group#balancing-mode).
enum LoadBalancingMode {

  // Round robin load balancing mode.
  //
  // All endpoints of the backend take their turns to receive requests attributed to the backend.
  ROUND_ROBIN = 0;

  // Random load balancing mode. Default value.
  //
  // For a request attributed to the backend, an endpoint that receives it is picked at random.
  RANDOM = 1;

  // Least request load balancing mode.
  //
  // To pick an endpoint that receives a request attributed to the backend, the power of two choices algorithm is used;
  // that is, two endpoints are picked at random, and the request is sent to the one which has the fewest active
  // requests.
  LEAST_REQUEST = 2;

  // Maglev hashing load balancing mode.
  //
  // Each endpoint is hashed, and a hash table with 65537 rows is filled accordingly, so that every endpoint occupies
  // the same amount of rows. An attribute of each request is also hashed by the same function (if session affinity is
  // enabled for the backend group, the attribute to hash is specified in session affinity configuration). The row
  // with the same number as the resulting value is looked up in the table to determine the endpoint that receives
  // the request.
  //
  // If the backend group with session affinity enabled contains more than one backend with positive weight, endpoints
  // for backends with `MAGLEV_HASH` load balancing mode are picked at `RANDOM` instead.
  MAGLEV_HASH = 3;
}

// A load balancing configuration resource.
message LoadBalancingConfig {
  // Threshold for panic mode.
  //
  // If percentage of healthy backends in the group drops below threshold,
  // panic mode will be activated and traffic will be routed to all backends, regardless of their health check status.
  // This helps to avoid overloading healthy backends.
  // For details about panic mode, see [documentation](/docs/application-load-balancer/concepts/backend-group#panic-mode).
  //
  // If the value is `0`, panic mode will never be activated and traffic is routed only to healthy backends at all times.
  //
  // Default value: `0`.
  int64 panic_threshold = 1 [(value) = "0-100"];

  // Percentage of traffic that a load balancer node sends to healthy backends in its availability zone.
  // The rest is divided equally between other zones. For details about zone-aware routing, see
  // [documentation](/docs/application-load-balancer/concepts/backend-group#locality).
  //
  // If there are no healthy backends in an availability zone, all the traffic is divided between other zones.
  //
  // If [strict_locality] is `true`, the specified value is ignored.
  // A load balancer node sends all the traffic within its availability zone, regardless of backends' health.
  //
  // Default value: `0`.
  int64 locality_aware_routing_percent = 2 [(value) = "0-100"];

  // Specifies whether a load balancer node should only send traffic to backends in its availability zone,
  // regardless of their health, and ignore backends in other zones.
  //
  // If set to `true` and there are no healthy backends in the zone, the node in this zone will respond
  // to incoming traffic with errors.
  // For details about strict locality, see [documentation](/docs/application-load-balancer/concepts/backend-group#locality).
  //
  // If `strict_locality` is `true`, the value specified in [locality_aware_routing_percent] is ignored.
  //
  // Default value: `false`.
  bool strict_locality = 3;

  // Load balancing mode for the backend.
  //
  // For details about load balancing modes, see
  // [documentation](/docs/application-load-balancer/concepts/backend-group#balancing-mode).
  LoadBalancingMode mode = 4;
}

// A stream (TCP) backend resource.
message StreamBackend {
  // Name of the backend.
  string name = 1 [(pattern) = "[a-z][-a-z0-9]{1,61}[a-z0-9]"];

  // Backend weight. Traffic is distributed between backends of a backend group according to their weights.
  //
  // Weights must be set either for all backends in a group or for none of them.
  // Setting no weights is the same as setting equal non-zero weights for all backends.
  //
  // If the weight is non-positive, traffic is not sent to the backend.
  google.protobuf.Int64Value backend_weight = 2;

  // Load balancing configuration for the backend.
  LoadBalancingConfig load_balancing_config = 3;

  // Port used by all targets to receive traffic.
  int64 port = 4 [(value) = "0-65535"];

  // Reference to targets that belong to the backend.
  oneof backend_type {
    option (exactly_one) = true;

    // Target groups that belong to the backend. For details about target groups, see
    // [documentation](/docs/application-load-balancer/concepts/target-group).
    TargetGroupsBackend target_groups = 5;
  }

  // Health checks to perform on targets from target groups.
  // For details about health checking, see [documentation](/docs/application-load-balancer/concepts/backend-group#health-checks).
  //
  // If no health checks are specified, active health checking is not performed.
  repeated HealthCheck healthchecks = 6;

  // Settings for TLS connections between load balancer nodes and backend targets.
  //
  // If specified, the load balancer establishes TLS-encrypted TCP connections with targets and compares received
  // certificates with the one specified in [BackendTls.validation_context].
  // If not specified, the load balancer establishes unencrypted TCP connections with targets.
  BackendTls tls = 7;

  // If set, proxy protocol will be enabled for this backend.
  bool enable_proxy_protocol = 8;
}

// An HTTP backend resource.
message HttpBackend {
  // Name of the backend.
  string name = 1 [
    (required) = true,
    (pattern) = "[a-z][-a-z0-9]{1,61}[a-z0-9]"
  ];

  // Backend weight. Traffic is distributed between backends of a backend group according to their weights.
  //
  // Weights must be set either for all backends in a group or for none of them.
  // Setting no weights is the same as setting equal non-zero weights for all backends.
  //
  // If the weight is non-positive, traffic is not sent to the backend.
  google.protobuf.Int64Value backend_weight = 2;

  // Load balancing configuration for the backend.
  LoadBalancingConfig load_balancing_config = 3;

  // Port used by all targets to receive traffic.
  int64 port = 4 [(value) = "0-65535"];

  // Reference to targets that belong to the backend.
  //
  // A backend may be a set of target groups or an Object Storage bucket. For details about backend types, see
  // [documentation](/docs/application-load-balancer/concepts/backend-group#types).
  oneof backend_type {
    option (exactly_one) = true;

    // Target groups that belong to the backend. For details about target groups, see
    // [documentation](/docs/application-load-balancer/concepts/target-group).
    TargetGroupsBackend target_groups = 5;

    // Object Storage bucket to use as the backend. For details about buckets, see
    // [documentation](/docs/storage/concepts/bucket).
    //
    // If a bucket is used as a backend, the list of bucket objects and the objects themselves must be publicly
    // accessible. For instructions, see [documentation](/docs/storage/operations/buckets/bucket-availability).
    StorageBucketBackend storage_bucket = 9;
  }

  // Health checks to perform on targets from target groups.
  // For details about health checking, see [documentation](/docs/application-load-balancer/concepts/backend-group#health-checks).
  //
  // If no health checks are specified, active health checking is not performed.
  repeated HealthCheck healthchecks = 6;

  // Settings for TLS connections between load balancer nodes and backend targets.
  //
  // If specified, the load balancer establishes HTTPS (HTTP over TLS) connections with targets
  // and compares received certificates with the one specified in [BackendTls.validation_context].
  // If not specified, the load balancer establishes unencrypted HTTP connections with targets.
  BackendTls tls = 7;

  // Enables HTTP/2 usage in connections between load balancer nodes and backend targets.
  //
  // Default value: `false`, HTTP/1.1 is used.
  bool use_http2 = 8;
}

// A gRPC backend resource.
message GrpcBackend {
  reserved 6;
  // Name of the backend.
  string name = 1 [
    (required) = true,
    (pattern) = "[a-z][-a-z0-9]{1,61}[a-z0-9]"
  ];

  // Backend weight. Traffic is distributed between backends of a backend group according to their weights.
  //
  // Weights must be set either for all backends of a group or for none of them.
  // Setting no weights is the same as setting equal non-zero weights for all backends.
  //
  // If the weight is non-positive, traffic is not sent to the backend.
  google.protobuf.Int64Value backend_weight = 2;

  // Load balancing configuration for the backend.
  LoadBalancingConfig load_balancing_config = 3;

  // Port used by all targets to receive traffic.
  int64 port = 4 [(value) = "0-65535"];

  // Reference to targets that belong to the backend. For now, targets are referenced via target groups.
  oneof backend_type {
    option (exactly_one) = true;

    // Target groups that belong to the backend.
    TargetGroupsBackend target_groups = 5;
  }

  // Health checks to perform on targets from target groups.
  // For details about health checking, see [documentation](/docs/application-load-balancer/concepts/backend-group#health-checks).
  //
  // If no health checks are specified, active health checking is not performed.
  repeated HealthCheck healthchecks = 7;

  // Settings for TLS connections between load balancer nodes and backend targets.
  //
  // If specified, the load balancer establishes HTTPS (HTTP over TLS) connections with targets
  // and compares received certificates with the one specified in [BackendTls.validation_context].
  // If not specified, the load balancer establishes unencrypted HTTP connections with targets.
  BackendTls tls = 8;
}

// A resource for target groups that belong to the backend.
message TargetGroupsBackend {
  // List of ID's of target groups that belong to the backend.
  //
  // To get the ID's of all available target groups, make a [TargetGroupService.List] request.
  repeated string target_group_ids = 1 [(size) = ">0"];
}

// Transport settings to be used instead of the settings configured per-cluster
message PlaintextTransportSettings {}

// Transport settings to be used instead of the settings configured per-cluster
message SecureTransportSettings {
  reserved 2;
  // SNI string for TLS connections.
  string sni = 1;

  // Validation context for backend TLS connections.
  ValidationContext validation_context = 3;
}

// A resource for backend TLS settings.
message BackendTls {
  reserved 2;
  // Server Name Indication (SNI) string for TLS connections.
  string sni = 1;

  // Validation context for TLS connections.
  ValidationContext validation_context = 3;
}

// A resource for Object Storage bucket used as a backend. For details about the concept,
// see [documentation](/docs/storage/concepts/bucket).
message StorageBucketBackend {
  // Name of the bucket.
  string bucket = 1 [(required) = true];
}

// A health check resource.
// For details about the concept, see [documentation](/docs/application-load-balancer/concepts/backend-group#health-checks).
message HealthCheck {
  // Health check timeout.
  //
  // The timeout is the time allowed for the target to respond to a check.
  // If the target doesn't respond in time, the check is considered failed.
  google.protobuf.Duration timeout = 1 [(required) = true];

  // Base interval between consecutive health checks.
  google.protobuf.Duration interval = 2 [(required) = true];

  double interval_jitter_percent = 3;

  // Number of consecutive successful health checks required to mark an unhealthy target as healthy.
  //
  // Both `0` and `1` values amount to one successful check required.
  //
  // The value is ignored when a load balancer is initialized; a target is marked healthy after one successful check.
  //
  // Default value: `0`.
  int64 healthy_threshold = 4;

  // Number of consecutive failed health checks required to mark a healthy target as unhealthy.
  //
  // Both `0` and `1` values amount to one unsuccessful check required.
  //
  // The value is ignored if a health check is failed due to an HTTP `503 Service Unavailable` response from the target
  // (not applicable to TCP stream health checks). The target is immediately marked unhealthy.
  //
  // Default value: `0`.
  int64 unhealthy_threshold = 5;

  // Port used for health checks.
  //
  // If not specified, the backend port ([HttpBackend.port] or [GrpcBackend.port]) is used for health checks.
  int64 healthcheck_port = 6 [(value) = "0-65535"];

  // A resource for TCP stream health check settings.
  message StreamHealthCheck {
    // Message sent to targets during TCP data transfer.
    //
    // If not specified, no data is sent to the target.
    Payload send = 1;

    // Data that must be contained in the messages received from targets for a successful health check.
    //
    // If not specified, no messages are expected from targets, and those that are received are not checked.
    Payload receive = 2;
  }

  // A resource for HTTP health check settings.
  message HttpHealthCheck {
    // Value for the HTTP/1.1 `Host` header or the HTTP/2 `:authority` pseudo-header used in requests to targets.
    string host = 1;

    // HTTP path used in requests to targets: request URI for HTTP/1.1 request line
    // or value for the HTTP/2 `:path` pseudo-header.
    string path = 2 [(required) = true];

    // Enables HTTP/2 usage in health checks.
    //
    // Default value: `false`, HTTP/1.1 is used.
    bool use_http2 = 3;
  }

  // A resource for gRPC health check settings.
  message GrpcHealthCheck {
    // Name of the gRPC service to be checked.
    //
    // If not specified, overall health is checked.
    //
    // For details about the concept, see [GRPC Health Checking Protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
    string service_name = 1;
  }

  // Protocol-specific health check settings.
  //
  // The protocols of the backend and of its health check may differ,
  // e.g. a gRPC health check may be specified for an HTTP backend.
  oneof healthcheck {
    option (exactly_one) = true;
    // TCP stream health check settings.
    StreamHealthCheck stream = 7;
    // HTTP health check settings.
    HttpHealthCheck http = 8;
    // gRPC health check settings.
    GrpcHealthCheck grpc = 9;
  }

  // Optional transport protocol for health checks.
  // When not set, health checks use the same protocol as the proxied traffic.
  // Use this when health checks' protocol settings differ from their backend, e.g. plaintext health checks for a TLS backend.
  oneof transport_settings {
    PlaintextTransportSettings plaintext = 10;
    SecureTransportSettings tls = 11;
  }
}