New Hap Rule Doc

docs/contributor/03-11-hap-rules.md

@@ -0,0 +1,210 @@
+# HAP Rule Configuration
+
+> [!NOTE]
+> This feature is still being developed and will be available soon.
+
+ The Hyperscaler Account Pool (HAP) Rule Configuration is a functionality that allows to control pool selection from a configurable helm property. 
+ The HAP pool is a set of Gardener's SecretBindings K8S resources that share the same labels. 
+ The HAP Pool Selection is a process that for every skr creation request decides on which secret binding is the most suitable to use. 
+ The process generates a list of search labels based on skr's physical and or logical (calculated) attributes.
+ The search labels are used to query Gardener's Secret Bindings. 
+ Search labels are generated by evaluating a Rule consisting of Rule Entries and if an Entry applies to the request then the Rule outputs its specific search labels to query the correct HAP Pool.
+ More about HAP process can be found in [Hyperscaler Account Pool](03-10-hyperscaler-account-pool.md) document.
+
+![Rules Evaluation Process](../assets/hap-rules-general.drawio.svg)
+
+## Rule Configuration
+
+The Rule is configured in values.yaml in `hap.rule` property.
+It is is a list of strings, each of which is a single Rule Entry that corresponds to a single HAP Pool. 
+Each Rule Entry is evaluated during a cluster provisioning process.
+If more than one rule applies the best matching rule is selected based on the rule [priority](#priority). The following examples presents the Rule Configuration in values.yaml:
+
+```
+hap: 
+  rule: 
+  - rule_1
+  - rule_2
+  ...
+  - rule_n
+```
+
+Every HAP Pool that the Rule Entry represents must be preconfigured in a Gardener Cluster that KEB connects to.
+
+## Rule Format 
+
+The following example shows the Rule Entry format:
+
+```
+PLAN(ATTR_1=VAL_1,ATTR_2=VAL_2,...,ATTR_N)->RESULT_1, RESULT_2, ..., RESULT_N
+```
+
+In its minimal form each rule consists of a `PLAN` that the rule applies to.
+The rule can be extended with a list of attributes and its values passed in the form of `ATTR=VAL` pairs.
+Description of when the rule is triggered can be found in the [Rule Evaluation](#evaluation) section.
+List of possible attributes is described in the [Rule Attributes](#rule-attributes) section.
+
+```
+hap: 
+  rule: 
+  - azure(ATTR_1=VAL_1,ATTR_2=VAL_2,...,ATTR_N)->RESULT_1, RESULT_2, ..., RESULT_N
+```
+
+The extended version of a rule entry allows to pass a list of attribute/value pairs in parantheses. The attributes include **platformRegion** (`PR`), **clusterRegion** (`CR`), **shared** (`S`) and **euAccess** (`E`). Each attribute can be used at most once in a single rule entry.
+shared and euAccess attributes are logical which means that they are not matched with SKR attributes but are used only to apply their labels modifications if rest of matched attributes are equal to SKR's values. 
+
+Rule Attributes include `PR`, `CR`. They are described in [Rule Attributes](#rule-attributes) section.
+
+Rule Entry results include `S` and `E`. They are described in [Rule Results](#rule-results) section.
+
+
+## Rule Evaluation
+
+HAP evaluates a set of rules to determine what labels to use when querying secret bindings.
+Rule is evaluated during cluster provisioning.
+Rule entries are analyzed one by one.
+Physical attributes from every entry are compared with values from input, if they are the same the rule entry is considered triggered.
+If there is more than one triggered rule then only one is selected in accordance to priority rules described in the [Priority](#priority) section.
+If there are no rule entries trigered then the error is returned. No fallback behaviour is defined in such case.
+
+## Priority
+
+Only one rule can be triggered. If more than one rule entry match the request than only one is selected by sorting them by the number of attributes they contain.
+The entry that specifies most attributes (hence is more specific) is selected.
+If there are more than one rule with the same number of attributes then an error is returned.
+
+## Search Labels
+
+The HAP stores credentials for the hyperscaler accounts that have been set up in advance in Kubernetes Secrets that the Secret Bindings, that KEB searches for, point to. The SecretBindings are labeld with **hyperscalerType**, **shared** and **euAccess** labels. 
+
+The **hyperscaler-type** contains hyperscaler name and region information in the format `hyperscaler_type: <HYPERSCALER_NAME>[_<PLATFORM_REGION>][_<HYPERSCALER_REGION>]`, where both `_<PLATFORM_REGION>` and `_<HYPERSCALER_REGION>` are optional. The **hypercaler-type** label is mandatory. It is value is hardcoded and computed based on a plan in [hyperscaler_type.go](https://github.com/kyma-project/kyma-environment-broker/blob/main/common/hyperscaler/hyperscaler_type.go). This means that not all plans share their name with hyperscaler types, e.g. sap-converged-plan has `openstack` plan and `trial` plan can have either `azure` or `aws` trial depending on the cluster regions. The **euAccess** and **shared** labels contain boolean values and they used to divide existing pools to secrets used by EU restricted regions and secrets shared by multiple Global Accounts. The **euAccess** and **shared** labels are optional
+
+Every rule must contain at least a plan and apply `hyperscaler_type: <HYPERSCALER_NAME>` label. For example, the following example shows a simple rule entry configuration and a SecretBinding pool that this configuration corresponds to:
+
+```
+hap:
+  rule:
+    - gcp
+
+SecretBinding pools:
+- hyperscalerType: gcp
+```
+
+Rest of the examples in the document follow the same structure of presenting an example configuration and corresponding HAP pools as above snippet.
+
+## Rule Attributes
+
+Triggered rule entry applies that labels to the SecretBinding search query.
+Rule entry attributes and its plan alter the search query by adding new or modifing existing search labels. Existence of an attribute in the rule means its inclusion in the search labels in addition to labels associated with rule plan.
+
+### PR Attribute
+
+It is possible to extend the rule entry with specified platform region by adding  a `PR` rule attribute. The value of PR attributes is compared to region of a subaccount of SKR and, if triggered, applies `hyperscalerType: <HYPERSCALER_NAME>[_<PLATFORM_REGION>]` label.
+
+Below configuration means that if a gcp cluster is provisioned in cf-sa30 subaccount region then KEB would search for secret bindings with `hyperscalerType: gcp_cf-sa30` label. 
+
+```
+hap: 
+  rule: 
+    - gcp(PR=cf-sa30)
+
+SecretBinding pools
+- hyperscalerType: gcp_cf-sa30, 
+```
+
+### Cluster Region Attribute
+
+A region that an SKR is provisioned in can be matched with an attribute named `CR`. Below configuration specifies azure plan as one for which to use cluster region based search. In this case, cluster provisioned in with the azure plan would require a secret binding with `hyperscalerType: azure_<CLUSTER_REGION>` label. 
+
+```
+hap: 
+  rule: 
+    - gcp(CR=us-central1)
+
+SecretBinding pools
+- hyperscalerType: gcp_us-central1, 
+```
+
+### Shared & EU Access attribute
+
+The `shared` and `euAccess` attributes does not correspond to any physical SKR property. It is a logical attribute that is used only to add its label. If the rule entry contains `shared` or `euAccess` attributes then when triggered a `shared: true` or `euAccess: true` labels are added to the search labels depending on which one of those two attributes is listed in the rule entry. Shared label on a SecretBindings marked it as assignable to more than one SKR and euAccess is a non-functional label not reused by KEB (more on that can be found in p[HAP Pool document](03-10-hyperscaler-account-pool.md)). Below configuration specifies that all gcp clusters will use the same pool of shared secret bindings marked with labels `hyperscalerType: gcp`, `shared: true` and azure clusters in the region cf-ch20 will use the pool of secret bindings marked with labels `hyperscalerType: azure`, `euAccess: true`. 
+
+```
+hap: 
+  rule: 
+    - gcp -> S
+    - azure(PR=cf-ch20) -> E
+
+SecretBinding pools:
+- hyperscalerType: gcp; shared: true
+- hyperscalerType: azure_cf-ch20, euAccess: true
+```
+
+### Attribute with "*"
+
+Attributes values can be replaced with `*` which means that all SKR values of that attribute are matched and reused in unchanged form when applying search labels modifications. For example, the following configuration makes KEB search SecretBindings with `hyperscalerType: gcp_<PR>`, where `PR` corresponds to an SKR value, for all `gcp` clusters:
+
+```
+hap: 
+  rule: 
+  - gcp(PR=*)
+```
+
+```
+SecretBinding pools:
+- hyperscalerType: gcp_cf-sa30
+- hyperscalerType: gcp_cf-jp30
+```
+
+The attributes that support `*` include: `PR`, `CR`.
+
+> ![NOTE]
+> The above configuration example effectivle disables usage of SecretBindings with only `hyperscalerType: gcp` label.
+
+
+## Validation
+
+KEB validates HAP Rules during startup. If the configuration is invalid, KEB will not start and an error message will be displayed in the logs. 
+
+The constraints used for validation during KEB startup include:
+* Rules format check - all the rules must comply with the format specified above.
+* Every rule Entry must refer to an existing plan - if you define a rule with non existing pools then an error is returned if a during KEB startup
+* Every Rule Entry must refer to an existing pool.
+
+## Initial Configuration
+
+The last example shows initial configuration create to mimic the current bahaviour of KEB at the time of writing the document. The configuration enforces that:
+* azure, aws, gcp have their own pools of dedicated bindings.
+* gcp clusters in the region cf-sa30 use the pool of secret bindings marked with labels: `hyperscalerType: gcp_cf-sa30`,
+* sap-converged-cloud clusters use the pool of secret bindings marked with labels: `hyperscalerType: openstack_<CLUSTER_REGION>` and all of the are shared.
+* trial clusters can use one of two pool of shared secret bindings marked with labels: `hyperscalerType: azure` or `hyperscalerType: aws` (because of hardcoded mapping of trial plan to azure or aws providers) depending on the provider type.
+* azure clusters in the region cf-ch20 and aws clusters in the region cf-eu11 have their own dedicated pool.
+
+```
+hap:
+ rule: 
+  - aws
+  - aws(PR=cf-eu11) -> EU
+  - azure
+  - azure(EU,PR=cf-ch20) -> EU
+  - gcp
+  - gcp(PR=cf-sa30)
+  - trial -> S
+  - sap-converged-cloud(CR=*) -> S
+
+?
+  - "azure_lite"
+  - "preview"
+?
+
+SecretBinding pools:
+- hyperscalerType: aws, 
+- hyperscalerType: aws_cf-eu11; euAccess: true 
+- hyperscalerType: azure, 
+- hyperscalerType: azure_cf-ch20; euAccess: true 
+- hyperscalerType: gcp, 
+- hyperscalerType: gcp_cf-sa30, 
+- hyperscalerType: azure; shared: true - TRIAL POOL
+- hyperscalerType: aws; shared: true - TRIAL POOL 
+- hyperscalerType: openstack_<CLUSTER_REGION>; shared: true, 
+```