Skip to content

Commit b7cff1d

Browse files
sreejithgssreejithgs
authored
Merge pull request #366 from citrix/doc-update-1.13
Doc update 1.13
2 parents d358820 + 6986118 commit b7cff1d

17 files changed

Lines changed: 744 additions & 79 deletions

File tree

‎canary/README.md‎

Lines changed: 253 additions & 43 deletions
Large diffs are not rendered by default.

‎deployment/openshift/manifest/cic.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ spec:
9191
serviceAccount: citrix
9292
containers:
9393
- name: cic
94-
image: "quay.io/citrix/citrix-k8s-ingress-controller:1.11.3"
94+
image: "quay.io/citrix/citrix-k8s-ingress-controller:1.13.15"
9595
securityContext:
9696
privileged: true
9797
env:

‎deployment/openshift/manifest/cpx_cic_side_car.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ spec:
100100
name: cpx-volume2
101101
# Add cic as a sidecar
102102
- name: cic
103-
image: "quay.io/citrix/citrix-k8s-ingress-controller:1.11.3"
103+
image: "quay.io/citrix/citrix-k8s-ingress-controller:1.13.15"
104104
volumeMounts:
105105
- mountPath: /var/deviceinfo
106106
name: shared-data

‎docs/canary/canary.md‎

Lines changed: 238 additions & 29 deletions
Large diffs are not rendered by default.

‎docs/configure/config-map.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@ The ConfigMap API resource holds key-value pairs of configuration data that can
44

55
ConfigMaps allow you to separate your configurations from your pods and make your workloads portable. Using ConfigMaps, you can easily change and manage your workload configurations and reduce the need to hardcode configuration data to pod specifications.
66

7-
The Citrix ingress controller supports configuration command line arguments, and environment variables mentioned in [deploying the Citrix ingress controller](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/deployment/baremetal/README.md). But, you cannot update these configurations at runtime without rebooting the Citrix ingress controller pod. With ConfigMap support, you can update the configuration automatically while keeping the Citrix ingress controller pod running. You do not need to restart the pod after the update.
7+
The Citrix ingress controller supports the configuration command line arguments, and environment variables mentioned in [deploying the Citrix ingress controller](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/deployment/baremetal/README.md). But, you cannot update these configurations at runtime without rebooting the Citrix ingress controller pod. With ConfigMap support, you can update the configuration automatically while keeping the Citrix ingress controller pod running. You do not need to restart the pod after the update.
88

99
## Supported environment variables in the Citrix ingress controller
1010

1111
The values for the following environment variables in the Citrix ingress controller can be specified in a ConfigMap.
1212

13-
- LOGLEVEL: Specifies the log levels to control the logs generated by Citrix ingress controller (debug, info, critical, and so on). The default value is `debug`.
13+
- LOGLEVEL: Specifies the log levels to control the logs generated by the Citrix ingress controller (debug, info, critical, and so on). The default value is `debug`.
1414

1515
- NS_HTTP2_SERVER_SIDE: Enables HTTP2 for Citrix ADC service group configurations with possible values as ON or OFF.
1616

@@ -20,6 +20,11 @@ The values for the following environment variables in the Citrix ingress control
2020

2121
- NS_COOKIE_VERSION: Specifies the persistence cookie version (0 or 1). The default value is `0`.
2222

23+
- POD_IPS_FOR_SERVICEGROUP_MEMBERS: Specifies to add the IP address of the pod and port as service group members instead of `NodeIP` and `NodePort` while configuring services of type `LoadBalancer` or `NodePort` on an external tier-1 Citrix ADC.
24+
25+
- IGNORE_NODE_EXTERNAL_IP: Specifies to ignore an external IP address and add an internal IP address for NodeIP while configuring NodeIP for services of type `LoadBalancer` or `NodePort` on an external tier-1 Citrix ADC.
26+
27+
2328
**Note:**
2429
This is an initial version of the ConfigMap support and currently supports only a few parameters. Earlier, these parameters were configurable through environment variables except the `NS_HTTP2_SERVER_SIDE` parameter.
2530

@@ -123,7 +128,7 @@ Perform the following to configure ConfigMap support for the Citrix ingress cont
123128

124129
kubectl delete -f cic-configmap.yaml
125130

126-
When you delete the ConfigMap, environment variable configuration falls back as per the following order of precedence:
131+
When you delete the ConfigMap, the environment variable configuration falls back as per the following order of precedence:
127132
ConfigMap configuration > environment variable configuration > default
128133

129134
(Optional) In case, you want to define all keys in a ConfigMap as environment variables in the Citrix ingress controller, use the following in the Citrix ingress controller deployment YAML file.

‎docs/configure/ingress-classes.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,75 @@ metadata:
5454
kubernetes.io/ingress.class: "my-custom-class"
5555
```
5656

57+
## Ingress V1 and IngressClass support
58+
59+
With the Kubernetes version 1.19, the Ingress resource is generally available.
60+
As a part of this change, a new resource named as `IngressClass` is added to the ingress API. Using this resource, you can associate specific Ingress controllers to Ingresses. For more information on the `IngressClass` resource, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class).
61+
62+
The following is a sample `IngressClass` resource.
63+
64+
```yml
65+
66+
apiVersion: networking.k8s.io/v1
67+
kind: IngressClass
68+
metadata:
69+
name: citrix
70+
spec:
71+
controller: citrix.com/ingress-controller
72+
73+
```
74+
75+
An `IngressClass`resource must refer to the ingress class associated with the controller that should implement the Ingress rules as shown as follows:
76+
77+
```yml
78+
apiVersion: networking.k8s.io/v1
79+
kind: Ingress
80+
metadata:
81+
name: minimal-ingress
82+
spec:
83+
ingressClassName: citrix
84+
host: abc.com
85+
rules:
86+
- http:
87+
paths:
88+
- path: /
89+
pathType: Prefix
90+
backend:
91+
service:
92+
name: test
93+
port:
94+
number: 80
95+
```
96+
97+
The Citrix ingress controller uses the following rules to match the Ingresses.
98+
99+
- If the Citrix ingress controller is started without specifying the `--ingress-classes` argument
100+
- If the Kubernetes version is lesser than 1.19 (IngressClass V1 resource is supported)
101+
- Matches any ingress object
102+
103+
- If the Kubernetes version is greater than or equal to 1.19 (IngressClass V1 resource is supported)
104+
- Matches any ingress object in which the `spec.ingressClassName` field is not set.
105+
- Matches any ingress if the `spec.ingressClassName` field of the Ingress object is set and a `v1.IngressClass` resource exists with the same name and the `spec.controller` field of the resource is `citrix.com/ingress-controller`.
106+
107+
- If the Citrix ingress controller is started with one or more ingress classes set using the `--ingress-classes` argument.
108+
109+
- If the Kubernetes version is lesser than 1.19 (IngressClass V1 resource is supported)
110+
- Matches any ingress with the ingress class annotation `kubernetes.io/ingress.class `matching to that of the configured ingress classes.
111+
- If the Kubernetes version is greater than or equal to 1.19 (IngressClass V1 resource is supported)
112+
- Matches any ingress in which the ingress class annotation `kubernetes.io/ingress.class` matches with the configured ingress classes. This annotation is deprecated but it has higher precedence over the `spec.IngressClassName` field to support backward compatibility.
113+
- Matches any ingress object, if a `v1.IngressClass` resource exists with the following attributes:
114+
- The name of the resource matches the `--ingress-classes` argument value.
115+
- The `spec.controller` field of the resource is set as the `citrix.com/ingress-controller`.
116+
- The name of the resource matches with the `spec.ingressClassName` field of the Ingress object.
117+
- Matches any ingress object where the `spec.ingressClassName` field is not set and if a `v1.IngressClass` resource exists with the following attributes:
118+
- The name of the resources matches the `--ingress-classes` argument value.
119+
- The `spec.controller` field of the resource is set as `citrix.com/ingress-controller`.
120+
- The resource is configured as the default class using the `ingressclass.kubernetes.io/is-default-class` annotation. For more information, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-ingress-class).
121+
122+
**Note:** If both the annotation and `spec.ingressClassName` is defined, the annotation is matched before the `spec.ingressClassName`. If the annotation does not match, the matching operation for the `spec.ingressClassName` field is not performed.
123+
124+
**Note:** When you are using Helm charts to install the Citrix ingress controller, if the `IngressClass` resource is supported and the Citrix ingress controller is deployed with the `--ingress-classes` argument, the `v1.IngressClass` resource is created by default.
125+
57126
## Updating the Ingress status for the Ingress resources with the specified IP address
58127

59128
To update the `Status.LoadBalancer.Ingress` field of the Ingress resources managed by the Citrix ingress controller with the allocated IP addresses, specify the command line argument `--update-ingress-status yes` when you start the Citrix ingress controller. This feature is only supported for the Citrix ingress controller deployed as a stand-alone pod for managing Citrix ADC VPX or MPX. For Citrix ADC CPXs deployed as sidecars, this feature is not supported.

‎docs/deploy/deploy-api-gateway-using-gitops.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ The API Gateway deployment CRD configures the following:
6161
- API to policy mapping
6262
- Open API authentication policy references to authentication policy template mapping
6363

64+
Alternatively, API Gateway CRD supports non-Git sources for fetching OpenAPI Specification (OAS) documents. Currently, both HTTP and HTTPS URL sources are supported. These URLs can be password protected and basic HTTP authentication is supported. Credentials can be configured using the same fields as that of Git based OAS file sources.
65+
6466
**Workflow**
6567

6668
The following image shows the API Gateway deployment CRD binding the API specification with policy templates using the API selectors and policy mappings.
@@ -96,11 +98,11 @@ The API Gateway deployment CRD configures the following:
9698
| ---------- | ----------- |
9799
| `Repository` | Specifies the Git repository URL.|
98100
| `Branch` | Specifies the Git branch name (By default, master). |
99-
| `git_secret_ref` | Specifies the Git access secret reference as a Kubernetes secret object name. **Note**: When creating a secret, keep the *user name* and *password* as the secret field names for user name and password.
101+
| `oas_secret_ref` | Specifies the Git access secret reference as a Kubernetes secret object name. **Note**: When creating a secret, keep the *user name* and *password* as the secret field names for user name and password.
100102
|
101103
| `User_name` | Specifies the Git user name. |
102104
| `Password` | Specifies the Git password. **Note**: Credentials can be specified as a *git_secret_ref* as mentioned before or as user name and password in plain text format. |
103-
| `Files` | Specifies the list of API specification files to monitor. |
105+
| `Files` | The credentials for these OAS URLs can be accessed from the `oas_secret_ref` field or user_name and password field combinations. |
104106

105107
## API proxy
106108

‎docs/deploy/deploy-cic-yaml.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,9 @@ Perform the following:
8888
| NS_VIP | Optional | Citrix ingress controller uses the IP address provided in this environment variable to configure a virtual IP address to the Citrix ADC that receives Ingress traffic. </br>**Note:** NS_VIP takes precedence over the [frontend-ip](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/docs/annotations.md) annotation. |
8989
| NS_APPS_NAME_PREFIX | Optional | By default, the Citrix ingress controller adds "**k8s**" as prefix to the Citrix ADC entities such as, content switching (CS) virtual server, load balancing (LB) virtual server and so on. You can now customize the prefix using the `NS_APPS_NAME_PREFIX` environment variable in the Citrix ingress controller deployment YAML file. You can use alphanumeric characters for the prefix and the prefix length should not exceed 8 characters. |
9090
| NAMESPACE | Optional | While running a Citrix ingress controller with Role based RBAC, you must provide the namespace which you want to listen or get events. This namespace must be same as the one used for creating the service account. Using the service account, the Citrix ingress controller can listen on a namespace. You can use the `NAMESPACE` environment variable to specify the namespace. For more information, see [Deploy the Citrix ingress controller for a namespace](#Deploy-the-Citrix-ingress-controller-for-a-namespace). |
91+
| POD_IPS_FOR_SERVICEGROUP_MEMBERS| Optional| By default, while configuring services of type LoadBalancer and NodePort on an external tier-1 Citrix ADC the Citrix ingress controller adds NodeIP and NodePort as service group members. If this variable is set as `True`, pod IP address and port are added instead of NodeIP and NodePort as service group members.|
92+
|IGNORE_NODE_EXTERNAL_IP| Optional |While adding NodeIP for services of type LoadBalancer or NodePort on an external tier-1 Citrix ADC, the Citrix ingress controller prioritizes an external IP address over an internal IP address. When you want to prefer an internal IP address over an external IP address for NodeIP, you can set this variable to `True`.|
93+
9194

9295
2. Once you update the environment variables, save the YAML file and deploy it using the following command:
9396

‎docs/how-to/pbr.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
2+
# Policy based routing support for multiple Kubernetes clusters
3+
4+
When you are using a single Citrix ADC to load balance multiple Kubernetes clusters, the Citrix ingress controller adds pod CIDR networks through static routes. These routes establish networking connectivity between Kubernetes pods and Citrix ADC. However, when the pod CIDRs overlap there may be route conflicts. Citrix ADC supports policy based routing (PBR) to address the networking conflicts in such scenarios. In PBR, decisions are taken based on the criteria that you specify. Typically, a next hop is specified where you send the selected packets. In a multi-cluster Kubernetes environment, PBR is implemented by reserving a subnet IP address (SNIP) for each Kubernetes cluster or the Citrix Ingress Controller. Using net profile, the SNIP is bound to all service groups created by the same Citrix ingress controller. For all the traffic generated from service groups belonging to the same cluster, the source IP address is the same SNIP.
5+
6+
Following is a sample topology where PBR is configured for two Kubernetes clusters which are load balanced using a Citrix ADC VPX or MPX.
7+
8+
![PBR configuration](../media/pbr.jpg)
9+
10+
## Configure PBR using the Citrix ingress controller
11+
12+
To configure PBR, you need one SNIP or more per Kubernetes cluster. You can provide SNIP values either using the environment variable in the Citrix ingress controller deployment YAML file during bootup or using ConfigMap.
13+
14+
Perform the following steps to deploy the Citrix ingress controller and configure PBR using ConfigMap.
15+
16+
1. Download the `citrix-k8s-ingress-controller.yaml` using the following command:
17+
18+
wget https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/deployment/baremetal/citrix-k8s-ingress-controller.yaml
19+
20+
2. Edit the Citrix ingress controller YAML file:
21+
22+
- Specify the values of the environment variables as per your requirements. For more information on specifying the environment variables, see the [Deploy Citrix ingress controller](https://developer-docs.citrix.com/projects/citrix-k8s-ingress-controller/en/latest/deploy/deploy-cic-yaml/).
23+
24+
3. Deploy the Citrix ingress controller using the edited YAML file with the following command on each cluster.
25+
26+
kubectl create -f citrix-k8s-ingress-controller.yaml
27+
28+
4. Create a YAML file `cic-configmap.yaml` with the required SNIP values in the ConfigMap.
29+
30+
Following is an example for a ConfigMap with the SNIP values:
31+
32+
```yml
33+
34+
apiVersion: v1
35+
kind: ConfigMap
36+
metadata:
37+
name: pbr-test
38+
namespace: default
39+
data:
40+
NS_SNIPS: '["192.0.2.2", "192.0.2.1"]'
41+
```
42+
43+
5. Apply the ConfigMap.
44+
45+
kubectl create -f cic-configmap.yaml
46+
47+
You can also specify the SNIPs using the `NS_SNIPS` environment variable in the Citrix ingress controller deployment YAML file.
48+
49+
- name: "NS_SNIPS"
50+
value: `["192.0.2.2", "192.0.2.1"]`
51+
52+
The following are the usage guidelines while using ConfigMap for configuring SNIP:
53+
54+
- Only SNIPs can be added or removed via ConfigMap. The `feature-node-watch` argument can only be enabled during bootup.
55+
56+
- When you add a ConfigMap:
57+
58+
- If SNIPs were already provided using the environment variable during bootup and you want to retain them, those SNIPs should be specified in the ConfigMap along with the new SNIPs.
59+
60+
- When you delete ConfigMap:
61+
62+
- All PBRs generated by ConfigMap SNIPs are deleted. If SNIPs are provided via the environment variable, PBR for those IP addresses is added.
63+
64+
- If SNIPs were not provided using the `NS_SNIPS` environment variable, static routes are added since `feature-node-watch` is enabled.

‎docs/media/pbr.jpg‎

130 KB
Loading

0 commit comments

Comments
 (0)