diff --git a/docs/getting-started-guides/juju.md b/docs/getting-started-guides/juju.md index e37486dea1b..2d580ab7c6d 100644 --- a/docs/getting-started-guides/juju.md +++ b/docs/getting-started-guides/juju.md @@ -30,12 +30,15 @@ Documentation for other releases can be found at + Getting started with Juju ------------------------- -Juju handles provisioning machines and deploying complex systems to a -wide number of clouds, supporting service orchestration once the bundle of -services has been deployed. +[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. + **Table of Contents** @@ -54,14 +57,14 @@ services has been deployed. ## Prerequisites -> Note: If you're running kube-up, on ubuntu - all of the dependencies +> 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) ### On Ubuntu -[Install the Juju client](https://juju.ubuntu.com/install) on your -local ubuntu system: +[Install the Juju client](https://jujucharms.com/get-started) on your +local Ubuntu system: sudo add-apt-repository ppa:juju/stable sudo apt-get update @@ -70,11 +73,11 @@ local ubuntu system: ### With Docker -If you are not using ubuntu or prefer the isolation of docker, you may +If you are not using Ubuntu or prefer the isolation of Docker, you may run the following: mkdir ~/.juju - sudo docker run -v ~/.juju:/home/ubuntu/.juju -ti whitmo/jujubox:latest + sudo docker run -v ~/.juju:/home/ubuntu/.juju -ti jujusolutions/jujubox:latest At this point from either path you will have access to the `juju quickstart` command. @@ -83,6 +86,10 @@ To set up the credentials for your chosen cloud run: 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. @@ -90,28 +97,27 @@ interface. ## Launch Kubernetes cluster -Kubernetes releases can be downloaded from [this page](https://github.com/GoogleCloudPlatform/kubernetes/releases). +You will need to export the `KUBERNETES_PROVIDER` environment variable before +bringing up the cluster. -You will need to have the Kubernetes tools compiled before launching the cluster - - make all WHAT=cmd/kubectl 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 predependencies to get started with Juju, additionally it will +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. -Next it will deploy the Kubernetes master, etcd, 2 nodes with flannel based -Software Defined Networking. +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. ## Exploring the cluster -Juju status provides information about each unit in the cluster: +The `juju status` command provides information about each unit in the cluster: - juju status --format=oneline + $ 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) @@ -130,8 +136,8 @@ You can use `juju ssh` to access any of the units: ## 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 setting -KUBERNETES_MASTER to point at the ip of `kubernetes-master/0`. +launch some containers, but one could use `kubectl` locally by setting +`KUBERNETES_MASTER` to point at the ip address of "kubernetes-master/0". No pods will be available before starting a container: @@ -178,7 +184,7 @@ Get info on the pod: To test the hello app, we need to locate which node is hosting -the container. Better tooling for using juju to introspect container +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 our hello app. @@ -191,7 +197,7 @@ Exit out of our ssh session and run: 02beb61339d8 quay.io/kelseyhightower/hello:latest /hello About an hour ago Up About an hour k8s_hello.... -We see `kubernetes/1` has our container, we can open port 80: +We see "kubernetes/1" has our container, we can open port 80: juju run --unit kubernetes/1 "open-port 80" juju expose kubernetes @@ -217,54 +223,49 @@ The [k8petstore example](../../examples/k8petstore/) is available as a 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. +> 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 ./kube-down.sh -or +or destroy your current Juju environment (using the `juju env` command): juju destroy-environment --force `juju env` + ## More Info -Kubernetes Bundle on Github +The Kubernetes charms and bundles can be found in the `kubernetes` project on +github.com: - - [Bundle Repository](https://github.com/whitmo/bundle-kubernetes) - * [Kubernetes master charm](https://github.com/whitmo/charm-kubernetes-master) - * [Kubernetes node charm](https://github.com/whitmo/charm-kubernetes) - - [Bundle Documentation](http://whitmo.github.io/bundle-kubernetes) - - [More about Juju](https://juju.ubuntu.com) + - [Bundle Repository](http://releases.k8s.io/HEAD/cluster/juju/bundles) + * [Kubernetes master charm](../../cluster/juju/charms/trusty/kubernetes-master/) + * [Kubernetes node charm](../../cluster/juju/charms/trusty/kubernetes/) + - [More about Juju](https://jujucharms.com) ### Cloud compatibility -Juju runs natively against a variety of cloud providers and can be -made to work against many more using a generic manual provider. +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). -Provider | v0.15.0 --------------- | ------- -AWS | TBD -HPCloud | TBD -OpenStack | TBD -Joyent | TBD -Azure | TBD -Digital Ocean | TBD -MAAS (bare metal) | TBD -GCE | TBD +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). - -Provider | v0.8.1 --------------- | ------- -AWS | [Pass](http://reports.vapour.ws/charm-test-details/charm-bundle-test-parent-136) -HPCloud | [Pass](http://reports.vapour.ws/charm-test-details/charm-bundle-test-parent-136) -OpenStack | [Pass](http://reports.vapour.ws/charm-test-details/charm-bundle-test-parent-136) -Joyent | [Pass](http://reports.vapour.ws/charm-test-details/charm-bundle-test-parent-136) -Azure | TBD -Digital Ocean | TBD -MAAS (bare metal) | TBD -GCE | TBD +The Kubernetes bundle has been tested on GCE and AWS and found to work with +version 1.0.0.