Skip to content

Commit

Permalink
Merge pull request #1133 from colemickens/pr-azure-kany
Browse files Browse the repository at this point in the history 
azure: switch to kubernetes-anywhere
  • Loading branch information
@mikedanese
mikedanese authored Sep 8, 2016
2 parents ee28f8d + 4cc1d90 commit 7a730e6
Showing 1 changed file with 4 additions and 166 deletions.
170 changes: 4 additions & 166 deletions docs/getting-started-guides/azure.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,170 +9,8 @@ assignees:
{:toc}


## Prerequisites
## Overview

1. An Azure subscription. If you don't already have one, you may create one on [azure.microsoft.com](https://azure.microsoft.com).
2. An account with Owner access to the subscription.
3. Both `docker` and `jq` need to be installed and available on `$PATH`.


## Cluster operations

### Cluster bring-up

```shell
export KUBERNETES_PROVIDER=azure; curl -sS https://get.k8s.io | bash
```

Note: if you receive an error "the input device is not a TTY", then you need to start the deployment manually.

```shell
cd ~/kubernetes
./cluster/kube-up.sh
```

NOTE: This script calls [cluster/kube-up.sh](http://releases.k8s.io/{{page.githubbranch}}/cluster/kube-up.sh)
which in turn calls [cluster/azure/util.sh](http://releases.k8s.io/{{page.githubbranch}}/cluster/azure/util.sh)
using [cluster/azure/config-default.sh](http://releases.k8s.io/{{page.githubbranch}}/cluster/azure/config-default.sh).

You must set `AZURE_SUBSCRIPTION_ID` or you will receive errors. Prior to Kubernetes 1.3.0, you must also set `AZURE_TENANT_ID`.
These may be set in `cluster/azure/config-default.sh` or set as environment variables:

```shell
export AZURE_SUBSCRIPTION_ID="<subscription-guid>"
export AZURE_TENANT_ID="<tenant-guid>" # only needed for Kubernetes < v1.3.0.
```

These values can be overriden by setting them in `cluster/azure/config-default.sh` or as environment variables. They are shown here with their default values:

```shell
export AZURE_DEPLOY_ID="" # autogenerated if blank
export AZURE_LOCATION="westus"
export AZURE_RESOURCE_GROUP="" # generated from AZURE_DEPLOY_ID if unset
export AZURE_MASTER_SIZE="Standard_A1"
export AZURE_NODE_SIZE="Standard_A1"
export AZURE_USERNAME="kube"
export NUM_NODES=3
export AZURE_AUTH_METHOD="device"
```


By default, this will deploy a cluster with 4 `Standard_A1`-sized VMs: one master node, three worker nodes. This process takes about 5 to 10 minutes. Once the cluster is up, connection information to the cluster will be displayed. Additionally, your `kubectl` configuration will be updated to know about this cluster and this new cluster will be set as the active context.

The Azure deployment process produces an output directory `cluster/azure/_deployments/${AZURE_DEPLOY_ID}`. In this directory you will find the PKI and SSH assets created for the cluster, as well as a script named `util.sh`. Here are some examples of its usage:

```shell
$ cd cluster/azure/_deployments/kube-20160316-001122/

# This uses the client cert with curl to make an http call to the apiserver.
$ ./util.sh curl api/v1/nodes

# This uses the client cert with kubectl to target this deployment's apiserver.
$ ./util.sh kubectl get nodes

# This alters the current kubectl configuration to point at this cluster.
$ ./util.sh configure-kubectl

# This will deploy the kube-system namespace, the SkyDNS addon, and the kube-dashboard addon.
$ ./util.sh deploy-addons

# This uses the ssh private key to copy the private key itself to the master node.
$ ./util.sh copykey

# This uses the ssh private key to open an ssh connection to the master.
$ ./util.sh ssh
```

### Cluster deployment examples

#### Deploy the `kube-system` namespace

The cluster addons are created in the `kube-system` namespace.

For versions of Kubernetes before 1.3.0, this must be done manually. Starting with 1.3.0, the
namespace is created automatically as part of the Azure bring-up. For versions prior to 1.3.0, you may
execute this to create the `kube-system` namespace:

```shell
kubectl create -f https://raw.githubusercontent.com/colemickens/azkube/v0.0.5/templates/coreos/addons/kube-system.yaml
```

#### Using `kubectl proxy`

`kubectl proxy` is currently used to access to access deployed services.

```shell
kubectl proxy --port=8001
```

Deployed services are available at: `http://localhost:8001/api/v1/proxy/namespaces/<namespace>/services/<service_name>`.


#### Addon: SkyDNS

You can deploy the [SkyDNS addon](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/cluster/addons/dns):

```shell
kubectl create -f https://raw.githubusercontent.com/colemickens/azkube/v0.0.5/templates/coreos/addons/skydns.yaml
```


#### Addon: Kube-Dashboard

This will deploy the [`kube-dashboard`](https://github.com/kubernetes/dashboard) addon:

```shell
kubectl create -f https://raw.githubusercontent.com/colemickens/azkube/v0.0.5/templates/coreos/addons/kube-dashboard.yaml
```

The dashboard is then available at: `http://localhost:8001/api/v1/proxy/namespaces/kube-system/services/dashboard-canary`.

#### Example: Guestbook

This will deploy the [`guestbook example`](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/examples/guestbook/README.md) (the all-in-one variant):

```shell
kubectl create -f https://raw.githubusercontent.com/kubernetes/kubernetes/release-1.2/examples/guestbook/all-in-one/guestbook-all-in-one.yaml
```

The guestbook is then available at: `http://localhost:8001/api/v1/proxy/namespaces/default/services/frontend`.


### Cluster scaling

The `azkube` tool used internally during `kube-up` can also be used to scale your cluster.
Here's an example of scaling a default deployment of 3 nodes to 10 nodes:

```shell
export AZURE_DEPLOY_ID="kube-20160316-001122"
$ docker run -it -v "$HOME/.azkube:/.azkube" -v "/tmp:/tmp" \
colemickens/azkube:v0.0.5 /opt/azkube/azkube scale \
--deployment-name="${AZURE_DEPLOY_ID}" \
--node-size="Standard_A1" \
--node-count=10
```

### Cluster tear-down

You can tear-down a cluster using `kube-down.sh`:

```shell
export AZURE_DEPLOY_ID="kube-20160316-001122"
$ ./cluster/kube-down.sh
```

Prior to Kubernetes 1.3, the cluster must be deleted manually with the Azure CLI or via the Azure Portal.

### Notes

1. The user account used for these operations must have Owner access to the subscription.
2. You can find your subscription ID in the [Azure Portal](https://portal.microsoft.com). (All Resources → Subscriptions)
3. The `AZURE_AUTH_METHOD` environment variable controls what authentication mechanism is used when bringing up the cluster. By default it is set to `device`. This allows the user to login via the a web browser. This interactive step can be automated by creating a Service Principal, setting `AZURE_AUTH_METHOD=client_secret` and setting `AZURE_CLIENT_ID` + `AZURE_CLIENT_SECRET` as appropriate for your Service Principal.
4. The `--node-size` used in the `scale` command must be the same size deployed initially or it will not have the desired effect.
5. Cluster tear-down requires manual intervention, due to the fact that it deletes the entire resource group and someone else may have deployed other resources since the initial deployment. For this reason you must confirm the list of resources that are to be deleted. If you wish to skip it, you may set `AZURE_DOWN_SKIP_CONFIRM` to `true`. This will delete everything in the resource group that was deployed to.
6. If you are deploying from a checkout of `kubernetes`, then you will need to take an additional step to ensure that a `hyperkube` image is available. You can set `AZURE_DOCKER_REGISTRY` and `AZURE_DOCKER_REPO` and the deployment will ensure that a hyperkube container is built and available in the specified Docker registry. That `hyperkube` image will then be used throughout the cluster for running the Kubernetes services. Alternatively, you may set `AZURE_HYPERKUBE_SPEC` to point to a custom `hyperkube` image.


## Further reading

* Please see the [azkube](https://github.com/colemickens/azkube) repository for more information about the deployment tool that manages the deployment.
The recommended approach for deploying a Kubernetes 1.4 cluster on Azure is the
[`kubernetes-anywhere`](https://github.com/kubernetes/kubernetes-anywhere) project. You will want to take a look at the
[Azure Getting Started Guide](https://github.com/kubernetes/kubernetes-anywhere/blob/master/phase1/azure/README.md).

0 comments on commit 7a730e6

Please sign in to comment.