Merge pull request #538 from citrix/cic-1.25-6

sreejithgs · web-flow · commit 5a076b778921 · 2022-05-25T09:38:50.000+05:30
updates for cic release 1.25-6
diff --git a/crd/appqoe/README.md b/crd/appqoe/README.md
@@ -0,0 +1,59 @@
+# Enable request retry feature using AppQoE for Citrix ingress controller
+
+When a Citrix ADC appliance receives an HTTP request and forwards it to a back-end server, sometimes there may be connection failures with the back-end server. You can configure the request-retry feature on Citrix ADC to forward the request to the next available server, instead of sending the reset to the client. Hence, the client saves round trip time when Citrix ADC initiates the same request to the next available service. For more information request retry feature, see the [Citrix ADC documentation](https://docs.citrix.com/en-us/citrix-adc/current-release/system/request-retry/request_retry_if_back-end_server_resets_tcp_connection.html)
+
+Now, you can configure request retry on Citrix ADC with Citrix ingress controller.
+Custom Resource Definitions (CRDs) are the primary way of configuring policies in cloud native deployments. Using the AppQoE CRD provided by Citrix, you can configure request-retry policies on Citrix ADC with the Citrix ingress controller. The AppQoE CRD enables communication between the Citrix ingress controller and Citrix ADC for enforcing AppQoE policies.
+
+## AppQoE CRD definition
+
+The AppQoE CRD is available in the Citrix ingress controller GitHub repo at: [appqoe-crd.yaml](https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/appqoe/appqoe-crd.yaml). The AppQoE CRD provides attributes for the various options that are required to define the AppQoE policy on Citrix ADC.
+
+The following are the attributes provided in the AppQoE CRD:
+
+| Attribute | Description |
+| --------- | ----------- |
+| `servicenames` | Specifies the list of Kubernetes services to which you want to apply the AppQoE policies.|
+| `on-reset`|  Specifies whether to set retry on connection Reset or Not|
+| `on-timeout` | Specifies the time in milliseconds for retry |
+| `number-of-retries`| Specifies the number of retries |
+| `appqoe-criteria`|Specifies the expression for evaluating traffic. |
+| `direction`| Specifies the bind point for binding the AppQoE policy. |
+
+## Deploy the AppQoE CRD
+
+Perform the following to deploy the AppQoE CRD:
+
+1.  Download the [AppQoE CRD](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/crd/appqoe/appqoe-crd.yaml).
+
+2.  Deploy the AppQoE CRD using the following command:
+
+        kubectl create -f appqoe-crd.yaml
+
+### How to write a AppQoE policy configuration
+
+After you have deployed the AppQoE CRD provided by Citrix in the Kubernetes cluster, you can define the AppQoE policy configuration in a `.yaml` file. In the `.yaml` file, use `appqoepolicy` in the kind field and in the `spec` section add the AppQoE CRD attributes based on your requirement for the policy configuration.
+
+The following YAML file applies the AppQoE policy to the services listed in the servicenames field. You must configure the AppQoE action to retry on timeout and define the number of retry attempts.
+
+```yml
+apiVersion: citrix.com/v1
+kind: appqoepolicy
+metadata:
+  name: targeturlappqoe
+spec:
+  appqoe-policies:
+    - servicenames:
+        - apache
+      appqoe-policy:
+        operation-retry:
+          onReset: 'YES'
+          onTimeout: 33
+        number-of-retries: 2
+        appqoe-criteria: 'HTTP.REQ.HEADER("User-Agent").CONTAINS("Android")'
+        direction: REQUEST
+```
+
+After you have defined the policy configuration, deploy the `.yaml` file using the following commands:
+
+   $ kubectl create -f appqoe-example.yaml
diff --git a/crd/appqoe/appqoe-crd.yaml b/crd/appqoe/appqoe-crd.yaml
@@ -0,0 +1,82 @@
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: appqoepolicies.citrix.com
+spec:
+  group: citrix.com
+  names:
+    kind: appqoepolicy 
+    plural: appqoepolicies
+    singular: appqoepolicy 
+  scope: Namespaced
+  versions: 
+  - name: v1
+    served: true
+    storage: true
+    subresources:
+      status: {}
+    additionalPrinterColumns:
+    - name: Status
+      type: string
+      description: "Current Status of the CRD"
+      jsonPath: .status.state
+    - name: Message
+      type: string
+      description: "Status Message"
+      jsonPath: .status.status_message
+    schema:
+      openAPIV3Schema:
+        type: object
+        properties:
+          status:
+            type: object
+            properties:
+              state:
+                 type: string
+              status_message:
+                 type: string
+          spec:
+            type: object
+            properties:
+              appqoe-policies:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    servicenames:
+                      description: 'Name of the services that needs to be binded to appqoe policy.'
+                      type: array
+                      items:
+                        type: string
+                        maxLength: 127
+                    appqoe-policy:
+                      type: object
+                      properties:
+                        operation-retry:
+                          type: object
+                          properties:
+                            on-reset:
+                              description: "To set Retry on Connection Reset or Not"
+                              type: string
+                              enum: ['YES','NO']
+                            on-timeout:
+                              description: "Time in milliseconds for retry"
+                              type: integer
+                              minimum: 30
+                              maximum: 2000
+                        number-of-retries:
+                          description: "To set number of retries"
+                          type: integer
+                          minimum: 1
+                          maximum: 7
+                          required: [operation-retry]
+                        appqoe-criteria:
+                          description: 'Expression against which traffic is evaluated.'
+                          type: string
+                          maxLength: 1299
+                        direction:
+                          description: 'Bind point to which to bind the policy.'
+                          type: string
+                          enum: ["REQUEST","RESPONSE"]
+                      required: [appqoe-criteria, operation-retry]
+                  required: [appqoe-policy]
diff --git a/docs/configure/config-map-coe.md b/docs/configure/config-map-coe.md
@@ -12,12 +12,13 @@ You can configure the following parameters under `NS_ANALYTICS_CONFIG` using a C
   - `samplingrate`: Specifies the OpenTracing sampling rate in percentage. The default value is 100.
 
 - `endpoint`: Specifies the IP address or DNS address of the analytics server.
-   
+
     - `server`: Set this value as the IP address or DNS address of the server.
-  
+    - `service`: Specifies the IP address or service name of the Citrix ADC observability exporter service depending on whether the service is running on a virtual machine or as a Kubernetes service.
+    If the Citrix ADC observability exporter instance is running on a virtual machine this parameter specifies the IP address. If the Citrix ADC observability exporter instance is running as a service in the Kubernetes cluster, this parameter specifies the instance as namespace/service name.
 - `timeseries`: Enables exporting time series data from Citrix ADC. You can specify the following attributes for time series configuration.
     
-    - `port`: Specifies the port number of time series end point of the analytics server. The default value is 5563.
+    - `port`: Specifies the port number of the time series end point of the analytics server. The default value is 5563.
     - `metrics`: Enables exporting metrics from Citrix ADC.
   
        - `enable`: Set this value to `true` to enable sending metrics. The default value is `false`.
@@ -31,7 +32,7 @@ You can configure the following parameters under `NS_ANALYTICS_CONFIG` using a C
 - `transactions`: Enables exporting transactions from Citrix ADC.
   
     - `enable`: Set this value to `true` to enable sending transactions. The default value is `false`.
-    - `port`: Specifies the port number of transactional endpoint of analytics server. The default value is 5557.
+    - `port`: Specifies the port number of the transactional endpoint of the analytics server. The default value is 5557.
 
 The following configurations cannot be changed while the Citrix ingress controller is running and you need to reboot the Citrix ingress controller to apply these settings.
 
@@ -41,6 +42,9 @@ The following configurations cannot be changed while the Citrix ingress controll
 
  You can change other ConfigMap settings at runtime while the Citrix ingress controller is running.
 
+**Note:**
+When the user specifies value for a service as `namespace/service name`, Citrix ingress controller derives the endpoint associated to that service and dynamically bind them to the transactional service group in Citrix tier-1 ADC . If a user specifies the value for a service as IP address, the IP address is direclty bound to the transactional service group. Citrix ingress controller is enhanced to create default web or TCP based analytics profiles and bind them to the logging virtual server. The default analytics profiles are bound to all load balancing virtual servers of applications if the Citrix ADC observability exporter is enabled in the cluster. If the user wants to change the analytics profile, they can use the `analyticsprofile` annotation.
+
 The attributes of `NS_ANALYTICS_CONFIG` should follow a well-defined schema. If any value provided does not confirm with the schema, then the entire configuration is rejected. For reference, see the schema file [ns_analytics_config_schema.yaml](#Schema-for-NSANALYTICSCONFIG).
 
 ## Creating a ConfigMap for analytics configuration
@@ -67,6 +71,7 @@ data:
       samplingrate: 100
     endpoint:
       server: '1.1.1.1'
+      service: 'default/coe-kafka'
     timeseries:
       port: 5563
       metrics:
@@ -79,6 +84,7 @@ data:
     transactions:
       enable: 'true'
       port: 5557
+    
 ```
 
 For more information on how to configure ConfigMap support on the Citrix ingress controller, [see configuring ConfigMap support for the Citrix ingress controller](https://developer-docs.citrix.com/projects/citrix-k8s-ingress-controller/en/latest/configure/config-map/#configuring-configmap-support-for-the-citrix-ingress-controller).
diff --git a/docs/configure/hashing-algorithm.md b/docs/configure/hashing-algorithm.md
@@ -0,0 +1,28 @@
+# Configuring consistent hashing algorithm using Citrix ingress controller
+
+Load balancing algorithms define the criteria that the Citrix ADC appliance uses to select the service to which to redirect each client request. Different load balancing algorithms use different criteria and consistent hashing is one the load balancing algorithms supported by Citrix ADC.
+Consistent hashing algorithms are often used to load balance when the back-end is a caching server to achieve stateless persistency.
+Consistent hashing can ensure that when a cache server is removed, only the requests cached in that specific server is rehashed and the rest of the requests are not affected. For more information on the consistent hashing algorithm, see the [Citrix ADC documentation](https://docs.citrix.com/en-us/citrix-adc/current-release/load-balancing/load-balancing-customizing-algorithms/hashing-methods.html#consistent-hashing-algorithms).
+
+You can now configure the consistent hashing algorithm on Citrix ADC using Citrix ingress controller. This configuration is enabled with in the Citrix ingress controller using a ConfigMap.
+
+## Configure hashing algorithm
+
+A new parameter `NS_LB_HASH_ALGO` is introduced in the Citrix ingress controller ConfigMap for hashing algorithm support.
+Supported environment variables for consistent hashing algorithm using ConfigMap under the `NS_LB_HASH_ALGO` parameter:
+
+-  `hashFingers`: Specifies the number of fingers to be used for the hashing algorithm. Possible values are from 1 to 1024. Increasing the number of fingers provides better distribution of traffic at the expense of extra memory.
+-  `hashAlgorithm`: Specifies the supported algorithm. Supported algorithms are `default`, `jarh`, `prac`.
+
+The following example shows a sample ConfigMap for configuring consistent hashing algorithm using Citrix ingress controller. In this example, the hashing algorithm is used as Prime Re-Shuffled Assisted CARP (PRAC) and the number of fingers to be used in PRAC is set as 50.
+
+        apiVersion: v1
+        kind: ConfigMap
+        metadata:
+        name: cic-configmap
+        labels:
+            app: citrix-ingress-controller
+        data:
+        NS_LB_HASH_ALGO: |
+            hashFingers: 50
+            hashAlgorithm: 'prac'
diff --git a/docs/crds/appqoe.md b/docs/crds/appqoe.md
@@ -0,0 +1,59 @@
+# Enable request retry feature using AppQoE for Citrix ingress controller
+
+When a Citrix ADC appliance receives an HTTP request and forwards it to a back-end server, sometimes there may be connection failures with the back-end server. You can configure the request-retry feature on Citrix ADC to forward the request to the next available server, instead of sending the reset to the client. Hence, the client saves round trip time when Citrix ADC initiates the same request to the next available service. For more information request retry feature, see the [Citrix ADC documentation](https://docs.citrix.com/en-us/citrix-adc/current-release/system/request-retry/request_retry_if_back-end_server_resets_tcp_connection.html)
+
+Now, you can configure request retry on Citrix ADC with Citrix ingress controller.
+Custom Resource Definitions (CRDs) are the primary way of configuring policies in cloud native deployments. Using the AppQoE CRD provided by Citrix, you can configure request-retry policies on Citrix ADC with the Citrix ingress controller. The AppQoE CRD enables communication between the Citrix ingress controller and Citrix ADC for enforcing AppQoE policies.
+
+## AppQoE CRD definition
+
+The AppQoE CRD is available in the Citrix ingress controller GitHub repo at: [appqoe-crd.yaml](https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/appqoe/appqoe-crd.yaml). The AppQoE CRD provides attributes for the various options that are required to define the AppQoE policy on Citrix ADC.
+
+The following are the attributes provided in the AppQoE CRD:
+
+| Attribute | Description |
+| --------- | ----------- |
+| `servicenames` | Specifies the list of Kubernetes services to which you want to apply the AppQoE policies.|
+| `on-reset`|  Specifies whether to set retry on connection Reset or Not|
+| `on-timeout` | Specifies the time in milliseconds for retry |
+| `number-of-retries`| Specifies the number of retries |
+| `appqoe-criteria`|Specifies the expression for evaluating traffic. |
+| `direction`| Specifies the bind point for binding the AppQoE policy. |
+
+## Deploy the AppQoE CRD
+
+Perform the following to deploy the AppQoE CRD:
+
+1.  Download the [AppQoE CRD](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/crd/appqoe/appqoe-crd.yaml).
+
+2.  Deploy the AppQoE CRD using the following command:
+
+        kubectl create -f appqoe-crd.yaml
+
+### How to write a AppQoE policy configuration
+
+After you have deployed the AppQoE CRD provided by Citrix in the Kubernetes cluster, you can define the AppQoE policy configuration in a `.yaml` file. In the `.yaml` file, use `appqoepolicy` in the kind field and in the `spec` section add the AppQoE CRD attributes based on your requirement for the policy configuration.
+
+The following YAML file applies the AppQoE policy to the services listed in the servicenames field. You must configure the AppQoE action to retry on timeout and define the number of retry attempts.
+
+```yml
+apiVersion: citrix.com/v1
+kind: appqoepolicy
+metadata:
+  name: targeturlappqoe
+spec:
+  appqoe-policies:
+    - servicenames:
+        - apache
+      appqoe-policy:
+        operation-retry:
+          onReset: 'YES'
+          onTimeout: 33
+        number-of-retries: 2
+        appqoe-criteria: 'HTTP.REQ.HEADER("User-Agent").CONTAINS("Android")'
+        direction: REQUEST
+```
+
+After you have defined the policy configuration, deploy the `.yaml` file using the following commands:
+
+   $ kubectl create -f appqoe-example.yaml
