Merge pull request #1 from citrix/docs

Citrix k8s node controller documentation

Author: nirmalkn

README.md

@@ -10,26 +10,27 @@
 
 # Citrix k8s node controller
 
-Citrix k8s node controller is a micro service provided by Citrix that creates network between the Kubernetes cluster and ingress device. 
+Citrix k8s node controller is deployed as a pod in Kubernetes cluster that provides a network between the Kubernetes cluster and the Ingress Citrix ADC.
 
 >**Note:**
 >Citrix k8s node controller currently works only with flannel as the Container Network Interface (CNI). The scope of Citrix node controller can be extended to other CNI.
 
 ## Contents
 
--  [Overview](#overview)
--  [Architecture](#architecture)
--  [How it works](#how-it-works)
--  [Get started](#get-started)
--  [Issues](#issues)
--  [Code of conduct](#code-of-conduct)
--  [License](#License)
+  + [Overview](#Overview)
+  + [Architecture](#Architecture)
+  + [How it works](#How-it-works)
+  + [Get started](#Get-started)
+  + [Questions](#Questions)
+  + [Issues](#Issues)
+  + [Code of conduct](#Code-of-conduct)
+  + [License](#License)
 
 ## Overview
 
 In Kubernetes environments, when you expose the services for external access through the Ingress device, to route the traffic into the cluster, you need to appropriately configure the network between the Kubernetes nodes and the Ingress device. Configuring the network is challenging as the pods use private IP addresses based on the CNI framework. Without proper network configuration, the Ingress device cannot access these private IP addresses. Also, manually configuring the network to ensure such reachability is cumbersome in Kubernetes environments.
 
-Citrix provides a microservice called as **Citrix k8s node controller** that you can use to create the network between the cluster and the Ingress device.
+Citrix k8s node controller is deployed as a pod in Kubernetes cluster that provides a network between the Kubernetes cluster and the Ingress Citrix ADC.
 
 ## Architecture
 
@@ -64,26 +65,30 @@ The are the main components of the Citrix k8s node controller:
        </details>
        <details>
        <summary>**Config Maps**</summary>
-	    The **Config Maps** component controls the Citrix k8s node controller.  It allows you to define Citrix k8s node controller to automatically create, apply, and delete routing configuration on Citrix ADC.
+	    The **Config Maps** component controls the Citrix k8s node controller.  It allows you to define the Citrix k8s node controller to automatically create, apply, and delete routing configuration on Citrix ADC.
        </details>
 
 ## How it works
 
-Citrix k8s node controller monitors the node events and establishes a route between the node to Citrix ADC using VXLAN. Citrix k8s node controller adds route on the Citrix ADC when a new node joins to the cluster. Similarly when a node leaves the cluster, Citrix k8s node controller removes the associated route from the Citrix ADC. Citrix k8s node controller uses VXLAN overlay between the Kubernetes cluster and Citrix ADC for service routing.
+Citrix k8s node controller monitors the node events and establishes a route between the cluster nodes and Citrix ADC using VXLAN. Citrix k8s node controller adds a route on the Citrix ADC when a new node joins to the cluster. Similarly when a node leaves the cluster, Citrix k8s node controller removes the associated route from the Citrix ADC. Citrix k8s node controller uses VXLAN overlay between the Kubernetes cluster and Citrix ADC for service routing.
 
 ## Get started
 
 Citrix k8s node controller can be used in the following two ways:
 
--  In cluster Citrix k8s node controller configuration. In this configuration, the Citrix k8s node controller is run as **microservice**.
--  Out of the cluster Citrix k8s node controller configuration. In this configuration, the Citrix k8s node controller is run as a **process**.
+-  **Inside the cluster** - In this configuration, the Citrix k8s node controller is run as **pod**.
+-  **Outside the cluster** - In this configuration, the Citrix k8s node controller is run as a **process**.
 
 >**Important:**
->Citrix recommends that you use **In cluster configuration** for production. And, use the **Out of cluster configuration** for easy development.
+>Citrix recommends that you use **Inside the cluster** configuration for production. And, use the **Outside the cluster** configuration for development environments.
+
+### Using Citrix k8s node controller as a pod
+
+Refer the [deployment](deploy/README.md) page for running Citrix k8s node controller as a pod inside the Kubernetes cluster.
 
 ### Using Citrix k8s node controller as a process
 
-Before you deploy the citrix-k8s-node-controller` package, ensure that you have installed Go binary for running MIC.
+Before you deploy the citrix-k8s-node-controller package, ensure that you have installed [Go package](https://golang.org/doc/).
 
 Perform the following:
 
@@ -97,10 +102,6 @@ Perform the following:
 
         kubectl apply -f https://raw.githubusercontent.com/citrix/citrix-k8s-node-controller/master/deploy/config_map.yaml
 
-### Using Citrix k8s node controller as a microservice
-
-Refer the [deployment](deploy/README.md) page for running Citrix k8s node controller as a microservice inside the Kubernetes cluster.
-
 ## Questions
 
 For questions and support the following channels are available:

deploy/README.md

@@ -10,13 +10,6 @@ Citrix k8s node controller is controlled using a [config map](https://github.com
 [config_map.yaml](https://github.com/citrix/citrix-k8s-node-controller/blob/master/deploy/config_map.yaml):
 
 ```yaml
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: citrix
-  labels:
-    name: citrix
----
 kind: ConfigMap
 apiVersion: v1
 metadata:
@@ -44,19 +37,18 @@ Perform the following:
 
     -  Citrix Node Controller service (`citrix-node-controller`)
 
-    You don't have to modify the definitions for `ClusterRole`, `ClusterRoleBinding`, and `ServiceAccount` definitions. The definitions are used by Citrix node controller to monitor Kubernetes events. But, in the`citrix-node-controller` definition you have to provide the values for the environment variables that is required for Citrix k8s node controller to configure the Citric ADC.
+    You don't have to modify the definitions for `ClusterRole`, `ClusterRoleBinding`, and `ServiceAccount` definitions. The definitions are used by Citrix node controller to monitor Kubernetes events. But, in the`citrix-node-controller` definition you have to provide the values for the environment variables that is required for Citrix k8s node controller to configure the Citrix ADC.
 
     You must provide values for the following environment variables in the Citrix k8s node controller service definition:
 
     | Environment Variable | Mandatory or Optional | Description |
     | -------------------- | --------------------- | ----------- |
-    | NS_IP | Mandatory | Citrix k8s node controller uses this IP address to configure the Citrix ADC. The NS_IP can be anyone of the following: </br> - NSIP for standalone Citrix ADC </br>- SNIP for high availability deployments (Ensure that management access is enabled) </br> - CLIP for Cluster deployments |
+    | NS_IP | Mandatory | Citrix k8s node controller uses this IP address to configure the Citrix ADC. The NS_IP can be anyone of the following: </br>- SNIP for high availability and standalone deployments (Ensure that management access is enabled) </br> - CLIP for Cluster deployments |
     | NS_USER and NS_PASSWORD | Mandatory | The user name and password of Citrix ADC. Citrix k8s node controller uses these credentials to authenticate with Citrix ADC. You can either provide the user name and password or Kubernetes secrets. If you want to use a non-default Citrix ADC user name and password, you can [create a system user account in Citrix ADC](https://developer-docs.citrix.com/projects/citrix-k8s-ingress-controller/en/latest/deploy/deploy-cic-yaml/#create-system-user-account-for-citrix-ingress-controller-in-citrix-adc). </br> The deployment file uses Kubernetes secrets, create a secret for the user name and password using the following command: </br> `kubectl create secret  generic nslogin --from-literal=username='nsroot' --from-literal=password='nsroot'` </br> **Note**: If you want to use a different secret name other than `nslogin`, ensure that you update the `name` field in the `citrix-node-controller` definition. |
-    | NODE_CNI_CIDR | Mandatory | Provide the node [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) of the Kubernetes cluster.|
+    | NODE_CNI_CIDR | Mandatory | Provide the node [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) of the Kubernetes cluster. Use the following command to view the node CIDR: </br> `cat /run/flannel/subnet.env` </br> The node CIDR is displayed as `FLANNEL_NETWORK`.|
     | NS_POD_CIDR | Mandatory | Provide a pod CIDR from the node CIDR in the Kubernetes cluster to create an overlay network between Citrix ADC and Kubernetes cluster. </br> For example, if the node CIDR in the Kubernetes cluster is `10.244.0.0/16` and the pod CIDRs of the nodes are `10.244.0.1/24`, `10.244.1.1/24`, `10.244.2.1/24`. You can provide a pod CIDR `10.244.254.1/24` that is not allocated to the nodes.|
     | NS_VTEP_MAC | Mandatory | Provide [VMAC](https://docs.citrix.com/en-us/netscaler/12/system/high-availability-introduction/configuring-virtual-mac-addresses-high-availability.html) that you have configured on the Citrix ADC as an interface towards your Kubernetes cluster. |
     | NS_NETPROFILE | Mandatory | Provide the network profile (netprofile) name that you have used in the Citrix ingress controller.|
-    | NS_VTEP_IP | Optional | Use this argument to provide IP address as VTEP, if you do not want to use `NS_IP` |
     | NS_VXLAN_ID | Optional | This argument is only applicable for Flannel CNI. If Flannel uses a different `VXLAN_ID`, Use this argument to provide the `VXLAN_ID` |
     | K8S_VXLAN_PORT | Optional | If the Kubernetes cluster VXLAN port is other than 8472, you have to provide the Kubernetes VXLAN port number using this parameter. |
 

deploy/config_map.yaml

@@ -1,4 +1,3 @@
-apiVersion: v1
 kind: ConfigMap
 apiVersion: v1
 metadata: