whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #287 from chuckbutler/juju-docs

Browse Source 
Updated Juju Documentation
This commit is contained in:
Brian Grant
2016-03-30 15:30:30 -07:00
parent f5704a6888 f1f0090d37
commit 21887f20ee
1 changed files with 108 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started-guides/juju.md
+108 -79
View File
@@ -3,9 +3,15 @@
[Juju](https://jujucharms.com/docs/stable/about-juju) makes it easy to deploy [Juju](https://jujucharms.com/docs/stable/about-juju) makes it easy to deploy
Kubernetes by provisioning, installing and configuring all the systems in 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. 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
{:toc} {:toc}
@@ -13,48 +19,57 @@ to increase the cluster size.
> 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: > 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 ### On Ubuntu
[Install the Juju client](https://jujucharms.com/get-started) on your [Install the Juju client](https://jujucharms.com/get-started)
local Ubuntu system:
> 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:
```shell ```shell
sudo add-apt-repository ppa:juju/stable sudo add-apt-repository ppa:juju/devel
sudo apt-get update 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 ### 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: run the following:
```shell > While this is a common target, the charmbox flavors of images are
mkdir ~/.juju > unofficial, and should be treated as experimental. If you encounter any issues
sudo docker run -v ~/.juju:/home/ubuntu/.juju -ti jujusolutions/jujubox:latest > turning up the Kubernetes cluster with charmbox, please file a bug on the
``` > [charmbox issue tracker](https://github.com/juju-solutions/charmbox/issues).
At this point from either path you will have access to the `juju
quickstart` command.
To set up the credentials for your chosen cloud run:
```shell ```shell
juju quickstart --constraints="mem=3.75G" -i mkdir ~/.juju2
sudo docker run -v ~/.juju2:/home/ubuntu/.local/share/juju -ti jujusolutions/charmbox:devel
``` ```
> The `constraints` flag is optional, it changes the size of virtual machines ### Configure Juju to point a cloud
> 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 At this point you have access to the Juju client. Before you can deploy a
bootstrap the juju root node and setup the juju web based user cluster you have to configure the credentials for the Juju cloud provider.
interface.
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).
## Launch Kubernetes cluster 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 a Kubernetes cluster
You will need to export the `KUBERNETES_PROVIDER` environment variable before You will need to export the `KUBERNETES_PROVIDER` environment variable before
bringing up the cluster. bringing up the cluster.
@@ -64,44 +79,50 @@ export KUBERNETES_PROVIDER=juju
cluster/kube-up.sh cluster/kube-up.sh
``` ```
If this is your first time running the `kube-up.sh` script, it will install If this is your first time running the `kube-up.sh` script, it will attempt to
the required dependencies to get started with Juju, additionally it will install the required dependencies to get started with Juju.
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 (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 ## 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 ```shell
$ juju status --format=oneline $ juju status
- 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
```
You can use `juju ssh` to access any of the units: ... (omitted for brevity)
```shell [Units]
juju ssh kubernetes-master/0 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
... (omitted for brevity)
``` ```
## Run some containers! ## Run some containers!
`kubectl` is available on the Kubernetes master node. We'll ssh in to The `kubectl` file, the TLS certificates along with the configuration are
launch some containers, but one could use `kubectl` locally by setting all available on the Kubernetes leader unit. Fetch the kubectl package so you
`KUBERNETES_MASTER` to point at the ip address of "kubernetes-master/0". 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 --kubeconfig config 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`.
No pods will be available before starting a container: No pods will be available before starting a container:
@@ -139,21 +160,20 @@ We'll follow the aws-coreos example. Create a pod manifest: `pod.json`
} }
``` ```
Create the pod with kubectl: Create the pod with kubectl:
```shell ```shell
kubectl create -f pod.json kubectl create -f pod.json
``` ```
Get info on the pod: Get info on the pod:
```shell ```shell
kubectl get pods kubectl get pods
``` ```
To test the hello app, we need to locate which node is hosting 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. We can use `juju run` and `juju status` commands to find
is in the works but we can use `juju run` and `juju status` to find
our hello app. our hello app.
Exit out of our ssh session and run: Exit out of our ssh session and run:
@@ -166,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.... 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 ```shell
juju run --unit kubernetes/1 "open-port 80" juju run --unit kubernetes/1 "open-port 80"
@@ -175,55 +196,65 @@ sudo apt-get install curl
curl $(juju status --format=oneline kubernetes/1 | cut -d' ' -f3) curl $(juju status --format=oneline kubernetes/1 | cut -d' ' -f3)
``` ```
Finally delete the pod: Finally delete the pod:
```shell ```shell
juju ssh kubernetes-master/0 juju ssh kubernetes/0
kubectl delete pods hello kubectl delete pods hello
``` ```
## Scale up cluster
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 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 ## Scale out cluster
We can add node units like so: Need more clusters? Juju makes it easy to add units of a charm:
```shell ```shell
juju add-unit docker # creates unit docker/2, kubernetes/2, docker-flannel/2 juju add-unit kubernetes
``` ```
## Launch the "k8petstore" example app Or multiple units at one time:
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 ```shell
juju action do kubernetes-master/0 juju add-unit -n3 kubernetes
``` ```
> 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 ## 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 ```shell
./kube-down.sh ./kube-down.sh
``` ```
or 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 ```shell
juju destroy-environment --force `juju env` juju kill-controller `juju env`
``` ```
## More Info ## More Info
The Kubernetes charms and bundles can be found in the `kubernetes` project on Juju works with charms and bundles to deploy solutions. The code that stands up
github.com: 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) The Kubernetes layer and bundles can be found in the `kubernetes`
* [Kubernetes master charm](https://releases.k8s.io/{{page.githubbranch}}/cluster/juju/charms/trusty/kubernetes-master) project on github.com:
* [Kubernetes node charm](https://releases.k8s.io/{{page.githubbranch}}/cluster/juju/charms/trusty/kubernetes)
- [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) - [More about Juju](https://jujucharms.com)
@@ -241,8 +272,6 @@ works with [Amazon Web Service](https://jujucharms.com/docs/stable/config-aws),
[Vagrant](https://jujucharms.com/docs/stable/config-vagrant), and [Vagrant](https://jujucharms.com/docs/stable/config-vagrant), and
[Vmware vSphere](https://jujucharms.com/docs/stable/config-vmware). [Vmware vSphere](https://jujucharms.com/docs/stable/config-vmware).
If you do not see your favorite cloud provider listed many clouds can be If you do not see your favorite cloud provider listed many clouds with ssh
configured for [manual provisioning](https://jujucharms.com/docs/stable/config-manual). access 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.