Package io.envoyproxy.envoy.extensions.load_balancing_policies.subset.v3

Interface SubsetOrBuilder

  • All Superinterfaces:
    com.google.protobuf.MessageLiteOrBuilder, com.google.protobuf.MessageOrBuilder
    All Known Implementing Classes:
    Subset, Subset.Builder
    public interface SubsetOrBuilder
extends com.google.protobuf.MessageOrBuilder

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean getAllowRedundantKeys()
      By default, only when the request metadata has exactly the **same** keys as one of subset selectors and the values of the related keys are matched, the load balancer will have a valid subset for the request.
      com.google.protobuf.Struct getDefaultSubset()
      Specifies the default subset of endpoints used during fallback if fallback_policy is :ref:`DEFAULT_SUBSET<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.DEFAULT_SUBSET>`.
      com.google.protobuf.StructOrBuilder getDefaultSubsetOrBuilder()
      Specifies the default subset of endpoints used during fallback if fallback_policy is :ref:`DEFAULT_SUBSET<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.DEFAULT_SUBSET>`.
      Subset.LbSubsetFallbackPolicy getFallbackPolicy()
      The behavior used when no endpoint subset matches the selected route's metadata.
      int getFallbackPolicyValue()
      The behavior used when no endpoint subset matches the selected route's metadata.
      boolean getListAsAny()
      If true, metadata specified for a metadata key will be matched against the corresponding endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value and any of the elements in the list matches the criteria.
      boolean getLocalityWeightAware()
      If true, routing to subsets will take into account the localities and locality weights of the endpoints when making the routing decision.
      Subset.LbSubsetMetadataFallbackPolicy getMetadataFallbackPolicy()
      Fallback mechanism that allows to try different route metadata until a host is found.
      int getMetadataFallbackPolicyValue()
      Fallback mechanism that allows to try different route metadata until a host is found.
      boolean getPanicModeAny()
      If true, when a fallback policy is configured and its corresponding subset fails to find a host this will cause any host to be selected instead.
      boolean getScaleLocalityWeight()
      When used with locality_weight_aware, scales the weight of each locality by the ratio of hosts in the subset vs hosts in the original subset.
      LoadBalancingPolicy getSubsetLbPolicy()
      The child LB policy to create for endpoint-picking within the chosen subset.
      LoadBalancingPolicyOrBuilder getSubsetLbPolicyOrBuilder()
      The child LB policy to create for endpoint-picking within the chosen subset.
      Subset.LbSubsetSelector getSubsetSelectors​(int index)
      For each entry, LbEndpoint.Metadata's ``envoy.lb`` namespace is traversed and a subset is created for each unique combination of key and value.
      int getSubsetSelectorsCount()
      For each entry, LbEndpoint.Metadata's ``envoy.lb`` namespace is traversed and a subset is created for each unique combination of key and value.
      List<Subset.LbSubsetSelector> getSubsetSelectorsList()
      For each entry, LbEndpoint.Metadata's ``envoy.lb`` namespace is traversed and a subset is created for each unique combination of key and value.
      Subset.LbSubsetSelectorOrBuilder getSubsetSelectorsOrBuilder​(int index)
      For each entry, LbEndpoint.Metadata's ``envoy.lb`` namespace is traversed and a subset is created for each unique combination of key and value.
      List<? extends Subset.LbSubsetSelectorOrBuilder> getSubsetSelectorsOrBuilderList()
      For each entry, LbEndpoint.Metadata's ``envoy.lb`` namespace is traversed and a subset is created for each unique combination of key and value.
      boolean hasDefaultSubset()
      Specifies the default subset of endpoints used during fallback if fallback_policy is :ref:`DEFAULT_SUBSET<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.DEFAULT_SUBSET>`.
      boolean hasSubsetLbPolicy()
      The child LB policy to create for endpoint-picking within the chosen subset.

      • Methods inherited from interface com.google.protobuf.MessageLiteOrBuilder

        isInitialized

      • Methods inherited from interface com.google.protobuf.MessageOrBuilder

        findInitializationErrors, getAllFields, getDefaultInstanceForType, getDescriptorForType, getField, getInitializationErrorString, getOneofFieldDescriptor, getRepeatedField, getRepeatedFieldCount, getUnknownFields, hasField, hasOneof

    • Method Detail

      • getFallbackPolicyValue

        int getFallbackPolicyValue()
         The behavior used when no endpoint subset matches the selected route's
 metadata. The value defaults to
 :ref:`NO_FALLBACK<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.NO_FALLBACK>`.
        .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy fallback_policy = 1 [(.validate.rules) = { ... }
        Returns:
        The enum numeric value on the wire for fallbackPolicy.

      • getFallbackPolicy

        Subset.LbSubsetFallbackPolicy getFallbackPolicy()
         The behavior used when no endpoint subset matches the selected route's
 metadata. The value defaults to
 :ref:`NO_FALLBACK<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.NO_FALLBACK>`.
        .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy fallback_policy = 1 [(.validate.rules) = { ... }
        Returns:
        The fallbackPolicy.

      • hasDefaultSubset

        boolean hasDefaultSubset()
         Specifies the default subset of endpoints used during fallback if
 fallback_policy is
 :ref:`DEFAULT_SUBSET<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.DEFAULT_SUBSET>`.
 Each field in default_subset is
 compared to the matching LbEndpoint.Metadata under the ``envoy.lb``
 namespace. It is valid for no hosts to match, in which case the behavior
 is the same as a fallback_policy of
 :ref:`NO_FALLBACK<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.NO_FALLBACK>`.
        .google.protobuf.Struct default_subset = 2;
        Returns:
        Whether the defaultSubset field is set.

      • getDefaultSubset

        com.google.protobuf.Struct getDefaultSubset()
         Specifies the default subset of endpoints used during fallback if
 fallback_policy is
 :ref:`DEFAULT_SUBSET<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.DEFAULT_SUBSET>`.
 Each field in default_subset is
 compared to the matching LbEndpoint.Metadata under the ``envoy.lb``
 namespace. It is valid for no hosts to match, in which case the behavior
 is the same as a fallback_policy of
 :ref:`NO_FALLBACK<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.NO_FALLBACK>`.
        .google.protobuf.Struct default_subset = 2;
        Returns:
        The defaultSubset.

      • getDefaultSubsetOrBuilder

        com.google.protobuf.StructOrBuilder getDefaultSubsetOrBuilder()
         Specifies the default subset of endpoints used during fallback if
 fallback_policy is
 :ref:`DEFAULT_SUBSET<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.DEFAULT_SUBSET>`.
 Each field in default_subset is
 compared to the matching LbEndpoint.Metadata under the ``envoy.lb``
 namespace. It is valid for no hosts to match, in which case the behavior
 is the same as a fallback_policy of
 :ref:`NO_FALLBACK<envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.Subset.LbSubsetFallbackPolicy.NO_FALLBACK>`.
        .google.protobuf.Struct default_subset = 2;

      • getSubsetSelectorsList

        List<Subset.LbSubsetSelector> getSubsetSelectorsList()
         For each entry, LbEndpoint.Metadata's
 ``envoy.lb`` namespace is traversed and a subset is created for each unique
 combination of key and value. For example:
 .. code-block:: json
   { "subset_selectors": [
       { "keys": [ "version" ] },
       { "keys": [ "stage", "hardware_type" ] }
   ]}
 A subset is matched when the metadata from the selected route and
 weighted cluster contains the same keys and values as the subset's
 metadata. The same host may appear in multiple subsets.
        repeated .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetSelector subset_selectors = 3;

      • getSubsetSelectors

        Subset.LbSubsetSelector getSubsetSelectors​(int index)
         For each entry, LbEndpoint.Metadata's
 ``envoy.lb`` namespace is traversed and a subset is created for each unique
 combination of key and value. For example:
 .. code-block:: json
   { "subset_selectors": [
       { "keys": [ "version" ] },
       { "keys": [ "stage", "hardware_type" ] }
   ]}
 A subset is matched when the metadata from the selected route and
 weighted cluster contains the same keys and values as the subset's
 metadata. The same host may appear in multiple subsets.
        repeated .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetSelector subset_selectors = 3;

      • getSubsetSelectorsCount

        int getSubsetSelectorsCount()
         For each entry, LbEndpoint.Metadata's
 ``envoy.lb`` namespace is traversed and a subset is created for each unique
 combination of key and value. For example:
 .. code-block:: json
   { "subset_selectors": [
       { "keys": [ "version" ] },
       { "keys": [ "stage", "hardware_type" ] }
   ]}
 A subset is matched when the metadata from the selected route and
 weighted cluster contains the same keys and values as the subset's
 metadata. The same host may appear in multiple subsets.
        repeated .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetSelector subset_selectors = 3;

      • getSubsetSelectorsOrBuilderList

        List<? extends Subset.LbSubsetSelectorOrBuilder> getSubsetSelectorsOrBuilderList()
         For each entry, LbEndpoint.Metadata's
 ``envoy.lb`` namespace is traversed and a subset is created for each unique
 combination of key and value. For example:
 .. code-block:: json
   { "subset_selectors": [
       { "keys": [ "version" ] },
       { "keys": [ "stage", "hardware_type" ] }
   ]}
 A subset is matched when the metadata from the selected route and
 weighted cluster contains the same keys and values as the subset's
 metadata. The same host may appear in multiple subsets.
        repeated .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetSelector subset_selectors = 3;

      • getSubsetSelectorsOrBuilder

        Subset.LbSubsetSelectorOrBuilder getSubsetSelectorsOrBuilder​(int index)
         For each entry, LbEndpoint.Metadata's
 ``envoy.lb`` namespace is traversed and a subset is created for each unique
 combination of key and value. For example:
 .. code-block:: json
   { "subset_selectors": [
       { "keys": [ "version" ] },
       { "keys": [ "stage", "hardware_type" ] }
   ]}
 A subset is matched when the metadata from the selected route and
 weighted cluster contains the same keys and values as the subset's
 metadata. The same host may appear in multiple subsets.
        repeated .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetSelector subset_selectors = 3;

      • getAllowRedundantKeys

        boolean getAllowRedundantKeys()
         By default, only when the request metadata has exactly the **same** keys as one of subset selectors and
 the values of the related keys are matched, the load balancer will have a valid subset for the request.
 For example, given the following subset selectors:
 .. code-block:: json
   { "subset_selectors": [
       { "keys": [ "version" ] },
       { "keys": [ "stage", "version" ] }
   ]}
 A request with metadata ``{"redundant-key": "redundant-value", "stage": "prod", "version": "v1"}`` or
 ``{"redundant-key": "redundant-value", "version": "v1"}`` will not have a valid subset even if the values
 of keys ``stage`` and ``version`` are matched because of the redundant key/value pair in the request
 metadata.
 By setting this field to true, the most appropriate keys will be filtered out from the request metadata
 according to the subset selectors. And then the filtered keys and related values will be matched to find
 the valid host subset. By this way, redundant key/value pairs are allowed in the request metadata. The keys
 of a request metadata could be superset of the keys of the subset selectors and need not to be exactly the
 same as the keys of the subset selectors.
 More specifically, if the keys of a request metadata is a superset of one of the subset selectors, then only
 the values of the keys that in the selector keys will be matched. Take the above example, if the request
 metadata is ``{"redundant-key": "redundant-value", "stage": "prod", "version": "v1"}``, the load balancer
 will only match the values of ``stage`` and ``version`` to find an appropriate subset because ``stage``
 ``version`` are contained by the second subset selector and the redundant ``redundant-key`` will be
 ignored.
 .. note::
   If the keys of request metadata is superset of multiple different subset selectors keys, the subset
   selector with most keys to win. For example, given subset selectors
   ``{"subset_selectors": ["keys": ["A", "B", "C"], ["A", "B"]]}`` and request metadata ``{"A": "-",
   "B": "-", "C": "-", "D": "-"}``, keys ``A``, ``B``, ``C`` will be evaluated.
   If the keys of request metadata is superset of multiple different subset selectors keys and the number
   of selector keys are same, then the one placed in front to win. For example, given subset selectors
   ``{"subset_selectors": ["keys": ["A", "B"], ["C", "D"]]}`` and request metadata ``{"A": "-", "B": "-",
   "C": "-", "D": "-"}``, keys ``A``, ``B`` will be evaluated.
        bool allow_redundant_keys = 10;
        Returns:
        The allowRedundantKeys.

      • getLocalityWeightAware

        boolean getLocalityWeightAware()
         If true, routing to subsets will take into account the localities and locality weights of the
 endpoints when making the routing decision.
 There are some potential pitfalls associated with enabling this feature, as the resulting
 traffic split after applying both a subset match and locality weights might be undesirable.
 Consider for example a situation in which you have 50/50 split across two localities X/Y
 which have 100 hosts each without subsetting. If the subset LB results in X having only 1
 host selected but Y having 100, then a lot more load is being dumped on the single host in X
 than originally anticipated in the load balancing assignment delivered via EDS.
        bool locality_weight_aware = 4;
        Returns:
        The localityWeightAware.

      • getScaleLocalityWeight

        boolean getScaleLocalityWeight()
         When used with locality_weight_aware, scales the weight of each locality by the ratio
 of hosts in the subset vs hosts in the original subset. This aims to even out the load
 going to an individual locality if said locality is disproportionately affected by the
 subset predicate.
        bool scale_locality_weight = 5;
        Returns:
        The scaleLocalityWeight.

      • getPanicModeAny

        boolean getPanicModeAny()
         If true, when a fallback policy is configured and its corresponding subset fails to find
 a host this will cause any host to be selected instead.
 This is useful when using the default subset as the fallback policy, given the default
 subset might become empty. With this option enabled, if that happens the LB will attempt
 to select a host from the entire cluster.
        bool panic_mode_any = 6;
        Returns:
        The panicModeAny.

      • getListAsAny

        boolean getListAsAny()
         If true, metadata specified for a metadata key will be matched against the corresponding
 endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value
 and any of the elements in the list matches the criteria.
        bool list_as_any = 7;
        Returns:
        The listAsAny.

      • getMetadataFallbackPolicyValue

        int getMetadataFallbackPolicyValue()
         Fallback mechanism that allows to try different route metadata until a host is found.
 If load balancing process, including all its mechanisms (like
 :ref:`fallback_policy<envoy_v3_api_field_extensions.load_balancing_policies.subset.v3.subset.fallback_policy>`)
 fails to select a host, this policy decides if and how the process is repeated using another metadata.
 The value defaults to
 :ref:`METADATA_NO_FALLBACK
 <envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.subset.LbSubsetMetadataFallbackPolicy.METADATA_NO_FALLBACK>`.
        .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetMetadataFallbackPolicy metadata_fallback_policy = 8 [(.validate.rules) = { ... }
        Returns:
        The enum numeric value on the wire for metadataFallbackPolicy.

      • getMetadataFallbackPolicy

        Subset.LbSubsetMetadataFallbackPolicy getMetadataFallbackPolicy()
         Fallback mechanism that allows to try different route metadata until a host is found.
 If load balancing process, including all its mechanisms (like
 :ref:`fallback_policy<envoy_v3_api_field_extensions.load_balancing_policies.subset.v3.subset.fallback_policy>`)
 fails to select a host, this policy decides if and how the process is repeated using another metadata.
 The value defaults to
 :ref:`METADATA_NO_FALLBACK
 <envoy_v3_api_enum_value_extensions.load_balancing_policies.subset.v3.subset.LbSubsetMetadataFallbackPolicy.METADATA_NO_FALLBACK>`.
        .envoy.extensions.load_balancing_policies.subset.v3.Subset.LbSubsetMetadataFallbackPolicy metadata_fallback_policy = 8 [(.validate.rules) = { ... }
        Returns:
        The metadataFallbackPolicy.

      • hasSubsetLbPolicy

        boolean hasSubsetLbPolicy()
         The child LB policy to create for endpoint-picking within the chosen subset.
        .envoy.config.cluster.v3.LoadBalancingPolicy subset_lb_policy = 9 [(.validate.rules) = { ... }
        Returns:
        Whether the subsetLbPolicy field is set.

      • getSubsetLbPolicy

        LoadBalancingPolicy getSubsetLbPolicy()
         The child LB policy to create for endpoint-picking within the chosen subset.
        .envoy.config.cluster.v3.LoadBalancingPolicy subset_lb_policy = 9 [(.validate.rules) = { ... }
        Returns:
        The subsetLbPolicy.

      • getSubsetLbPolicyOrBuilder

        LoadBalancingPolicyOrBuilder getSubsetLbPolicyOrBuilder()
         The child LB policy to create for endpoint-picking within the chosen subset.
        .envoy.config.cluster.v3.LoadBalancingPolicy subset_lb_policy = 9 [(.validate.rules) = { ... }