From 8f76449b13fb14d9d12f6d5a5d6f936a13cc0310 Mon Sep 17 00:00:00 2001 From: Matt Bruzek Date: Wed, 27 Jul 2016 17:55:34 -0500 Subject: [PATCH 1/2] Updating the juju docs with new commands and links. --- docs/getting-started-guides/juju.md | 185 ++++++++++++++++++---------- 1 file changed, 120 insertions(+), 65 deletions(-) diff --git a/docs/getting-started-guides/juju.md b/docs/getting-started-guides/juju.md index 313f10176d..ba70a6a5e1 100644 --- a/docs/getting-started-guides/juju.md +++ b/docs/getting-started-guides/juju.md @@ -1,10 +1,12 @@ --- --- -[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 -to increase the cluster size. +[Juju](https://jujucharms.com/docs/2.0/about-juju) encapsulates the +operational knowledge of provisioning, installing, and securing a Kubernetes +cluster into one step. Juju allows you to consistently deploy a cluster on +different cloud providers with a consistent repeatable open source operations. +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 @@ -23,7 +25,7 @@ and tag the issue with "juju" so we can find them. ### On Ubuntu -[Install the Juju client](https://jujucharms.com/get-started) +[Install the Juju client](https://jujucharms.com/docs/2.0/getting-started-general) > This documentation focuses on the Juju 2.0 release which will be > promoted to stable during the April 2016 release cycle. @@ -33,48 +35,55 @@ To paraphrase, on your local Ubuntu system: ```shell sudo add-apt-repository ppa:juju/devel sudo apt-get update -sudo apt-get install juju2 +sudo apt-get install juju ``` 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. +[getting started guide](https://jujucharms.com/docs/2.0/getting-started-general) +to install the Juju dependencies for your platform. ### With Docker -If you are not using Ubuntu or prefer the isolation of Docker, you may -run the following: +If you prefer the isolation of Docker, you can run the Juju client in a +container. Create a local directory to store the Juju configuration, then +volume mount the container: + +```shell +mkdir -p $HOME/.local/share/juju +docker run --rm -ti \ + -v $HOME/.local/share/juju:/home/ubuntu/.local/share/juju \ + jujusolutions/charmbox:devel +``` > 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 > [charmbox issue tracker](https://github.com/juju-solutions/charmbox/issues). -```shell -mkdir ~/.juju2 -sudo docker run -v ~/.juju2:/home/ubuntu/.local/share/juju -ti jujusolutions/charmbox:devel -``` - -### Configure Juju to point a cloud +### Configure Juju to your favorite 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. +cluster you have to configure Juju with the +[cloud credentials](https://jujucharms.com/docs/2.0/credentials) for each +cloud provider you would like to use. -Juju [supports a wide variety of public clouds](#Cloud-compatibility) to set +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). +[cloud setup page](https://jujucharms.com/docs/devel/getting-started-general#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. +command: `juju bootstrap $controllername $cloudtype` you are ready to launch +the Kubernetes cluster. ## Launch a Kubernetes cluster -You will need to export the `KUBERNETES_PROVIDER` environment variable before -bringing up the cluster. +You can deploy a Kubernetes cluster with Juju from the `kubernetes` directory of +the [kubernetes github project](https://github.com/kubernetes/kubernetes.git). +Clone the repository on your local system. Export the `KUBERNETES_PROVIDER` +environment variable before bringing up the cluster. ```shell +cd kubernetes export KUBERNETES_PROVIDER=juju cluster/kube-up.sh ``` @@ -82,47 +91,60 @@ 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 two nodes of Kubernetes, 1 unit of etcd, and network +The script 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 -The `juju status` command provides information about each unit in the cluster: +The `juju status` command provides information about each unit in the cluster: ```shell $ juju status +MODEL CONTROLLER CLOUD/REGION VERSION +default windows azure/centralus 2.0-beta13 -... (omitted for brevity) +APP VERSION STATUS EXPOSED ORIGIN CHARM REV OS +etcd active false jujucharms etcd 3 ubuntu +kubernetes active true jujucharms kubernetes 5 ubuntu -[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 +RELATION PROVIDES CONSUMES TYPE +cluster etcd etcd peer +etcd etcd kubernetes regular +certificates kubernetes kubernetes peer -... (omitted for brevity) +UNIT WORKLOAD AGENT MACHINE PORTS PUBLIC-ADDRESS MESSAGE +etcd/0 active idle 0 2379/tcp 13.67.217.11 (leader) cluster is healthy +kubernetes/0 active idle 1 8088/tcp 13.67.219.76 Kubernetes running. +kubernetes/1 active idle 2 6443/tcp 13.67.219.182 (master) Kubernetes running. + +MACHINE STATE DNS INS-ID SERIES AZ +0 started 13.67.217.11 machine-0 trusty +1 started 13.67.219.76 machine-1 trusty +2 started 13.67.219.182 machine-2 trusty ``` ## Run some containers! -The `kubectl` file, the TLS certificates along with the configuration are -all available on the Kubernetes leader unit. Fetch the kubectl package so you +The `kubectl` file, and the TLS certificates along with the configuration are +all available on the Kubernetes master 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: +Use the `juju status` command to figure out which unit is the master. In the +example above the "kubernetes/1" unit is the master. Use the `juju scp` +command to copy the file from the unit: ```shell juju scp kubernetes/1:kubectl_package.tar.gz . tar xvfz kubectl_package.tar.gz -kubectl --kubeconfig config get pods +./kubectl --kubeconfig kubeconfig get pods ``` 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`. +Copy the `kubeconfig` file to 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: @@ -202,6 +224,7 @@ Finally delete the pod: juju ssh kubernetes/0 kubectl delete pods hello ``` + ## Scale up cluster Want larger Kubernetes nodes? It is easy to request different sizes of cloud @@ -209,12 +232,12 @@ 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 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) +[Juju documentation for machine](https://jujucharms.com/docs/2.0/charms-constraints) details. ## Scale out cluster -Need more clusters? Juju makes it easy to add units of a charm: +Need more workers? Juju makes it easy to add units of a charm: ```shell juju add-unit kubernetes @@ -226,21 +249,28 @@ Or multiple units at one time: juju add-unit -n3 kubernetes ``` +You can also scale the etcd charm for more fault tolerant key/value storage: + +```shell +juju add-unit -n2 etcd +``` + ## Tear down cluster -We recommend that you use the `kube-down.sh` command when you are done using +We recommend that you use the `kube-down.sh` script 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 +./cluster/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 the Juju model or the +controller. Use the `juju switch` command to get the current controller name: ```shell -juju kill-controller `juju env` +juju switch +juju destroy-controller $controllername ``` ## More Info @@ -260,33 +290,58 @@ project on github.com: ### Cloud compatibility -Juju runs natively against a variety of public cloud providers. Juju currently -works with [Amazon Web Service](https://jujucharms.com/docs/stable/config-aws), -[Windows Azure](https://jujucharms.com/docs/stable/config-azure), -[DigitalOcean](https://jujucharms.com/docs/stable/config-digitalocean), -[Google Compute Engine](https://jujucharms.com/docs/stable/config-gce), -[HP Public Cloud](https://jujucharms.com/docs/stable/config-hpcloud), -[Joyent](https://jujucharms.com/docs/stable/config-joyent), -[LXC](https://jujucharms.com/docs/stable/config-LXC), any -[OpenStack](https://jujucharms.com/docs/stable/config-openstack) deployment, -[Vagrant](https://jujucharms.com/docs/stable/config-vagrant), and -[Vmware vSphere](https://jujucharms.com/docs/stable/config-vmware). +Juju is cloud agnostic and gives you a consistent experience across different +cloud providers. Juju supports a variety of public cloud providers: [Amazon Web Service](https://jujucharms.com/docs/2.0/help-aws), +[Microsoft Azure](https://jujucharms.com/docs/2.0/help-azure), +[Google Compute Engine](https://jujucharms.com/docs/2.0/help-google), +[Joyent](https://jujucharms.com/docs/2.0/help-joyent), +[Rackspace](https://jujucharms.com/docs/2.0/help-rackspace), any +[OpenStack cloud](https://jujucharms.com/docs/2.0/clouds#specifying-additional-clouds), +and +[Vmware vSphere](https://jujucharms.com/docs/2.0/config-vmware). 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). +[manual provisioning](https://jujucharms.com/docs/2.0/clouds-manual). + +There are three special types of clouds: MAAS, LXD and Manual. + +- [LXD](https://jujucharms.com/docs/2.0/clouds-LXD): Is a system level + container technology that is extremely fast and less overhead than + traditional virutalization. + [LXD is a container hypervisor](http://www.ubuntu.com/cloud/lxd) + that runs on any Linux host, providing the ability to spin up system + containers on the host machine. **Note** that at this time nested + containerization of Docker inside LXD is not supported, so you can not spin + up a Kubernetes cluster on LXD. For more details on using LXD, please see the + [LXD documentation](https://jujucharms.com/docs/2.0/clouds-LXD). + +- [MAAS](https://jujucharms.com/docs/2.0/clouds-maas): An acronym of Metal As + A Service, MAAS lets you treat physical servers like virtual machines in the + cloud. Rather than having to manage each server individually, MAAS turns your + bare metal into an elastic cloud-like resource. There is more information on + MAAS at the [MAAS website](http://maas.io/), and detailed instructions on + [using MAAS with Juju here](https://jujucharms.com/docs/2.0/clouds-maas). + + - [Manual](https://jujucharms.com/docs/2.0/clouds-manual): There may be + occasions where you can bring up machines for Juju to use which are not part + of a recognized public cloud or do not support other protocols used by Juju. + As long as you have SSH access to these machines, you can get part of the + Juju magic and deploy applications. + +To change to a different cloud you can use the `juju switch` command and set +up the credentials for that cloud provider and continue to use the `kubeup.sh` +script. ## Support Level IaaS Provider | Config. Mgmt | OS | Networking | Docs | Conforms | Support Level -------------------- | ------------ | ------ | ---------- | --------------------------------------------- | ---------| ---------------------------- -AWS | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/juju) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) -OpenStack/HPCloud | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/juju) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) -Joyent | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/juju) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) - +Amazon Web Services (AWS) | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/juju) | | [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) +OpenStack | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/juju) | | [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) +Microsoft Azure | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/juju) | | [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) +Google Compute Engine (GCE) | Juju | Ubuntu | flannel | [docs](/docs/getting-started-guides/juju) | | [Community](https://github.com/juju-solutions/bundle-kubernetes-core) ( [@mbruzek](https://github.com/mbruzek), [@chuckbutler](https://github.com/chuckbutler) ) For support level information on all solutions, see the [Table of solutions](/docs/getting-started-guides/#table-of-solutions) chart. - - From 6b8b1cf2b225cac79ecceab61420a8162a4a4dc8 Mon Sep 17 00:00:00 2001 From: Matt Bruzek Date: Thu, 28 Jul 2016 13:59:02 -0500 Subject: [PATCH 2/2] Addressing review comments from @chuckbutler and @kelseyhightower --- docs/getting-started-guides/juju.md | 42 ++++++----------------------- 1 file changed, 8 insertions(+), 34 deletions(-) diff --git a/docs/getting-started-guides/juju.md b/docs/getting-started-guides/juju.md index ba70a6a5e1..ac7ceef8d0 100644 --- a/docs/getting-started-guides/juju.md +++ b/docs/getting-started-guides/juju.md @@ -3,14 +3,13 @@ [Juju](https://jujucharms.com/docs/2.0/about-juju) encapsulates the operational knowledge of provisioning, installing, and securing a Kubernetes -cluster into one step. Juju allows you to consistently deploy a cluster on -different cloud providers with a consistent repeatable open source operations. -Once deployed the cluster can easily scale up with one command to increase the -cluster size. +cluster into one step. Juju allows you to deploy a Kubernetes cluster on +different cloud providers with a consistent, repeatable user experience. +Once deployed the cluster can easily scale up with one command. -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) +The Juju Kubernetes work is curated by a dedicated team of community members, +let us know how we are doing. If you find any problems please open an +[issue on the kubernetes project](https://github.com/kubernetes/kubernetes/issues) and tag the issue with "juju" so we can find them. @@ -91,7 +90,7 @@ 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. -The script will deploy two nodes of kubernetes, 1 unit of etcd, and network +The script 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 @@ -270,7 +269,7 @@ controller. Use the `juju switch` command to get the current controller name: ```shell juju switch -juju destroy-controller $controllername +juju destroy-controller $controllername --destroy-all-models ``` ## More Info @@ -304,31 +303,6 @@ 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/2.0/clouds-manual). -There are three special types of clouds: MAAS, LXD and Manual. - -- [LXD](https://jujucharms.com/docs/2.0/clouds-LXD): Is a system level - container technology that is extremely fast and less overhead than - traditional virutalization. - [LXD is a container hypervisor](http://www.ubuntu.com/cloud/lxd) - that runs on any Linux host, providing the ability to spin up system - containers on the host machine. **Note** that at this time nested - containerization of Docker inside LXD is not supported, so you can not spin - up a Kubernetes cluster on LXD. For more details on using LXD, please see the - [LXD documentation](https://jujucharms.com/docs/2.0/clouds-LXD). - -- [MAAS](https://jujucharms.com/docs/2.0/clouds-maas): An acronym of Metal As - A Service, MAAS lets you treat physical servers like virtual machines in the - cloud. Rather than having to manage each server individually, MAAS turns your - bare metal into an elastic cloud-like resource. There is more information on - MAAS at the [MAAS website](http://maas.io/), and detailed instructions on - [using MAAS with Juju here](https://jujucharms.com/docs/2.0/clouds-maas). - - - [Manual](https://jujucharms.com/docs/2.0/clouds-manual): There may be - occasions where you can bring up machines for Juju to use which are not part - of a recognized public cloud or do not support other protocols used by Juju. - As long as you have SSH access to these machines, you can get part of the - Juju magic and deploy applications. - To change to a different cloud you can use the `juju switch` command and set up the credentials for that cloud provider and continue to use the `kubeup.sh` script.