Skip to content
This repository has been archived by the owner on Jan 11, 2023. It is now read-only.

Doc style, minor updates pass #4017

Merged
merged 4 commits into from
Oct 16, 2018
Merged

Doc style, minor updates pass #4017

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
118d18b
acsengine and deploy pass
oivindoh Oct 13, 2018
c1770b2
Clean up the main README
oivindoh Oct 13, 2018
478f590
pass over the kubernetes walkthrough doc - I think maybe just azure s…
oivindoh Oct 13, 2018
8401e3a
Review changes
oivindoh Oct 16, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 14 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# Microsoft Azure Container Service Engine - Builds Docker Enabled Clusters

[![Coverage Status](https://codecov.io/gh/Azure/acs-engine/branch/master/graph/badge.svg)](https://codecov.io/gh/Azure/acs-engine)
[![CircleCI](https://circleci.com/gh/Azure/acs-engine/tree/master.svg?style=svg)](https://circleci.com/gh/Azure/acs-engine/tree/master)
[![GoDoc](https://godoc.org/github.com/Azure/acs-engine?status.svg)](https://godoc.org/github.com/Azure/acs-engine)
Expand All @@ -8,13 +9,14 @@
The Azure Container Service Engine (`acs-engine`) generates ARM (Azure Resource Manager) templates for Docker enabled clusters on Microsoft Azure with your choice of DC/OS, Kubernetes, OpenShift, Swarm Mode, or Swarm orchestrators. The input to the tool is a cluster definition. The cluster definition (or apimodel) is very similar to (in many cases the same as) the ARM template syntax used to deploy a Microsoft Azure Container Service cluster.

The cluster definition file enables you to customize your Docker enabled cluster in many ways including:
* choice of DC/OS, Kubernetes, OpenShift, Swarm Mode, or Swarm orchestrators
* multiple agent pools where each agent pool can specify:
* standard or premium VM Sizes, including GPU optimized VM sizes
* node count
* Virtual Machine ScaleSets or Availability Sets
* Storage Account Disks or Managed Disks
* OS and distro

* Choice of DC/OS, Kubernetes, OpenShift, Swarm Mode, or Swarm orchestrators
* Multiple agent pools where each agent pool can specify:
* Standard or premium VM Sizes, including GPU optimized VM sizes
* Node count
* Virtual Machine ScaleSets or Availability Sets
* Storage Account Disks or Managed Disks
* OS and distro
* Custom VNET
* Extensions

Expand All @@ -23,13 +25,15 @@ More info, including a thorough walkthrough is [here](docs/acsengine.md).
## User guides

These guides show how to create your first deployment for each orchestrator:

* [DC/OS Walkthrough](docs/dcos.md) - shows how to create a DC/OS cluster on Azure
* [Kubernetes Walkthrough](docs/kubernetes.md) - shows how to create a Linux or Windows Kubernetes cluster on Azure
* [OpenShift Walkthrough](docs/openshift.md) - shows how to create an OpenShift cluster on Azure
* [Swarm Mode Walkthrough](docs/swarmmode.md) - shows how to create a [Docker Swarm Mode](https://docs.docker.com/engine/swarm/) cluster on Azure
* [Standalone Swarm Walkthrough](docs/swarm.md) - shows how to create a [Docker Standalone Swarm](https://docs.docker.com/swarm/) cluster on Azure

These guides cover more advanced features to try out after you have built your first cluster:

* [Cluster Definition](docs/clusterdefinition.md) - describes the components of the cluster definition file
* [Custom VNET](examples/vnet) - shows how to use a custom VNET
* [Attached Disks](examples/disks-storageaccount) - shows how to attach up to 4 disks per node
Expand All @@ -45,11 +49,8 @@ To build acs-engine, run `make build`. If you are developing with a working [Doc
Please follow these instructions before submitting a PR:

1. Execute `make test` to run unit tests.

2. Manually test deployments if you are making modifications to the templates.
For example, if you have to change the expected resulting templates then you
should deploy the relevant example cluster definitions to ensure that you are not introducing any regressions.

* For example, if you have to change the expected resulting templates then you should deploy the relevant example cluster definitions to ensure that you are not introducing any regressions.
3. Make sure that your changes are properly documented and include relevant unit tests.

## Usage
Expand All @@ -58,7 +59,7 @@ Please follow these instructions before submitting a PR:

Usage is best demonstrated with an example:

```shell
```sh
$ vim examples/kubernetes.json

# insert your preferred, unique DNS prefix
Expand All @@ -67,9 +68,7 @@ $ vim examples/kubernetes.json
$ ./acs-engine generate examples/kubernetes.json
```

This produces a new directory inside `_output/` that contains an ARM template
for deploying Kubernetes into Azure. (In the case of Kubernetes, some additional
needed assets are generated and placed in the output directory.)
This produces a new directory inside `_output/` that contains an ARM template for deploying Kubernetes into Azure. (In the case of Kubernetes, some additional needed assets are generated and placed in the output directory.)

## Code of conduct

Expand Down
22 changes: 12 additions & 10 deletions docs/acsengine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ When the script `devenv.ps1` or `devenv.sh` completes, you will be left at a com

Run the following commands to pull the latest dependencies and build the `acs-engine` tool.

```
```sh
# install and download build dependencies
make bootstrap
# build the `acs-engine` binary
Expand All @@ -105,8 +105,8 @@ make build

The build process leaves the compiled `acs-engine` binary in the `bin` directory. Make sure everything completed successfully by running `bin/acs-engine` without any arguments:

```
# ./bin/acs-engine
```sh
$ ./bin/acs-engine
ACS-Engine deploys and manages Kubernetes, OpenShift, Swarm Mode, and DC/OS clusters in Azure

Usage:
Expand Down Expand Up @@ -137,20 +137,21 @@ Use "acs-engine [command] --help" for more information about a command.
Building ACS Engine from source has a few requirements for each of the platforms. Download and install the pre-reqs for your platform, Windows, Linux, or Mac:

### Prerequisite

1. Go version 1.8 [installation instructions](https://golang.org/doc/install)
2. Git Version Control [installation instructions](https://git-scm.com/download/)

### Windows

Setup steps:

1. Setup your go workspace. This guide assumes you are using `c:\gopath` as your Go workspace:
* Setup your go workspace. This guide assumes you are using `c:\gopath` as your Go workspace:
1. Type Windows key-R to open the run prompt
2. Type `rundll32 sysdm.cpl,EditEnvironmentVariables` to open the system variables
3. Add `c:\go\bin` and `c:\gopath\bin` to your PATH variables
4. Click "new" and add new environment variable named `GOPATH` and set the value to `c:\gopath`

Build acs-engine:
* Build acs-engine:
1. Type Windows key-R to open the run prompt
2. Type `cmd` to open a command prompt
3. Type `mkdir %GOPATH%` to create your gopath
Expand All @@ -173,14 +174,15 @@ Setup steps:

1. Open a command prompt to setup your gopath:
2. `mkdir $HOME/go`
3. edit `$HOME/.bash_profile` and add the following lines to setup your go path
```
export GOPATH=$HOME/go
export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin
```
3. Edit `$HOME/.bash_profile` and add the following lines to setup your go path:
```sh
export GOPATH=$HOME/go
export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin
```
4. `source $HOME/.bash_profile`

Build acs-engine:

1. Type `go get github.com/Azure/acs-engine` to get the acs-engine Github project
2. Type `cd $GOPATH/src/github.com/Azure/acs-engine` to change to the source directory
3. Type `make bootstrap` to install supporting components
Expand Down
30 changes: 14 additions & 16 deletions docs/kubernetes/deploy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Deploy a Kubernetes Cluster

## Install Pre-requisites
## Install Prerequisites

All the commands in this guide require both the Azure CLI and `acs-engine`. Follow the [installation instructions to download acs-engine before continuing](../acsengine.md#install-acs-engine) or [compile from source](../acsengine.md#build-from-source).

Expand All @@ -23,7 +23,7 @@ After the cluster is deployed the upgrade and [scale](scale.md) commands can be
* A `dnsPrefix` which forms part of the the hostname for your cluster (e.g. staging, prodwest, blueberry). The DNS prefix must be unique so pick a random name.
* A location to provision the cluster e.g. `westus2`.

```
```sh
$ az account list -o table
Name CloudName SubscriptionId State IsDefault
----------------------------------------------- ----------- ------------------------------------ ------- -----------
Expand All @@ -36,7 +36,7 @@ For this example, the subscription id is `51ac25de-afdg-9201-d923-8d8e8e8e8e8e`,

Run `acs-engine deploy` with the appropriate arguments:

```
```sh
$ acs-engine deploy --subscription-id 51ac25de-afdg-9201-d923-8d8e8e8e8e8e \
--dns-prefix contoso-apple --location westus2 \
--api-model examples/kubernetes.json
Expand All @@ -52,13 +52,14 @@ INFO[0393] Finished ARM Deployment (contoso-apple-1423145182).

`acs-engine` will output Azure Resource Manager (ARM) templates, SSH keys, and a kubeconfig file in `_output/contoso-apple-59769a59` directory:

* `_output/contoso-apple-59769a59/azureuser_rsa`
* `_output/contoso-apple-59769a59/kubeconfig/kubeconfig.westus2.json`
* `_output/contoso-apple-59769a59/azureuser_rsa`
* `_output/contoso-apple-59769a59/kubeconfig/kubeconfig.westus2.json`

acs-engine generates kubeconfig files for each possible region. Access the new cluster by using the kubeconfig generated for the cluster's location. This example used `westus2`, so the kubeconfig is `_output/<clustername>/kubeconfig/kubeconfig.westus2.json`:

```
$ KUBECONFIG=_output/contoso-apple-59769a59/kubeconfig/kubeconfig.westus2.json kubectl cluster-info
```sh
$ KUBECONFIG=_output/contoso-apple-59769a59/kubeconfig/kubeconfig.westus2.json
$ kubectl cluster-info
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two commands should stay as a one-liner, or the first command should begin with export KUBECONFIG= so the environment variable is visible to the second command.

Kubernetes master is running at https://contoso-apple-59769a59.westus2.cloudapp.azure.com
Heapster is running at https://contoso-apple-59769a59.westus2.cloudapp.azure.com/api/v1/proxy/namespaces/kube-system/services/heapster
KubeDNS is running at https://contoso-apple-59769a59.westus2.cloudapp.azure.com/api/v1/proxy/namespaces/kube-system/services/kube-dns
Expand Down Expand Up @@ -86,7 +87,6 @@ acs-engine deploy --resource-group "your-resource-group" \
--set servicePrincipalProfile.secret="spn-client-secret"
```


<a href="#the-long-way"></a>

## ACS Engine the Long Way
Expand All @@ -99,7 +99,7 @@ If you don't have an SSH key [cluster operators may generate a new one](../ssh.m

### Step 2: Create a Service Principal

Kubernetes clusters have integrated support for various cloud providers as core functionality. On Azure, acs-engine uses a Service Principal to interact with Azure Resource Manager (ARM). Follow the instructions to [create a new service principal](../serviceprincipal.md)
Kubernetes clusters have integrated support for various cloud providers as core functionality. On Azure, acs-engine uses a Service Principal to interact with Azure Resource Manager (ARM). Follow the instructions to [create a new service principal and grant it the necessary IAM role to create Azure resources](../serviceprincipal.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good addition, but having a URL link that long looks strange. Could you add the words outside the URL link markdown?


### Step 3: Edit your Cluster Definition

Expand All @@ -124,31 +124,29 @@ Run `acs-engine generate examples/kubernetes.json`

The generate command lets you override values from the cluster definition file without having to update the file. You can use the `--set` flag to do that:

```bash
```sh
acs-engine generate --set linuxProfile.adminUsername=myNewUsername,masterProfile.count=3 clusterdefinition.json
```

The `--set` flag only supports JSON properties under `properties`. You can also work with array, like the following:

```bash
```sh
acs-engine generate --set agentPoolProfiles[0].count=5,agentPoolProfiles[1].name=myPoolName clusterdefinition.json
```

### Step 5: Submit your Templates to Azure Resource Manager (ARM)

[Deploy the output azuredeploy.json and azuredeploy.parameters.json](../acsengine.md#deployment-usage)
* To enable the optional network policy enforcement using calico, you have to
set the parameter during this step according to this [guide](../kubernetes.md#optional-enable-network-policy-enforcement-using-calico)
* To enable the optional network policy enforcement using cilium, you have to
set the parameter during this step according to this [guide](../kubernetes.md#optional-enable-network-policy-enforcement-using-cilium)

* To enable the optional network policy enforcement using calico, you have to set the parameter during this step according to this [guide](../kubernetes.md#optional-enable-network-policy-enforcement-using-calico)
* To enable the optional network policy enforcement using cilium, you have to set the parameter during this step according to this [guide](../kubernetes.md#optional-enable-network-policy-enforcement-using-cilium)

**Note**: If the cluster is using an existing VNET please see the [Custom VNET](features.md#feat-custom-vnet) feature documentation for additional steps that must be completed after cluster provisioning.


## Checking VM tags

### First we get list of Master and Agent VMs in the cluster

```sh
az vm list -g <resource group of cluster> -o table
Name ResourceGroup Location
Expand Down
Loading