Skip to content

Commit 20e6a13

Browse files
sreejithgssreejithgs
authored
Merge pull request #585 from citrix/new-simplified-doc-set
adding the files in simplified deployment
2 parents e7f5856 + 3c21e32 commit 20e6a13

12 files changed

Lines changed: 2337 additions & 0 deletions

‎simplified-deployment-usecases/ DNS-configuration.md‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
# NetScaler DNS configuration using Citrix ingress controller
2+
3+
NetScaler can be configured as an Authoritative Domain Name Server (ADNS), DNS proxy server, DNS resolver, or Forwarder. You can configure DNS resource records such as SRV records, A records, AAAA records, NS records, SOA records, and so on which can load balance on external DNS servers.
4+
5+
You can add, remove, enable, and disable external name servers using their IP addresses or you can configure an existing virtual server as the name server.
6+
7+
When adding name servers you can specify IP addresses or Virtual IP addresses (VIPs).
8+
9+
You can use Citrix ingress controller to configure NetScaler with the following DNS configurations.
10+
11+
- [Configuring NetScaler VPX or MPX as an ADNS server](#configuring-netscaler-vpx-or-mpx-as-an-adns-server)
12+
13+
- [Configuring DNS Address records in NetScaler VPX or MPX](#configuring-netscaler-as-dns-resolver)
14+
15+
- [Configuring DNS Nameserver on NetScaler VPX or MPX](#configuring-dns-nameservers-on-netscaler-vpx-or-mpx)
16+
17+
- [Configuring Wildcard DNS domains in NetScaler](#configuring-wildcard-domains-in-netscaler-using-citrix-ingress-controller)
18+
19+
- [Traffic Management of External services](#traffic-management-of-external-services)
20+
21+
## Configuring NetScaler VPX or MPX as an ADNS server
22+
23+
Citrix ingress controller can configure NetScaler VPX/MPX as an ADNS server using the ConfigMap variable `NS_ADNS_IPS`.
24+
25+
An example of a ConfigMap for configuring NetScaler VPX/MPX as ADNS servers.
26+
27+
```yml
28+
apiVersion: v1
29+
kind: ConfigMap
30+
metadata:
31+
name: adns-cmap
32+
namespace: netscaler
33+
data:
34+
NS_ADNS_IPS: '["192.1.2.3", "175.2.4.5"]' # List of IPs to configure ADNS server
35+
```
36+
37+
**NOTE:**
38+
You can also configure NetScaler VPX or MPX as an ADNS server using the environment variable `NS_ADNS_IPS` of [Citrix Ingress Controller deployment](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/deployment/baremetal/citrix-k8s-ingress-controller.yaml#L95).
39+
40+
NetScaler Configuration:
41+
42+
```
43+
show server
44+
45+
1) Name: 192.1.2.3 State:ENABLED
46+
IPAddress: 192.1.2.3
47+
2) Name: 175.2.4.5 State:ENABLED
48+
IPAddress: 175.2.4.5
49+
```
50+
51+
## Configuring NetScaler as DNS resolver
52+
53+
To configure NetScaler as a DNS resolver, you can add the DNS address records using Citrix Ingress Controller.
54+
55+
### Adding DNS records for Ingress resources
56+
57+
To add DNS records for ingress resources, you need to set the value of the variable `NS_CONFIG_DNS_REC` to `true` in [Citrix Ingress Controller](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/deployment/baremetal/citrix-k8s-ingress-controller.yaml#L95) deployment at the boot time.
58+
Citrix Ingress Controller adds the address records in NetScaler for all the host names specified under the ingresses that are intended to configure NetScaler.
59+
60+
### Adding DNS records for services of type LoadBalancer
61+
62+
To add DNS records for the service of type LoadBalancer, you need to:
63+
64+
1. Enable the `NS_SVC_LB_DNS_REC` environment variable of Citrix Ingress Controller deployment by setting the value as `true`.
65+
2. Specify the DNS host name for which the address records needs to be updated in NetScaler using the `service.citrix.com/dns-hostname` annotation in the service of type LoadBalancer.
66+
67+
Following is an example of a service of Type LoadBalancer with the special annotation to add DNS address records in NetScaler.
68+
69+
```yml
70+
apiVersion: v1
71+
kind: Service
72+
metadata:
73+
name: guestbook
74+
annotations:
75+
# Special annotation to add DNS Address records in Netscaler.
76+
service.citrix.com/dns-hostname: "www.guestbook.com"
77+
spec:
78+
type: LoadBalancer
79+
ports:
80+
- port: 9006
81+
targetPort: 80
82+
protocol: TCP
83+
selector:
84+
app: guestbook
85+
```
86+
87+
NetScaler Configuration:
88+
89+
```
90+
show dns addrec
91+
92+
1) Host Name : www.guestbook.com ECS Subnet : None
93+
Record Type : ADNS TTL : 3600 secs
94+
IP Address : 175.4.3.5
95+
96+
```
97+
98+
## Configuring DNS Nameservers on NetScaler VPX or MPX
99+
100+
Citrix ingress controller can configure DNS nameservers on NetScaler VPX or MPX using the ConfigMap variable `NS_DNS_NAMESERVER`.
101+
102+
An example of a ConfigMap to configure DNS nameservers on NetScaler VPX or MPX.
103+
104+
```yml
105+
apiVersion: v1
106+
kind: ConfigMap
107+
metadata:
108+
name: nameserver-cmap
109+
namespace: netscaler
110+
data:
111+
NS_DNS_NAMESERVER: '["192.1.2.3", "175.2.4.5"]' # List of Name server IPs to configured on NetScaler VPX/MPX
112+
```
113+
114+
**NOTE:**
115+
You can also configure DNS nameservers on NetScaler VPX/MPX using the environment variable `NS_DNS_NAMESERVER` of [Citrix Ingress Controller deployment](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/deployment/baremetal/citrix-k8s-ingress-controller.yaml).
116+
117+
NetScaler configuration:
118+
119+
```
120+
# show nameserver
121+
1) 192.1.2.3 - State: DOWN Protocol: UDP
122+
2) 192.1.2.3 - State: DOWN Protocol: TCP
123+
3) 175.2.4.5 - State: DOWN Protocol: UDP
124+
4) 175.2.4.5 - State: DOWN Protocol: TCP
125+
126+
```
127+
128+
## Traffic Management of External services
129+
130+
To enable NetScaler features such as traffic management, policy enforcement, fail over management an external service which is deployed outside of the Kubernetes cluster, you need to configure NetScaler as domain name resolver and make sure that the reachability of the external service is established from the Kubernetes cluster.
131+
132+
### Configure NetScaler as a domain name resolver using Citrix ingress controller
133+
134+
Citrix Ingress Controller can configure NetScaler as domain name resolver by creating a domain-based service group using the ingress annotation `ingress.citrix.com/external-service`.
135+
136+
The value for `ingress.citrix.com/external-service` is a list of external name services with their corresponding domain names.
137+
138+
```yml
139+
apiVersion: networking.k8s.io/v1
140+
kind: Ingress
141+
metadata:
142+
name: ingress-demo
143+
namespace: netscaler
144+
annotations:
145+
kubernetes.io/ingress.class: "netscaler"
146+
ingress.citrix.com/external-service: '{"my-service": {"domain": "www.external.service.com"}}'
147+
spec:
148+
rules:
149+
- host: "externalservice.com"
150+
http:
151+
paths:
152+
- path: /
153+
pathType: Prefix
154+
backend:
155+
service:
156+
name: service-test
157+
port:
158+
number: 80
159+
```
160+
161+
### Configure a service to enable reachability of NetScaler from the Kubernetes cluster
162+
163+
To reach NetScaler from microservices in a Kubernetes cluster, you need to define a headless service which would be resolved to a NetScaler service and thus the connectivity between microservices and NetScaler establishes.
164+
165+
The following is the sample NetScaler service which enables connectivity from microservices to NetScaler.
166+
167+
```yml
168+
apiversion: v1
169+
kind: Service
170+
metadata:
171+
name: my-service
172+
spec:
173+
selector:
174+
app: cpx
175+
ports:
176+
- protocol: TCP
177+
port: 80
178+
```
179+
180+
### Configure IP address of DNS server to reach external service endpoints
181+
182+
Using the ConfigMap variable `NS_DNS_NAMESERVER` you can configure the name server to reach the external service.
183+
184+
```yml
185+
apiVersion: v1
186+
kind: ConfigMap
187+
metadata:
188+
name: nameserver-cmap
189+
namespace: default
190+
data:
191+
NS_DNS_NAMESERVER: '["192.1.2.3"]'
192+
```
193+
194+
### Traffic management using NetScaler CPX
195+
196+
The following diagram depicts NetScaler CPX deployment to reach external services. An Ingress is deployed where the external service annotation is specified to configure DNS on NetScaler CPX.
197+
198+
**Note:** A ConfigMap is used to configure name servers on NetScaler VPX or MPX.
199+
200+
![Traffic Management of External Services](../docs/media/cpx-traffic.png)
201+
202+
In this deployment:
203+
204+
1. A microservice sends the DNS query for www.externalsvc.com which would get resolved to the NetScaler CPX service.
205+
206+
2. NetScaler CPX resolves www.externalsvc.com and reaches external service.
207+
208+
Following are the steps to configure NetScaler CPX to load balance external services:
209+
210+
1. Define a headless service to reach NetScaler.
211+
212+
```yml
213+
apiVersion: v1
214+
kind: Service
215+
metadata:
216+
name: external-svc # Service to reach CPX
217+
spec:
218+
selector:
219+
app: cpx # Referring to CPX deployment
220+
ports:
221+
- protocol: TCP
222+
port: 80
223+
```
224+
225+
2. Define an ingress and specify the external-service annotation with which, Citrix ingress controller creates DNS servers on NetScaler and binds the servers to the corresponding service group.
226+
227+
```yml
228+
apiVersion: networking.k8s.io/v1
229+
kind: Ingress
230+
metadata:
231+
name: dbs-ingress
232+
annotations:
233+
kubernetes.io/ingress.class: "cpx-ingress"
234+
# Special annotation to create DNS servers
235+
ingress.citrix.com/external-service: '{"external-svc": {"domain": "www.externalsvc.com"}}'
236+
spec:
237+
rules:
238+
- host: "www.portal.externalsvc.com"
239+
http:
240+
paths:
241+
- backend:
242+
service:
243+
name: my-external-service
244+
port:
245+
number: 30036
246+
path: /
247+
pathType: Prefix
248+
```
249+
250+
## Configuring Wildcard domains in NetScaler using Citrix ingress controller
251+
252+
Using the Wildcard DNS CRD, you can configure wildcard DNS domains on a Netscaler using Citrix Ingress Controller.
253+
The Wildcard DNS CRD is available in the Citrix ingress controller GitHub repo at [wildcarddnsentry.yaml](https://github.com/citrix/citrix-k8s-ingress-controller/blob/master/crd/wildcard-dns/wildcarddnsentry.yaml) . The Wildcard DNS CRD provides attributes for the various options that are required to configure wildcard DNS entries on NetScaler.
254+
255+
The following are the attributes provided in the Wildcard DNS CRD:
256+
257+
|Attribute |Description |
258+
|----------|-------------|
259+
|`domain` |Specifies the wild card domain name configured for the zone.|
260+
|`dnsaddrec`|Specifies the DNS Address record with the IPv4 address of the wildcard domain.|
261+
|`dnsaaaarec`|Specifies the DNS AAAA record with the IPV6 address of the wildcard domain.|
262+
|`soarec`|Specifies the SOA record configuration details.|
263+
|`nsrec`|Specifies the name server configuration details.|
264+
265+
### Deploying Wildcard DNS CRD
266+
267+
1. Deploy the Wildcard DNS CRD definition YAML from [Wildcard DNS YAML](https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/wildcard-dns/wildcarddnsentry.yaml)
268+
269+
kubectl create -f wildcarddns_spec.yaml
270+
271+
2. Update domain name, zone, DNS address record, AAAA record, SOA record and the NS record in the CRD instance and apply the configuration.
272+
273+
kubectl create -f wilcardddns_config.yaml
274+
275+
A sample YAML file definition that configures a SOA record, NS record, DNS zone, and address and AAAA Records on NetScaler.
276+
277+
```yml
278+
apiVersion: citrix.com/v1
279+
kind: wildcarddnsentry
280+
metadata:
281+
name: sample-config
282+
spec:
283+
zone:
284+
# Domain the wildcard domain name to configured on NetScaler
285+
domain: configexample.com
286+
# DNS address record to be configured on NetScaler with IP and ttl
287+
dnsaddrec:
288+
domain-ip: 1.1.1.1
289+
ttl: 3600
290+
# DNS AAAA record to be configured in Netscaler with IP and ttl
291+
dnsaaaarec:
292+
domain-ip: '2001::.1'
293+
ttl: 3600
294+
# DNS SOA record to be configured in NetScaler with origin-server name, admin contact information, retry count, expiry time, refresh time, etc
295+
soarec:
296+
origin-server: n2.configexample.com
297+
contact: admin.configexample.com
298+
serial: 100
299+
refresh: 3600
300+
retry: 3
301+
expire: 3600
302+
# DNS NS records to be configured in NetScaler with nameserver domain name and ttl
303+
nsrec:
304+
nameserver: n1.configexample.com
305+
ttl: 3600
306+
```
307+
308+
NetScaler Configuration:
309+
310+
```
311+
show soarec
312+
1) Domain Name : configexample.com ECS Subnet : None Origin Server : n2.configexample.com
313+
Contact : admin.configexample.com
314+
Serial No. : 100 Refresh : 3600 secs Retry : 3 secs
315+
Expire : 3600 secs Minimum : 5 secs TTL : 3600 secs
316+
Record Type : ADNS
317+
318+
show nsrec
319+
1) Domain : configexample.com ECS Subnet : None NameServer : n1.configexample.com
320+
TTL : 3600 sec Record Type : ADNS
321+
322+
show dns zone
323+
Zone Name : configexample.com
324+
Proxy Mode : NO
325+
DNSSEC Offload: DISABLED
326+
327+
show dns addrec
328+
1) Host Name : *.configexample.com ECS Subnet : None
329+
Record Type : ADNS TTL : 3600 secs
330+
IP Address : 1.1.1.1
331+
332+
show dns aaaarec
333+
1) Host Name : *.configexample.com ECS Subnet : None
334+
Record Type : ADNS TTL : 3600 secs
335+
IPV6 Address : 2001::1
336+
```
337+
338+
**Note:** For more information on configuring wildcard domain names in NetScaler, see [Supporting Wildcard Domains](https://docs.citrix.com/en-us/citrix-adc/current-release/dns/supporting-wildcard-dns-domains.html).

0 commit comments

Comments
 (0)