Skip to content

Commit 4f77c8b

Browse files
sreejithgssreejithgs
authored
Merge pull request #454 from citrix/support-update
Support update
2 parents da6b6a8 + 9b5ea6a commit 4f77c8b

13 files changed

Lines changed: 272 additions & 55 deletions

File tree

‎crd/auth/README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,9 @@ The following are the attributes for forms based authentication.
4545
|`listener_name`| The name of the Listener CRD for which the authentication using forms is applicable.|
4646
| `vip` |Specifies the front-end IP address of the Ingress for which the authentication using forms is applicable. This attribute refers to the `frontend-ip` address provided with the Ingress. If there is more than one Ingress resource which uses the same frontend-ip, it is recommended to use vip.|
4747

48-
**Note:** While using forms, authentication can be enabled for all types of traffic. Currently, granular authentication is not supported.
48+
**Note:** While using forms, authentication can be enabled for all types of traffic. Currently, granular authentication is not supported.
49+
50+
**Note:** Depending on the resource to which you need to apply form based authentication, you can use one of the `ingress_name`, `lb_service_name`, `listener_name`, or `vip` attributes to specify the resource.
4951

5052
### Authentication providers
5153

@@ -412,7 +414,7 @@ spec:
412414
authentication_host: "fqdn_authenticaton_host"
413415
authentication_host_cert:
414416
tls_secret: authhost-tls-cert-secret
415-
ingress_name: “example-ingress”
417+
listener_name: “example-listener”
416418
417419
authentication_providers:
418420
- name: "saml-auth-provider"
@@ -613,4 +615,5 @@ stringData:
613615
username: 'ldap_server_username'
614616
password: 'ldap_server_password'
615617
616-
```
618+
```
619+

‎crd/cors/README.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Configure cross-origin resource sharing policies with Citrix ingress controller
2+
3+
Citrix provides a Custom Resource Definition (CRD) called the CORS CRD for Kubernetes. You can use the CORS CRD to configure the cross-origin resource sharing (CORS) policies with Citrix ingress controller on the Citrix ADC.
4+
5+
## What is CORS
6+
7+
Cross-Origin resource sharing is a mechanism that allows the browser to determine whether a specific web application can share resources with another web application from a different origin. It allows users request resources (For example, images, fonts, and videos) from domains outside the original domain.
8+
9+
## CORS pre-flight
10+
11+
Before a web browser allowing Javascript to issue a POST to a URL, it performs a `pre-flight` request. A pre-flight request is a simple request to the server with the same URL using the method OPTIONS rather than POST. The web browser checks the HTTP headers for CORS related headers to determine if POST operation on behalf of the user is allowed.
12+
13+
![CORS request](../../docs/media/cors-api.png)
14+
15+
## CORS CRD definition
16+
17+
The CORS CRD is available in the Citrix ingress controller GitHub repo at: [cors-crd.yaml](https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/cors/cors-crd.yaml). The CORS CRD provides attributes for the various options that are required to define the CORS policy on the Ingress Citrix ADC that acts as an API gateway. The required attributes include: `servicenames`, `allow_origin`, `allow_methods`, and `allow_headers`.
18+
19+
The following are the attributes provided in the CORS CRD:
20+
21+
| Attribute | Description |
22+
| --------- | ----------- |
23+
| `servicenames` | Specifies the list of Kubernetes services to which you want to apply the CORS policies.|
24+
| `allow_origin` | Specifies the list of allowed origins. Incoming origin is screened against this list.|
25+
|`allow_methods`| Specifies the list of allowed methods as part of the CORS protocol.|
26+
| `allow_headers`| Specifies the list of allowed headers as part of the CORS protocol.|
27+
|`max_age`| Specifies the number of seconds the information provided by the `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` headers can be cached. The default value is 86400.|
28+
| `allow_credentials` |Specifies whether the response can be shared when the credentials mode of the request is "include". The default value is 'true'.|
29+
30+
## Deploy the CORS CRD
31+
32+
Perform the following to deploy the CORS CRD:
33+
34+
1. Download the [CORS CRD](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/crd/cors/cors-crd.yaml).
35+
36+
2. Deploy the CORS CRD using the following command:
37+
38+
kubectl create -f cors-crd.yaml
39+
40+
For example:
41+
42+
$ kubectl create -f cors-crd.yaml
43+
customresourcedefinition.apiextensions.k8s.io/corspolicies.citrix.com created
44+
$ kubectl get crd
45+
NAME CREATED AT
46+
corspolicies.citrix.com 2021-05-21T20:01:13Z
47+
48+
### How to write a CORS policy configuration
49+
50+
After you have deployed the CORS CRD provided by Citrix in the Kubernetes cluster, you can define the CORS policy configuration in a `.yaml` file. In the `.yaml` file, use `corspolicy` in the kind field and in the `spec` section add the CORS CRD attributes based on your requirement for the policy configuration.
51+
52+
The following YAML file applies the configured policy to the services listed in the servicenames field. Citrix ADC responds with a 200 OK response code for the pre-flight request if the origin is one of the `allow_origins` ["random1234.com", "hotdrink.beverages.com"]. The response includes configured `allow_methods`, `allow_headers`, and `max_age`.
53+
54+
```yml
55+
apiVersion: citrix.com/v1beta1
56+
kind: corspolicy
57+
metadata:
58+
name: corspolicy-example
59+
spec:
60+
servicenames:
61+
- "cors-service"
62+
allow_origin:
63+
- "random1234.com"
64+
- "hotdrink.beverages.com"
65+
allow_methods:
66+
- "POST"
67+
- "GET"
68+
- "OPTIONS"
69+
allow_headers:
70+
- "Origin"
71+
- "X-Requested-With"
72+
- "Content-Type"
73+
- "Accept"
74+
- "X-PINGOTHER"
75+
max_age: 86400
76+
allow_credentials: true
77+
```
78+
After you have defined the policy configuration, deploy the `.yaml` file using the following commands:
79+
80+
user@master:~/cors$ kubectl create -f corspolicy-example.yaml
81+
corspolicy.citrix.com/corspolicy-example created
82+
83+
The Citrix ingress controller applies the policy configuration on the Ingress Citrix ADC device.

‎crd/cors/cors-crd.yaml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
apiVersion: apiextensions.k8s.io/v1beta1
2+
kind: CustomResourceDefinition
3+
metadata:
4+
name: corspolicies.citrix.com
5+
spec:
6+
group: citrix.com
7+
version: v1beta1
8+
names:
9+
kind: corspolicy
10+
plural: corspolicies
11+
singular: corspolicy
12+
shortNames:
13+
- cp
14+
scope: Namespaced
15+
subresources:
16+
status: {}
17+
additionalPrinterColumns:
18+
- name: Status
19+
type: string
20+
description: 'Current Status of the CRD'
21+
JSONPath: .status.state
22+
- name: Message
23+
type: string
24+
description: 'Status Message'
25+
JSONPath: .status.status_message
26+
validation:
27+
openAPIV3Schema:
28+
properties:
29+
spec:
30+
properties:
31+
ingressclass:
32+
type: string
33+
description: "Ingress class, if not specified then all citrix ingress controllers in the cluster will process the resource otherwise only the controller with that ingress class will process this resource"
34+
servicenames:
35+
description: 'The list of Kubernetes services to which you want to apply the cors policies.'
36+
type: array
37+
items:
38+
type: string
39+
maxLength: 63
40+
allow_origin:
41+
description: 'Represents list of allowed origins, it is used to screen the “origin” in the cors pre flight request'
42+
type: array
43+
items:
44+
type: string
45+
maxLength: 2083
46+
allow_methods:
47+
description: 'Indicates which methods are supported by the response’s URL for the purposes of the CORS protocol. This variable will be used to set Access-Control-Allow-Methods in the pre-flight cors response.'
48+
type: array
49+
items:
50+
type: string
51+
maxLength: 127
52+
allow_headers:
53+
description: 'Indicates which headers are supported by the response’s URL for the purposes of the CORS protocol. This variable will be used to set Access-Control-Allow-Headers in the pre-flight cors response.'
54+
type: array
55+
items:
56+
type: string
57+
maxLength: 127
58+
max_age:
59+
description: 'Indicates the number of seconds (5 by default) the information provided by the `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` headers can be cached. This variable will be used to set Access-Control-Max-Age in the pre-flight cors response.'
60+
type: integer
61+
allow_credentials:
62+
description: 'Indicates whether the response can be shared when the request’s credentials mode is "include". This variable will be set to Access-Control-Allow-Credentials in the rewrite action.'
63+
type: boolean
64+
required: [servicenames, allow_origin, allow_methods, allow_headers]

‎crd/ratelimit/README.md‎

Lines changed: 33 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,13 @@ In a Kubernetes deployment, you can rate limit the requests to the resources on
44

55
Citrix provides a Kubernetes [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions) (CRDs) called the **Rate limit CRD** that you can use with the Citrix ingress controller to configure the rate limiting configurations on the Citrix ADCs used as Ingress devices.
66

7-
Apart from rate limiting the requests to the services in Kubernetes environment, you can use the Rate limit CRD for API security as well. The Rate limit CRD allows you to limit the REST API request to API servers or specific API endpoints on the API servers. It monitors and keeps track of the requests to the API server or endpoints against the allowed limit per time slice and hence protects from attacks such as DDos attack.
7+
Apart from rate limiting the requests to the services in a Kubernetes environment, you can use the Rate limit CRD for API security as well. The Rate limit CRD allows you to limit the REST API request to API servers or specific API endpoints on the API servers. It monitors and keeps track of the requests to the API server or endpoints against the allowed limit per time slice and hence protects from attacks such as the DDoS attack.
8+
9+
You can enable logging for observability with the rate limit CRD. Logs are stored on Citrix ADC which can be viewed by checking the logs using the shell command. The file location is based on the syslog configuration. For example, `/var/logs/ns.log`.
810

911
## Rate limit CRD definition
1012

11-
The Rate limit CRD is available in the Citrix ingress controller GitHub repo at: [ratelimit-crd.yaml](https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/ratelimit/ratelimit-crd.yaml). The Rate limit CRD provides [attributes](#ratelimit-crd-attributes) for various options that are required to define the rate limit policies on the Ingress Citrix ADC that acts as an API gateway.
13+
The Rate limit CRD is available in the Citrix ingress controller GitHub repo at: [ratelimit-crd.yaml](https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/ratelimit/ratelimit-crd.yaml). The **Rate limit CRD provides** [attributes](#ratelimit-crd-attributes) for the various options that are required to define the rate limit policies on the Ingress Citrix ADC that acts as an API gateway.
1214

1315
The following is the Rate limit CRD definition ([ratelimit-crd.yaml](https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/ratelimit/ratelimit-crd.yaml)):
1416

@@ -25,17 +27,6 @@ spec:
2527
plural: ratelimits
2628
singular: ratelimit
2729
scope: Namespaced
28-
subresources:
29-
status: {}
30-
additionalPrinterColumns:
31-
- name: Status
32-
type: string
33-
description: "Current Status of the CRD"
34-
JSONPath: .status.state
35-
- name: Message
36-
type: string
37-
description: "Status Message"
38-
JSONPath: .status.status_message
3930
validation:
4031
openAPIV3Schema:
4132
properties:
@@ -76,7 +67,7 @@ spec:
7667
description: 'Timeslice in miliseconds in multiple of 10. Defaults to 1000 miliseconds'
7768
type: integer
7869
limittype:
79-
description: "Burst mode or smooth. Defaults to burst if limittype is not specified"
70+
description: "Burst mode or smooth. Defaults to smooth limittype if not specified"
8071
type: string
8172
enum: ['BURSTY','SMOOTH']
8273
throttle_action:
@@ -86,6 +77,19 @@ spec:
8677
redirect_url:
8778
type: string
8879
description: "Redirect-URL"
80+
logpackets:
81+
description: 'Adds an audit message action.
82+
The action specifies whether to log the message, and to which log.'
83+
properties:
84+
logexpression:
85+
description: 'Default-syntax expression that defines the format and content of the log message.'
86+
type: string
87+
maxLength: 7991
88+
loglevel:
89+
description: 'Audit log level, which specifies the severity level of the log message being generated.'
90+
type: string
91+
enum: ["EMERGENCY", "ALERT", "CRITICAL", "ERROR", "WARNING", "NOTICE", "INFORMATIONAL", "DEBUG"]
92+
required: [logexpression, loglevel]
8993
required: [servicenames, req_threshold]
9094
```
9195
@@ -96,12 +100,15 @@ The following table lists the various attributes provided in the Rate limit CRD:
96100
| CRD attribute | Description |
97101
| ---------- | ----------- |
98102
| `servicename` | The list of Kubernetes services to which you want to apply the rate limit policies. |
99-
| `selector_keys` | The traffic selector keys that filter the traffic to identify the API requests against which the throttling is applied and monitored. </br> </br>**Note:** The `selector_keys` is an optional attribute. You can choose to configure zero, one or more of the selector keys. If more than one selector keys are configured then it is considered as a logical AND expression.</br></br> In this version of the Rate limit CRD, `selector_keys` provides `basic` configuration section that you can use to configure the following commonly used traffic characteristics as the keys against which the configured limits are monitored and throttled:</br></br> - **path:** An array of URL path prefixes that refer to a specific API endpoint. For example, `/api/v1/products/` </br> - **method:** An array of HTTP methods. Allowed values are GET, PUT, POST, or DELETE. </br> - **header_name:** HTTP header that has the unique API client or user identifier. For example, `X-apikey` which comes with unique API-key that identifies the API client sending the request. </br>- **per_client_ip:** Allows you to monitor and apply the configured threshold to each API request received per unique client IP address. |
103+
| `selector_keys` | The traffic selector keys that filter the traffic to identify the API requests against which the throttling is applied and monitored. </br> </br>**Note:** The `selector_keys` is an optional attribute. You can choose to configure zero, one or more of the selector keys. If more than one selector keys are configured then it is considered as a logical AND expression.</br></br> In this version of the Rate limit CRD, `selector_keys` provides the `basic` configuration section that you can use to configure the following commonly used traffic characteristics as the keys against which the configured limits are monitored and throttled:</br></br> - **path:** An array of URL path prefixes that refer to a specific API endpoint. For example, `/api/v1/products/` </br> - **method:** An array of HTTP methods. Allowed values are GET, PUT, POST, or DELETE. </br> - **header_name:** HTTP header that has the unique API client or user identifier. For example, `X-apikey` which comes with a unique API-key that identifies the API client sending the request. </br>- **per_client_ip:** Allows you to monitor and apply the configured threshold to each API request received per unique client IP address. |
100104
| `req_threshold` | The maximum number of requests that are allowed in the given time slice (request rate). |
101105
| `timeslice` | The time interval specified in microseconds (multiple of 10 s), during which the requests are monitored against the configured limits. If not specified it defaults to 1000 milliseconds. |
102-
| `limittype` | It allows you to configure the following type of throttling algorithms that you want to use to apply the limit: </br> - burst </br> - smooth </br> The default is ***burst*** mode.
103-
| `throttle_action` | It allows you to define the throttle action that needs to be taken on the traffic that's throttled for crossing the configured threshold. </br></br> The following are the throttle action that you can define: </br> - **DROP:** Drops the requests above the configured traffic limits. </br>- **RESET:** Resets the connection for the requests crossing configured limit. </br> - **REDIRECT:** Redirects the traffic to the configured `redirect_url`. </br> - **RESPOND:** Responds with the standard "***429 Too many requests***" response. |
104-
| `redirect_url` | This is an optional attribute that is required only if `throttle_action` is configured with the value `REDIRECT`. |
106+
| `limittype` | It allows you to configure the following type of throttling algorithms that you want to use to apply the limit: </br> - burst </br> - smooth. The default is the ***burst*** mode.
107+
| `throttle_action` | It allows you to define the throttle action that needs to be taken on the traffic that's throttled for crossing the configured threshold. </br></br> The following are the throttle action that you can define: </br> - **DROP:** Drops the requests above the configured traffic limits. </br>- **RESET:** Resets the connection for the requests crossing the configured limit. </br> - **REDIRECT:** Redirects the traffic to the configured `redirect_url`. </br> - **RESPOND:** Responds with the standard "***429 Too many requests***" response. |
108+
| `redirect_url` | This attribute is an optional attribute that is required only if `throttle_action` is configured with the value `REDIRECT`. |
109+
| `logpackets` | Enables audit logs. |
110+
| `logexpression` | Specifies the default-syntax expression that defines the format and content of the log message. |
111+
| `loglevel` | Specifies the severity level of the log message that is generated. |
105112

106113
## Deploy the Rate limit CRD
107114

@@ -153,11 +160,14 @@ spec:
153160
req_threshold: 15
154161
timeslice: 60000
155162
throttle_action: "RESPOND"
163+
logpackets:
164+
logexpression: "http.req.url"
165+
loglevel: "INFORMATIONAL"
156166
```
157167

158168
>**Note:**
159169
>
160-
> You can initiate multiple Kubernetes objects for different paths that require different ratelimit configurations.
170+
> You can initiate multiple Kubernetes objects for different paths that require different rate limit configurations.
161171

162172
After you have defined the policy configuration, deploy the `.yaml` file using the following command:
163173

@@ -168,7 +178,7 @@ The Citrix ingress controller applies the policy configuration on the Ingress Ci
168178

169179
#### Limit API requests to calender APIs
170180

171-
Consider a scenario wherein you want to define a rate-based policy in Citrix ADC to limit the API requests (GET or POST) to 5 requests from each API client identified using HTTP header `X-API-Key` to the calender APIs. Create a `.yaml` file called `ratelimit-example2.yaml` and use the appropriate CRD attributes to define the rate-based policy as follows:
181+
Consider a scenario wherein you want to define a rate-based policy in a Citrix ADC to limit the API requests (GET or POST) to five requests from each API client identified using the HTTP header `X-API-Key` to the calender APIs. Create a `.yaml` file called `ratelimit-example2.yaml` and use the appropriate CRD attributes to define the rate-based policy as follows:
172182

173183
```yml
174184
apiVersion: citrix.com/v1beta1
@@ -188,6 +198,9 @@ spec:
188198
header_name: "X-API-Key"
189199
req_threshold: 5
190200
throttle_action: "RESPOND"
201+
logpackets:
202+
logexpression: "rate exceeded, you may want to configure higher limit"
203+
loglevel: "INFORMATIONAL"
191204
```
192205

193206
After you have defined the policy configuration, deploy the `.yaml` file using the following command:

0 commit comments

Comments
 (0)