Merge pull request #594 from citrix/cic-1.34.16-updates

added the external name service support

Author: sreejithgs

docs/how-to/extenal-name-service-support.md

@@ -0,0 +1,57 @@
+# Support for external name service across namespaces
+
+Namespaces are used to isolate resources within a Kubernetes cluster. Sometimes, services in a different namespace might have to access a service located in another namespace. In such scenarios, you can use the `ExternalName` service provided by Kubernetes. An `ExternalName` service is a special service that does not have selectors and instead uses DNS names.
+
+In the service definition, the `externalName` field must point to the namespace and also to the service which we are trying to access on that namespace. Citrix ingress controller supports services of type `ExternalName` when you have to access services within the cluster.
+
+When you create the `ExternalName` service, the following criteria must be met:
+
+-  The `externalName` field in the service definition must follow the format:
+    `svc: <name-of-the-service>.<namespace-of-the-service>.svc.cluster.local`
+-  The port number in the `ExternalName` service must exactly match the port number of the targetted service.
+
+**Note:**
+ When the service of an application is outside the Kubernetes cluster and you have created an `ExternalName` service, you can resolve the domain name using the [Traffic management for external services feature](https://docs.netscaler.com/en-us/citrix-k8s-ingress-controller/how-to/external-load-balance-adc.html).
+
+## Sample ExternalName service
+
+In this example, a `mysql` service is running in the default namespace and a sample `ExternalName` service is created to access the `mysql` service from the `namespace1` namespace.
+
+The following is a sample service definition for a MySQL service running in the default namespace.
+
+```yml
+apiVersion: v1
+kind: Service
+metadata:
+  name: mysql
+  namespace: default
+spec:
+  clusterIP: None
+  ports:
+  - port: 3306
+    protocol: TCP
+    targetPort: 3306
+  selector:
+    app: mysql
+  type: ClusterIP
+
+```
+
+The following is a sample `ExternalName` service definition to access the `mysql` service from the `namespace1` namespace.
+
+```yml
+kind: Service
+apiVersion: v1
+metadata:
+  name: dbservice
+  namespace: namespace1
+spec:
+  type: ExternalName
+  externalName: mysql.default.svc.cluster.local
+  ports:
+  - port: 3306 
+    protocol: TCP
+    targetPort: 3306
+```
+
+In the example, the service points to the namespace where `mysql` is deployed as specified in the field `externalName: mysql.default.svc.cluster.local`. Here `mysql` is the service name and `default` is the namespace. You can see that the port name is also the same as the `mysql` service.