Make needed changes to the getting started guide for CLC

based on comments in PR  126

_data/guides.yml

@@ -45,6 +45,8 @@ toc:
       path: /docs/getting-started-guides/aws/
     - title: Running Kubernetes on Azure
       path: /docs/getting-started-guides/coreos/azure/
+    - title: Running Kubernetes on CenturyLink Cloud
+      path: /docs/getting-started-guides/clc/
   - title: Running Kubernetes on Custom Solutions
     section:
     - title: Getting Started From Scratch

docs/getting-started-guides/clc.md

@@ -1,21 +1,28 @@
-# Kubernetes on CenturyLink Cloud
+---
+---
+* TOC
+{: toc}
+
 These scripts handle the creation, deletion and expansion of kubernetes clusters on CenturyLink Cloud.
 
-You can accomplish all these tasks with a simple single command. And, for those interested in what's under the covers, we used Ansible to perform these tasks and we have made these Ansible playbooks available as well.
+You can accomplish all these tasks with a single command. We have made the Ansible playbooks used to perform these tasks available [here](https://github.com/CenturyLinkCloud/adm-kubernetes-on-clc/blob/master/ansible/README.md).
 
 ## Find Help
+
 If you run into any problems or want help with anything, we are here to help. Reach out to use via any of the following ways:
 - Submit a github issue
 - Send an email to kubernetes AT ctl DOT io
 - Visit http://info.ctl.io/kubernetes
 
 ## Clusters of VMs or Physical Servers, your choice.
+
 - We support Kubernetes clusters on both Virtual Machines or Physical Servers. If you want to use physical servers for the worker nodes (minions), simple use the --minion_type=bareMetal flag.
 - For more information on physical servers, visit: [https://www.ctl.io/bare-metal/](https://www.ctl.io/bare-metal/))
 - Physical serves are only available in the VA1 and GB3 data centers.
 - VMs are available in all 13 of our public cloud locations
 
 ## Requirements
+
 The requirements to run this script are:
 - A linux administrative host (tested on ubuntu and OSX)
 - python 2 (tested on 2.7.11)
@@ -25,11 +32,12 @@ The requirements to run this script are:
 - An active VPN connection to the CenturyLink Cloud from your linux host
 
 ## Script Installation
+
 After you have all the requirements met, please follow these instructions to install this script.
 
 1) Clone this repository and cd into it.
 
-```
+```shell
 git clone https://github.com/CenturyLinkCloud/adm-kubernetes-on-clc
 ```
 
@@ -38,23 +46,20 @@ git clone https://github.com/CenturyLinkCloud/adm-kubernetes-on-clc
   * CenturyLink Cloud SDK
   * Ansible Modules
 
-```
+```shell
 sudo pip install -r ansible/requirements.txt
 ```
 
 3) Create the credentials file from the template and use it to set your ENV variables
 
-```
+```shell
 cp ansible/credentials.sh.template ansible/credentials.sh
 vi ansible/credentials.sh
 source ansible/credentials.sh
 
 ```
 
-4) Make sure the computer you are working on has access to the CenturyLink Cloud
+4) Grant your machine access to the CenturyLink Cloud network by using a VM inside the network or [ configuring a VPN connection to the CenturyLink Cloud network.](https://www.ctl.io/knowledge-base/network/how-to-configure-client-vpn/)
-network. This is done by using a VM inside the CenturyLink Cloud network or
-having an active VPN connection to the CenturyLink Cloud network. To find out
-how to configure the VPN connection, [visit here](https://www.ctl.io/knowledge-base/network/how-to-configure-client-vpn/)
 
 
 #### Script Installation Example: Ubuntu 14 Walkthrough
@@ -62,7 +67,7 @@ how to configure the VPN connection, [visit here](https://www.ctl.io/knowledge-b
 If you use an ubuntu 14, for your convenience we have provided a step by step
 guide to install the requirements and install the script.
 
-```
+```shell
   # system
   apt-get update
   apt-get install -y git python python-crypto
@@ -89,7 +94,7 @@ guide to install the requirements and install the script.
 To create a new Kubernetes cluster, simply run the kube-up.sh script. A complete
 list of script options and some examples are listed below.
 
-```
+```shell
 CLC_CLUSTER_NAME=[name of kubernetes cluster]
 cd ./adm-kubernetes-on-clc
 bash kube-up.sh -c="$CLC_CLUSTER_NAME"
@@ -100,14 +105,16 @@ will output some commands that will help you setup kubectl on your machine to
 point to the new cluster.
 
 When the cluster creation is complete, the configuration files for it are stored
-locally on your administrative host, in the directory
+locally on your administrative host, in the following directory
 
+```shell
 > CLC_CLUSTER_HOME=$HOME/.clc_kube/$CLC_CLUSTER_NAME/
+```
 
 
 #### Cluster Creation: Script Options
 
-```
+```shell
 Usage: kube-up.sh [OPTIONS]
 Create servers in the CenturyLinkCloud environment and initialize a Kubernetes cluster
 Environment variables CLC_V2_API_USERNAME and CLC_V2_API_PASSWD must be set in
@@ -133,19 +140,19 @@ between option name and option value.
 
 ## Cluster Expansion
 
-To expand an existing Kubernetes cluster, run the add-kube-node.sh
+To expand an existing Kubernetes cluster, run the ```add-kube-node.sh```
-script. A complete list of script options and some examples are listed below.
+script. A complete list of script options and some examples are listed [[below]](####Cluster Expansion: Script Options).
-This script must be run from the same hose that created the cluster (or a host
+This script must be run from the same host that created the cluster (or a host
-that has the cluster artifact files stored in ~/.clc_kube/$cluster_name).
+that has the cluster artifact files stored in ```~/.clc_kube/$cluster_name```).
 
-```
+```shell
 cd ./adm-kubernetes-on-clc
 bash add-kube-node.sh -c="name_of_kubernetes_cluster" -m=2
 ```
 
 #### Cluster Expansion: Script Options
 
-```
+```shell
 Usage: add-kube-node.sh [OPTIONS]
 Create servers in the CenturyLinkCloud environment and add to an
 existing CLC kubernetes cluster
@@ -160,11 +167,12 @@ order to access the CenturyLinkCloud API
 ```
 
 ## Cluster Deletion
+
 There are two ways to delete an existing cluster:
 
 1) Use our python script:
 
-```
+```shell
 python delete_cluster.py --cluster=clc_cluster_name --datacenter=DC1
 
 ```
@@ -174,27 +182,29 @@ Cloud control portal and delete the parent server group that contains the
 Kubernetes Cluster. We hope to add a scripted option to do this soon.
 
 ## Examples
+
 Create a cluster with name of k8s_1, 1 master node and 3 worker minions (on physical machines), in VA1
 
-```
+```shell
  bash kube-up.sh --clc_cluster_name=k8s_1 --minion_type=bareMetal --minion_count=3 --datacenter=VA1
 ```
 
 Create a cluster with name of k8s_2, an ha etcd cluster on 3 VMs and 6 worker minions (on VMs), in VA1
 
-```
+```shell
  bash kube-up.sh --clc_cluster_name=k8s_2 --minion_type=standard --minion_count=6 --datacenter=VA1 --etcd_separate_cluster=yes
 ```
 
 Create a cluster with name of k8s_3, 1 master node, and 10 worker minions (on VMs) with higher mem/cpu, in UC1:
 
-```
+```shell
   bash kube-up.sh --clc_cluster_name=k8s_3 --minion_type=standard --minion_count=10 --datacenter=VA1 -mem=6 -cpu=4
 ```
 
 
 
 ## Cluster Features and Architecture
+
 We configue the Kubernetes cluster with the following features:
 
 * KubeDNS: DNS resolution and service discovery
@@ -215,24 +225,24 @@ We use the following to create the kubernetes cluster:
 
 * Logging: We offer an integrated centralized logging ELK platform so that all
   kubernetes and docker logs get sent to the ELK stack. To install the ELK stack
-  and configure kubernetes to send logs to it, follow this documentation: [log
+  and configure Kubernetes to send logs to it, follow [the log
-  aggregation](log_aggregration.md). Note: We don't install this by default as
+  aggregation documentation](https://github.com/CenturyLinkCloud/adm-kubernetes-on-clc/blob/master/log_aggregration.md). Note: We don't install this by default as
   the footprint isn't trivial.
 
 ## Cluster management
 
 The most widely used tool for managing a kubernetes cluster is the command-line
-utility _kubectl_.  If you do not already have a copy of this binary on your
+utility ```kubectl```.  If you do not already have a copy of this binary on your
-administrative machine, you may run the script _install_kubectl.sh_ which will
+administrative machine, you may run the script ```install_kubectl.sh``` which will
-download it and install it in _/usr/bin/local_.
+download it and install it in ```/usr/bin/local```.
 
-The script requires that the environment variable CLC_CLUSTER_NAME be defined
+The script requires that the environment variable ```CLC_CLUSTER_NAME``` be defined
 
-_install_kubectl.sh_ also writes a configuration file which will embed the necessary
+```install_kubectl.sh``` also writes a configuration file which will embed the necessary
 authentication certificates for the particular cluster.  The configuration file is
-written to the  ${CLC_CLUSTER_HOME}/kube directory
+written to the  ```${CLC_CLUSTER_HOME}/kube``` directory
 
-```
+```shell
 export KUBECONFIG=${CLC_CLUSTER_HOME}/kube/config
 kubectl version
 kubectl cluster-info
@@ -240,78 +250,85 @@ kubectl cluster-info
 
 ### Accessing the cluster programmatically 
 
-It's possible to use the locally-stored client certificates to access the api server
+It's possible to use the locally-stored client certificates to access the api server. For example, you may want to use any of the [Kubernetes API client libraries](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/client-libraries.md) to program against your Kubernetes cluster in the programming language of your choice. 
-```
+
+To demostrate how to use these locally stored certificates, we provide the folowing example of using ```curl``` to communicate to the master api server via https:
+
+```shell
 curl \
    --cacert ${CLC_CLUSTER_HOME}/pki/ca.crt  \
    --key ${CLC_CLUSTER_HOME}/pki/kubecfg.key \
    --cert ${CLC_CLUSTER_HOME}/pki/kubecfg.crt  https://${MASTER_IP}:6443
 ```
-But please note, this *does not* work out of the box with the curl binary
+
-distributed with OSX
+But please note, this *does not* work out of the box with the ```curl``` binary
+distributed with OSX.
 
 ### Accessing the cluster with a browser
 
-We install two UIs on kubernetes. The orginal KubeUI and the newer kube
+We install two UIs on Kubernetes. The orginal KubeUI and [the newer kube
-dashboard. When you create a cluster, the script should output URLs for these
+dashboard](/docs/user-guide/ui/). When you create a cluster, the script should output URLs for these
 interfaces like this:
 
-KubeUI is running at https://${MASTER_IP}:6443/api/v1/proxy/namespaces/kube-system/services/kube-ui
+KubeUI is running at ```https://${MASTER_IP}:6443/api/v1/proxy/namespaces/kube-system/services/kube-ui```
-kubernetes-dashboard is running at https://${MASTER_IP}:6443/api/v1/proxy/namespaces/kube-system/services/kubernetes-dashboard
+kubernetes-dashboard is running at ```https://${MASTER_IP}:6443/api/v1/proxy/namespaces/kube-system/services/kubernetes-dashboard```
 
 Note on Authentication to the UIs: The cluster is set up to use basic
 authentication for the user _admin_.   Hitting the url at
-https://${MASTER_IP}:6443 will require accepting the self-signed certificate
+```https://${MASTER_IP}:6443``` will require accepting the self-signed certificate
-from the apiserver, and then presenting the admin password written to file at
+from the apiserver, and then presenting the admin password written to file at:
 
-> _${CLC_CLUSTER_HOME}/kube/admin_password.txt_
+```> _${CLC_CLUSTER_HOME}/kube/admin_password.txt_```
 
 
 ### Configuration files
 
 Various configuration files are written into the home directory *CLC_CLUSTER_HOME* under
-_.clc_kube/${CLC_CLUSTER_NAME}_ in several subdirectories. You can use these files
+```.clc_kube/${CLC_CLUSTER_NAME}``` in several subdirectories. You can use these files
 to access the cluster from machines other than where you created the cluster from.
 
-* _config/_: ansible variable files containing parameters describing the master and minion hosts
+* ```config/```: Ansible variable files containing parameters describing the master and minion hosts
-* _hosts/_: hosts files listing access information for the ansible playbooks
+* ```hosts/```: hosts files listing access information for the ansible playbooks
-* _kube/_: kubectl configuration files, and the basic-authentication password for admin access to the kubernetes api
+* ```kube/```: ```kubectl``` configuration files, and the basic-authentication password for admin access to the Kubernetes API
-* _pki/_: public key infrastructure files enabling TLS communication in the cluster
+* ```pki/```: public key infrastructure files enabling TLS communication in the cluster
-* _ssh/_: ssh keys for root access to the hosts
+* ```ssh/```: SSH keys for root access to the hosts
 
 
-## _kubectl_ usage examples
+## ```kubectl``` usage examples
 
 There are a great many features of _kubectl_.  Here are a few examples
 
-List existing nodes, pods, services and more, in all namespaces, or in just one
+List existing nodes, pods, services and more, in all namespaces, or in just one:
-```
+
+```shell
 kubectl get nodes
-
 kubectl get --all-namespaces services
-
 kubectl get --namespace=kube-system replicationcontrollers
-
 ```
 
-The kubernetes api server exposes services on web urls, which are protected by requiring
+The Kubernetes API server exposes services on web URLs, which are protected by requiring
-client certificates.  If you run a kubectl proxy locally, kubectl will provide
+client certificates.  If you run a kubectl proxy locally, ```kubectl``` will provide
 the necessary certificates and serve locally over http.
-```
+
+```shell
 kubectl proxy -p 8001
 ```
-and then access urls like http://127.0.0.1:8001/api/v1/proxy/namespaces/kube-system/services/kube-ui/
+
-without the need for client certificates in your browser.
+Then, you can access urls like ```http://127.0.0.1:8001/api/v1/proxy/namespaces/kube-system/services/kube-ui/``` without the need for client certificates in your browser.
 
 
 ## What Kubernetes features do not work on CenturyLink Cloud
 
-- At this time, there is no support services of the type 'loadbalancer'. We are
+These are the known items that don't work on CenturyLink cloud but do work on other cloud providers:
-  actively working on this and hope to publish the changes soon.
+
+- At this time, there is no support services of the type [LoadBalancer](/docs/user-guide/load-balancer/). We are actively working on this and hope to publish the changes sometime around April 2016.
+
 - At this time, there is no support for persistent storage volumes provided by
   CenturyLink Cloud. However, customers can bring their own persistent storage
   offering. We ourselves use Gluster.
 
-## Ansible Files
+
-If you want more information about our ansible files, please [read this file](https://github.com/CenturyLinkCloud/adm-kubernetes-on-clc/blob/master/ansible/README.md)
+## Ansible Files
+
+If you want more information about our Ansible files, please [read this file](https://github.com/CenturyLinkCloud/adm-kubernetes-on-clc/blob/master/ansible/README.md)