From 11dc763bbb3f91b34a1dd53523dfb5c814999bf3 Mon Sep 17 00:00:00 2001 From: Charles Butler Date: Tue, 29 Mar 2016 10:54:35 -0400 Subject: [PATCH 1/5] Work done yesterday --- docs/getting-started-guides/juju.md | 114 +++++++++++++--------------- 1 file changed, 53 insertions(+), 61 deletions(-) diff --git a/docs/getting-started-guides/juju.md b/docs/getting-started-guides/juju.md index a2ec08615d..73d42b1647 100644 --- a/docs/getting-started-guides/juju.md +++ b/docs/getting-started-guides/juju.md @@ -17,42 +17,46 @@ to increase the cluster size. ### On Ubuntu -[Install the Juju client](https://jujucharms.com/get-started) on your -local Ubuntu system: +[Install the Juju client](https://jujucharms.com/get-started) + +> This documentation focuses on the juju 2.0 release which will be +> promoted to stable during its release cycle in April + +To paraphrase, on your local Ubuntu system: ```shell -sudo add-apt-repository ppa:juju/stable +sudo add-apt-repository ppa:juju/devel sudo apt-get update -sudo apt-get install juju-core juju-quickstart +sudo apt-get install juju2 ``` +If you are using another distro/platform - please consult the +[getting started guide](https://jujucharms.com/get-started) to install the +Juju dependencies for your platform. + ### With Docker +> While this is a common target, the charmbox flavors of images are +> unofficial, and should be treated as Experimental. If you encounter any issues +> turning up the Kubernetes cluster with charmbox, please file a bug on the +> respective issue tracker [here](https://github.com/juju-solutions/charmbox/issues) + If you are not using Ubuntu or prefer the isolation of Docker, you may run the following: ```shell -mkdir ~/.juju -sudo docker run -v ~/.juju:/home/ubuntu/.juju -ti jujusolutions/jujubox:latest +mkdir ~/.juju2 +sudo docker run -v ~/.juju2:/home/ubuntu/.local/share/juju -ti jujusolutions/charmbox:devel ``` At this point from either path you will have access to the `juju -quickstart` command. +bootstrap` command. However we will need to configure the credentials for the + Juju cloud provider before we can proceed. -To set up the credentials for your chosen cloud run: - -```shell -juju quickstart --constraints="mem=3.75G" -i -``` - -> The `constraints` flag is optional, it changes the size of virtual machines -> that Juju will generate when it requests a new machine. Larger machines -> will run faster but cost more money than smaller machines. - -Follow the dialogue and choose `save` and `use`. Quickstart will now -bootstrap the juju root node and setup the juju web based user -interface. +To set up the credentials for your chosen cloud see the [cloud setup docs](https://jujucharms.com/docs/devel/getting-started#2.-choose-a-cloud): +Once your cloud has been bootstrapped via: +`juju bootstrap $cloudname $cloudtype` you are ready to launch the cluster. ## Launch Kubernetes cluster @@ -64,14 +68,12 @@ export KUBERNETES_PROVIDER=juju cluster/kube-up.sh ``` -If this is your first time running the `kube-up.sh` script, it will install -the required dependencies to get started with Juju, additionally it will -launch a curses based configuration utility allowing you to select your cloud -provider and enter the proper access credentials. +If this is your first time running the `kube-up.sh` script, it will attempt to +install the required dependencies to get started with Juju. -Next it will deploy the kubernetes master, etcd, 2 nodes with flannel based -Software Defined Networking (SDN) so containers on different hosts can -communicate with each other. +Next it will deploy the kubernetes application, 3 units of etcd, and network +the units with flannel based Software Defined Networking (SDN) so containers +on different hosts can communicate with each other. ## Exploring the cluster @@ -80,28 +82,33 @@ The `juju status` command provides information about each unit in the cluster: ```shell $ juju status --format=oneline -- docker/0: 52.4.92.78 (started) - - flannel-docker/0: 52.4.92.78 (started) - - kubernetes/0: 52.4.92.78 (started) -- docker/1: 52.6.104.142 (started) - - flannel-docker/1: 52.6.104.142 (started) - - kubernetes/1: 52.6.104.142 (started) -- etcd/0: 52.5.216.210 (started) 4001/tcp -- juju-gui/0: 52.5.205.174 (started) 80/tcp, 443/tcp -- kubernetes-master/0: 52.6.19.238 (started) 8080/tcp + +... (snipped for brevity) + +[Units] +ID WORKLOAD-STATE AGENT-STATE VERSION MACHINE PORTS PUBLIC-ADDRESS MESSAGE +etcd/0 active idle 2.0-beta2 1 54.146.50.29 Etcd leader running +kubernetes/0 active idle 2.0-beta2 2 6443/tcp,8088/tcp 54.205.204.227 Kubernetes follower running +kubernetes/1 active idle 2.0-beta2 3 6443/tcp,8088/tcp 54.145.57.114 Kubernetes leader running + +... (snipped for brevity) ``` -You can use `juju ssh` to access any of the units: - -```shell -juju ssh kubernetes-master/0 -``` ## Run some containers! -`kubectl` is available on the Kubernetes master node. We'll ssh in to -launch some containers, but one could use `kubectl` locally by setting -`KUBERNETES_MASTER` to point at the ip address of "kubernetes-master/0". +`kubectl` is available on the Kubernetes leader node. We'll fetch the kubectl +command, and execute some queries against our newly stood up cluster. + + +```shell +juju scp kubernetes/1:kubectl_package.tar.gz . +tar xvfz kubectl_package.tar.gz +``` + +If you are not on a linux amd64 host system, you will need to fetch a kubectl + + No pods will be available before starting a container: @@ -178,7 +185,7 @@ curl $(juju status --format=oneline kubernetes/1 | cut -d' ' -f3) Finally delete the pod: ```shell -juju ssh kubernetes-master/0 +juju ssh kubernetes/0 kubectl delete pods hello ``` @@ -187,21 +194,9 @@ kubectl delete pods hello We can add node units like so: ```shell -juju add-unit docker # creates unit docker/2, kubernetes/2, docker-flannel/2 +juju add-unit kubernetes ``` -## Launch the "k8petstore" example app - -The [k8petstore example](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/k8petstore/) is available as a -[juju action](https://jujucharms.com/docs/devel/actions). - -```shell -juju action do kubernetes-master/0 -``` - -> Note: this example includes curl statements to exercise the app, which -> automatically generates "petstore" transactions written to redis, and allows -> you to visualize the throughput in your browser. ## Tear down cluster @@ -243,6 +238,3 @@ works with [Amazon Web Service](https://jujucharms.com/docs/stable/config-aws), If you do not see your favorite cloud provider listed many clouds can be configured for [manual provisioning](https://jujucharms.com/docs/stable/config-manual). - -The Kubernetes bundle has been tested on GCE and AWS and found to work with -version 1.0.0. \ No newline at end of file From fd125f229d7920aad069720fc5d2c7911e179f94 Mon Sep 17 00:00:00 2001 From: Matt Bruzek Date: Tue, 29 Mar 2016 11:12:14 -0500 Subject: [PATCH 2/5] Adding my thoughts on the juju getting started doc. --- docs/getting-started-guides/juju.md | 64 ++++++++++++++++++----------- 1 file changed, 41 insertions(+), 23 deletions(-) diff --git a/docs/getting-started-guides/juju.md b/docs/getting-started-guides/juju.md index 73d42b1647..445f73ce66 100644 --- a/docs/getting-started-guides/juju.md +++ b/docs/getting-started-guides/juju.md @@ -36,27 +36,32 @@ Juju dependencies for your platform. ### With Docker +If you are not using Ubuntu or prefer the isolation of Docker, you may +run the following: + > While this is a common target, the charmbox flavors of images are > unofficial, and should be treated as Experimental. If you encounter any issues > turning up the Kubernetes cluster with charmbox, please file a bug on the > respective issue tracker [here](https://github.com/juju-solutions/charmbox/issues) -If you are not using Ubuntu or prefer the isolation of Docker, you may -run the following: - ```shell mkdir ~/.juju2 sudo docker run -v ~/.juju2:/home/ubuntu/.local/share/juju -ti jujusolutions/charmbox:devel ``` -At this point from either path you will have access to the `juju -bootstrap` command. However we will need to configure the credentials for the - Juju cloud provider before we can proceed. +### Configure Juju to point a cloud -To set up the credentials for your chosen cloud see the [cloud setup docs](https://jujucharms.com/docs/devel/getting-started#2.-choose-a-cloud): +At this point you have access to the Juju client. If you wish to use a cloud, +you need to configure the credentials for the Juju cloud provider. -Once your cloud has been bootstrapped via: -`juju bootstrap $cloudname $cloudtype` you are ready to launch the cluster. +Juju supports a wide variety of public clouds to set up the credentials for +your chosen cloud see the +[cloud setup page](https://jujucharms.com/docs/devel/getting-started#2.-choose-a-cloud). + +After configuration is complete test your setup with a `juju bootstrap` +command: +`juju bootstrap $cloudname $cloudtype` you are ready to launch the +Kubernetes cluster. ## Launch Kubernetes cluster @@ -75,15 +80,14 @@ Next it will deploy the kubernetes application, 3 units of etcd, and network the units with flannel based Software Defined Networking (SDN) so containers on different hosts can communicate with each other. - ## Exploring the cluster The `juju status` command provides information about each unit in the cluster: ```shell -$ juju status --format=oneline +$ juju status -... (snipped for brevity) +... (omitted for brevity) [Units] ID WORKLOAD-STATE AGENT-STATE VERSION MACHINE PORTS PUBLIC-ADDRESS MESSAGE @@ -91,24 +95,29 @@ etcd/0 active idle 2.0-beta2 1 54.1 kubernetes/0 active idle 2.0-beta2 2 6443/tcp,8088/tcp 54.205.204.227 Kubernetes follower running kubernetes/1 active idle 2.0-beta2 3 6443/tcp,8088/tcp 54.145.57.114 Kubernetes leader running -... (snipped for brevity) +... (omitted for brevity) ``` - ## Run some containers! -`kubectl` is available on the Kubernetes leader node. We'll fetch the kubectl -command, and execute some queries against our newly stood up cluster. +The `kubectl` file, the TLS certificates along with the configuration are +all available on the Kubernetes leader unit. Fetch the kubectl package so you +can run commands on the new Kuberntetes cluster. +Use the `juju status` command to figure out which Kubernetes unit is the leader +and copy the file from the leader: ```shell juju scp kubernetes/1:kubectl_package.tar.gz . tar xvfz kubectl_package.tar.gz +kubectl --config config get pods ``` -If you are not on a linux amd64 host system, you will need to fetch a kubectl - +If you are not on a Linux amd64 host system, you will need to find or build a +kubectl binary package for your architecture. +Put the config file in the home directory so you don't have to specify it on +the command line each time. The default location is `${HOME}/.kube/config`. No pods will be available before starting a container: @@ -159,8 +168,7 @@ kubectl get pods ``` To test the hello app, we need to locate which node is hosting -the container. Better tooling for using Juju to introspect container -is in the works but we can use `juju run` and `juju status` to find +the container. We can use `juju run` and `juju status` commands to find our hello app. Exit out of our ssh session and run: @@ -197,23 +205,33 @@ We can add node units like so: juju add-unit kubernetes ``` +Or multiple units at one time: + +```shell +juju add-unit -n3 kubernetes +``` + ## Tear down cluster +We recommend that you use the `kube-down.sh` command when you are done using +the cluster, as it properly brings down the cloud and removes some of the +build directories. + ```shell ./kube-down.sh ``` -or destroy your current Juju environment (using the `juju env` command): +If you want stop the servers you can destroy your current Juju environment +(using the `juju env` command): ```shell juju destroy-environment --force `juju env` ``` - ## More Info -The Kubernetes charms and bundles can be found in the `kubernetes` project on +The Kubernetes charms and bundleso can be found in the `kubernetes` project on github.com: - [Bundle Repository](http://releases.k8s.io/{{page.githubbranch}}/cluster/juju/bundles) From 799f0846454670582ede2f24db1334e87c51b192 Mon Sep 17 00:00:00 2001 From: Matt Bruzek Date: Tue, 29 Mar 2016 11:28:14 -0500 Subject: [PATCH 3/5] Added more words at the bottom and layer reference. --- docs/getting-started-guides/juju.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/getting-started-guides/juju.md b/docs/getting-started-guides/juju.md index 445f73ce66..ac5ad8f014 100644 --- a/docs/getting-started-guides/juju.md +++ b/docs/getting-started-guides/juju.md @@ -211,7 +211,6 @@ Or multiple units at one time: juju add-unit -n3 kubernetes ``` - ## Tear down cluster We recommend that you use the `kube-down.sh` command when you are done using @@ -231,12 +230,16 @@ juju destroy-environment --force `juju env` ## More Info -The Kubernetes charms and bundleso can be found in the `kubernetes` project on -github.com: +Juju works with charms and bundles to deploy solutions. The code that stands up +a Kubernetes cluster is done in the charm code. The charm is built from using +a layered approach to keep the code smaller and more focused on the operations +of Kubernetes. - - [Bundle Repository](http://releases.k8s.io/{{page.githubbranch}}/cluster/juju/bundles) - * [Kubernetes master charm](https://releases.k8s.io/{{page.githubbranch}}/cluster/juju/charms/trusty/kubernetes-master) - * [Kubernetes node charm](https://releases.k8s.io/{{page.githubbranch}}/cluster/juju/charms/trusty/kubernetes) +The Kubernetes layer and bundles can be found in the `kubernetes` +project on github.com: + + - [Bundle location](https://github.com/kubernetes/kubernetes/tree/master/cluster/juju/bundles) + - [Kubernetes charm layer location](https://github.com/kubernetes/kubernetes/tree/master/cluster/juju/layers/kubernetes) - [More about Juju](https://jujucharms.com) @@ -254,5 +257,11 @@ works with [Amazon Web Service](https://jujucharms.com/docs/stable/config-aws), [Vagrant](https://jujucharms.com/docs/stable/config-vagrant), and [Vmware vSphere](https://jujucharms.com/docs/stable/config-vmware). -If you do not see your favorite cloud provider listed many clouds can be -configured for [manual provisioning](https://jujucharms.com/docs/stable/config-manual). +If you do not see your favorite cloud provider listed many clouds with ssh +access can be configured for +[manual provisioning](https://jujucharms.com/docs/stable/config-manual). + +The Juju Kubernetes work is curated by a very small group of community members. +Let us know how we are doing. If you find any problems please open an +[issue at the kubernetes project](https://github.com/kubernetes/kubernetes/issues) +and tag it with "juju" so we can find it. From a0dc91ccb5dec0efb758a0c28293583a073bd60d Mon Sep 17 00:00:00 2001 From: Matt Bruzek Date: Tue, 29 Mar 2016 16:17:36 -0500 Subject: [PATCH 4/5] Addressing review comments from @chuckbutler. --- docs/getting-started-guides/juju.md | 39 ++++++++++++++++++----------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/getting-started-guides/juju.md b/docs/getting-started-guides/juju.md index ac5ad8f014..82bdc93042 100644 --- a/docs/getting-started-guides/juju.md +++ b/docs/getting-started-guides/juju.md @@ -3,9 +3,15 @@ [Juju](https://jujucharms.com/docs/stable/about-juju) makes it easy to deploy Kubernetes by provisioning, installing and configuring all the systems in -the cluster. Once deployed the cluster can easily scale up with one command +the cluster. Once deployed the cluster can easily scale up with one command to increase the cluster size. +The Juju Kubernetes work is curated by a very small group of community members. +Let us know how we are doing. If you find any problems please open an +[issue at the kubernetes project](https://github.com/kubernetes/kubernetes/issues) +and tag the issue with "juju" so we can find them. + + * TOC {:toc} @@ -51,11 +57,11 @@ sudo docker run -v ~/.juju2:/home/ubuntu/.local/share/juju -ti jujusolutions/cha ### Configure Juju to point a cloud -At this point you have access to the Juju client. If you wish to use a cloud, -you need to configure the credentials for the Juju cloud provider. +At this point you have access to the Juju client. Before you can deploy a +cluster you have to configure the credentials for the Juju cloud provider. -Juju supports a wide variety of public clouds to set up the credentials for -your chosen cloud see the +Juju [supports a wide variety of public clouds](#Cloud-compatibility) to set +up the credentials for your chosen cloud see the [cloud setup page](https://jujucharms.com/docs/devel/getting-started#2.-choose-a-cloud). After configuration is complete test your setup with a `juju bootstrap` @@ -110,7 +116,7 @@ and copy the file from the leader: ```shell juju scp kubernetes/1:kubectl_package.tar.gz . tar xvfz kubectl_package.tar.gz -kubectl --config config get pods +kubectl --kubeconfig config get pods ``` If you are not on a Linux amd64 host system, you will need to find or build a @@ -196,10 +202,18 @@ Finally delete the pod: juju ssh kubernetes/0 kubectl delete pods hello ``` +## Scale up cluster + +Whant larger kubernetes nodes? It is easy to request different sizes of cloud +resources from Juju by using **constraints**. You can increase the amount of +CPU or memory (RAM) in any of the systems requested by Juju. This allows you +to fine tune th Kubernetes cluster to fit your workload. Use the boostrap +command or as a seperate `juju constraints` command. Look to the +[Juju documentation for machine constraints](https://jujucharms.com/docs/devel/charms-constraints). ## Scale out cluster -We can add node units like so: +Need more clusters? Juju makes it easy to add units of a charm: ```shell juju add-unit kubernetes @@ -221,11 +235,11 @@ build directories. ./kube-down.sh ``` -If you want stop the servers you can destroy your current Juju environment -(using the `juju env` command): +Alternately if you want stop the servers you can destroy your current Juju environment. +Use the `juju env` command to get the current environment name: ```shell -juju destroy-environment --force `juju env` +juju kill-controller `juju env` ``` ## More Info @@ -260,8 +274,3 @@ works with [Amazon Web Service](https://jujucharms.com/docs/stable/config-aws), If you do not see your favorite cloud provider listed many clouds with ssh access can be configured for [manual provisioning](https://jujucharms.com/docs/stable/config-manual). - -The Juju Kubernetes work is curated by a very small group of community members. -Let us know how we are doing. If you find any problems please open an -[issue at the kubernetes project](https://github.com/kubernetes/kubernetes/issues) -and tag it with "juju" so we can find it. From 8ac73e38a1b96aaac54a3ea7eb8c334fdcbd9478 Mon Sep 17 00:00:00 2001 From: Matt Bruzek Date: Wed, 30 Mar 2016 08:38:23 -0500 Subject: [PATCH 5/5] Spelling and other formatting changes. --- docs/getting-started-guides/juju.md | 47 +++++++++++++++-------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/getting-started-guides/juju.md b/docs/getting-started-guides/juju.md index 82bdc93042..6127206404 100644 --- a/docs/getting-started-guides/juju.md +++ b/docs/getting-started-guides/juju.md @@ -19,16 +19,16 @@ and tag the issue with "juju" so we can find them. > Note: If you're running kube-up, on Ubuntu - all of the dependencies > will be handled for you. You may safely skip to the section: -> [Launch Kubernetes Cluster](#launch-kubernetes-cluster) +> [Launch a Kubernetes Cluster](#launch-a-kubernetes-cluster) ### On Ubuntu [Install the Juju client](https://jujucharms.com/get-started) -> This documentation focuses on the juju 2.0 release which will be -> promoted to stable during its release cycle in April +> This documentation focuses on the Juju 2.0 release which will be +> promoted to stable during the April 2016 release cycle. -To paraphrase, on your local Ubuntu system: +To paraphrase, on your local Ubuntu system: ```shell sudo add-apt-repository ppa:juju/devel @@ -46,9 +46,9 @@ If you are not using Ubuntu or prefer the isolation of Docker, you may run the following: > While this is a common target, the charmbox flavors of images are -> unofficial, and should be treated as Experimental. If you encounter any issues +> unofficial, and should be treated as experimental. If you encounter any issues > turning up the Kubernetes cluster with charmbox, please file a bug on the -> respective issue tracker [here](https://github.com/juju-solutions/charmbox/issues) +> [charmbox issue tracker](https://github.com/juju-solutions/charmbox/issues). ```shell mkdir ~/.juju2 @@ -69,7 +69,7 @@ command: `juju bootstrap $cloudname $cloudtype` you are ready to launch the Kubernetes cluster. -## Launch Kubernetes cluster +## Launch a Kubernetes cluster You will need to export the `KUBERNETES_PROVIDER` environment variable before bringing up the cluster. @@ -82,9 +82,8 @@ cluster/kube-up.sh If this is your first time running the `kube-up.sh` script, it will attempt to install the required dependencies to get started with Juju. -Next it will deploy the kubernetes application, 3 units of etcd, and network -the units with flannel based Software Defined Networking (SDN) so containers -on different hosts can communicate with each other. +Next it will deploy two nodes of Kubernetes, 1 unit of etcd, and network +the units so containers on different hosts can communicate with each other. ## Exploring the cluster @@ -161,13 +160,13 @@ We'll follow the aws-coreos example. Create a pod manifest: `pod.json` } ``` -Create the pod with kubectl: +Create the pod with kubectl: ```shell kubectl create -f pod.json ``` -Get info on the pod: +Get info on the pod: ```shell kubectl get pods @@ -187,7 +186,8 @@ CONTAINER IDIMAGE COMMAND CREATED STATUS PORTS NAMES 02beb61339d8quay.io/kelseyhightower/hello:latest /hello About an hour ago Up About an hourk8s_hello.... ``` -We see "kubernetes/1" has our container, we can open port 80: +We see "kubernetes/1" has our container, expose the kubernetes charm and open +port 80: ```shell juju run --unit kubernetes/1 "open-port 80" @@ -196,7 +196,7 @@ sudo apt-get install curl curl $(juju status --format=oneline kubernetes/1 | cut -d' ' -f3) ``` -Finally delete the pod: +Finally delete the pod: ```shell juju ssh kubernetes/0 @@ -204,22 +204,23 @@ kubectl delete pods hello ``` ## Scale up cluster -Whant larger kubernetes nodes? It is easy to request different sizes of cloud +Want larger Kubernetes nodes? It is easy to request different sizes of cloud resources from Juju by using **constraints**. You can increase the amount of CPU or memory (RAM) in any of the systems requested by Juju. This allows you -to fine tune th Kubernetes cluster to fit your workload. Use the boostrap -command or as a seperate `juju constraints` command. Look to the -[Juju documentation for machine constraints](https://jujucharms.com/docs/devel/charms-constraints). +to fine tune th Kubernetes cluster to fit your workload. Use flags on the +bootstrap command or as a separate `juju constraints` command. Look to the +[Juju documentation for machine constraints](https://jujucharms.com/docs/devel/charms-constraints) +details. ## Scale out cluster -Need more clusters? Juju makes it easy to add units of a charm: +Need more clusters? Juju makes it easy to add units of a charm: ```shell juju add-unit kubernetes ``` -Or multiple units at one time: +Or multiple units at one time: ```shell juju add-unit -n3 kubernetes @@ -235,8 +236,8 @@ build directories. ./kube-down.sh ``` -Alternately if you want stop the servers you can destroy your current Juju environment. -Use the `juju env` command to get the current environment name: +Alternately if you want stop the servers you can destroy your current Juju +environment. Use the `juju env` command to get the current environment name: ```shell juju kill-controller `juju env` @@ -250,7 +251,7 @@ a layered approach to keep the code smaller and more focused on the operations of Kubernetes. The Kubernetes layer and bundles can be found in the `kubernetes` -project on github.com: +project on github.com: - [Bundle location](https://github.com/kubernetes/kubernetes/tree/master/cluster/juju/bundles) - [Kubernetes charm layer location](https://github.com/kubernetes/kubernetes/tree/master/cluster/juju/layers/kubernetes)