Skip to content

Commit

Permalink
ref(docs): reorganize documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@slack
slack committed Aug 3, 2017
1 parent 2db4653 commit c944b67
Show file tree
Hide file tree
Showing 15 changed files with 521 additions and 473 deletions.
70 changes: 3 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,9 @@ Please follow these instructions before submitting a PR:
should deploy the relevant example cluster definitions to ensure you're not
introducing any sort of regression.

## Usage (Template Generation)
## Usage

### Generate Templates

Usage is best demonstrated with an example:

Expand All @@ -57,72 +59,6 @@ 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.)

## Deployment Usage

Generated templates can be deployed using
[the Azure XPlat CLI (v0.10**.0** only)](https://github.com/Azure/azure-xplat-cli/releases/tag/v0.10.0-May2016),
[the Azure CLI 2.0](https://github.com/Azure/azure-cli) or
[Powershell](https://github.com/Azure/azure-powershell).

### Deploying with Azure XPlat CLI

**NOTE:** Some deployments will fail if certain versions of the Azure XPlat CLI are used. It's recommended that you use [Azure XPlat CLI 0.10**.0**](https://github.com/Azure/azure-xplat-cli/releases/tag/v0.10.0-May2016) until a new point release of `0.10.x` is available with the fix.

```bash
$ azure login

$ azure account set "<SUBSCRIPTION NAME OR ID>"

$ azure config mode arm

$ azure group create \
--name="<RESOURCE_GROUP_NAME>" \
--location="<LOCATION>"

$ azure group deployment create \
--name="<DEPLOYMENT NAME>" \
--resource-group="<RESOURCE_GROUP_NAME>" \
--template-file="./_output/<INSTANCE>/azuredeploy.json" \
--parameters-file="./_output/<INSTANCE>/azuredeploy.parameters.json"
```

### Deploying with Azure CLI 2.0
Azure CLI 2.0 is actively improved, so please see [the Azure CLI 2.0 GitHub Repo](https://github.com/Azure/azure-cli) for the latest release and documentation.

```bash
$ az login

$ az account set --subscription "<SUBSCRIPTION NAME OR ID>"

$ az group create \
--name "<RESOURCE_GROUP_NAME>" \
--location "<LOCATION>"

$ az group deployment create \
--name "<DEPLOYMENT NAME>" \
--resource-group "<RESOURCE_GROUP_NAME>" \
--template-file "./_output/<INSTANCE>/azuredeploy.json" \
--parameters "./_output/<INSTANCE>/azuredeploy.parameters.json"
```

### Deploying with Powershell

```powershell
Add-AzureRmAccount
Select-AzureRmSubscription -SubscriptionID <SUBSCRIPTION_ID>
New-AzureRmResourceGroup `
-Name <RESOURCE_GROUP_NAME> `
-Location <LOCATION>
New-AzureRmResourceGroupDeployment `
-Name <DEPLOYMENT_NAME> `
-ResourceGroupName <RESOURCE_GROUP_NAME> `
-TemplateFile _output\<INSTANCE>\azuredeploy.json `
-TemplateParameterFile _output\<INSTANCE>\azuredeploy.parameters.json
```

## Code of conduct

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
23 changes: 0 additions & 23 deletions README_zh-CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,32 +56,9 @@ needed assets are generated and placed in the output directory.)
## 部署方法

可以使用如下几种方式来部署ARM模板：
[the Azure XPlat CLI (v0.10**.0** only)](https://github.com/Azure/azure-xplat-cli/releases/tag/v0.10.0-May2016),
[the Azure CLI 2.0](https://github.com/Azure/azure-cli)，
[Powershell](https://github.com/Azure/azure-powershell).

### 使用Azure XPlat CLI部署

**注意:** 建议使用[Azure XPlat CLI 0.10**.0**](https://github.com/Azure/azure-xplat-cli/releases/tag/v0.10.0-May2016)来部署，使用其他版本的话可能会出现兼容性问题，这些问题会在`0.10.x`版本有更新后修复。

```bash
$ azure login （登录中国版Azure需要指定-e AzureChinaCloud参数）

$ azure account set "<SUBSCRIPTION NAME OR ID>"

$ azure config mode arm

$ azure group create \
--name="<RESOURCE_GROUP_NAME>" \
--location="<LOCATION>"

$ azure group deployment create \
--name="<DEPLOYMENT NAME>" \
--resource-group="<RESOURCE_GROUP_NAME>" \
--template-file="./_output/<INSTANCE>/azuredeploy.json" \
--parameters-file="./_output/<INSTANCE>/azuredeploy.parameters.json"
```

### 使用Azure CLI 2.0部署
**NOTE:** Azure CLI 2.0目前任处于测试阶段，中国地区尚且无法使用。如果部署到国际版的Azure的话可以使用以下流程：

Expand Down
220 changes: 121 additions & 99 deletions docs/acsengine.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,111 @@
# Microsoft Azure Container Service Engine

The Azure Container Service Engine (`acs-engine`) generates ARM (Azure Resource Manager) templates for Docker enabled clusters on Microsoft Azure with your choice of DCOS, Kubernetes, or Swarm orchestrators. The input to the tool is a cluster definition. The cluster definition is very similar to (in many cases the same as) the ARM template syntax used to deploy a Microsoft Azure Container Service cluster.
The Azure Container Service Engine (`acs-engine`) generates ARM (Azure Resource Manager) templates for Docker enabled clusters on Microsoft Azure with your choice of DCOS, Kubernetes, or Swarm orchestrators. The input to acs-engine is a cluster definition file which describes the desired cluster, including orchestrator, features, and agents. The structure of the input files is very similar to the public API for Azure Container Service.

# Development in Docker
<a href="#install-acs-engine"></a>

The easiest way to get started developing on `acs-engine` is to use Docker. If you already have Docker or "Docker for {Windows,Mac}" then you can get started without needing to install anything extra.
## Install

* Windows (PowerShell): `.\scripts\devenv.ps1`
* Linux/OSX (bash): `./scripts/devenv.sh`
Binary downloads for the latest verison of acs-engine are available here:

* [OSX](https://github.com/Azure/acs-engine/releases/download/v0.4.0/acs-engine-v0.4.0-darwin-amd64.tar.gz)
* [Linux 64bit](https://github.com/Azure/acs-engine/releases/download/v0.4.0/acs-engine-v0.4.0-linux-amd64.tar.gz)
* [Windows 64bit](https://github.com/Azure/acs-engine/releases/download/v0.4.0/acs-engine-v0.4.0-windows-amd64.zip)

Download `acs-engine` for your operating system. Extract the binary and copy it to your `$PATH`.

If would prefer to build `acs-engine` from source or are you are interested in contributing to `acs-engine` see [building from source](#build-from-source) below.

## Usage

`acs-engine` reads a JSON [cluster definition](../clusterdefinition.md) and generates a number of files that may be submitted to Azure Resource Manager (ARM). The generated files include:

1. **apimodel.json**: is an expanded version of the cluster definition provided to the generate command. All default or computed values will be expanded during the generate phase.
2. **azuredeploy.json**: represents a complete description of all Azure resources required to fulfill the cluster definition from `apimodel.json`.
3. **azuredeploy.parameters.json**: the parameters file holds a series of custom variables which are used in various locations throughout `azuredeploy.json`.
4. **certificate and access config files**: orchestrators like Kubernetes require certificates and additional configuration files (e.g. Kubernetes apiserver certificates and kubeconfig).

### Generate Templates

Here is an example of how to generate a new deployment. This example assumes you are using [examples/kubernetes.json](../examples/kubernetes.json).

1. Before starting ensure you have generated a valid [SSH Public/Private key pair](ssh.md#ssh-key-generation).
2. edit [examples/kubernetes.json](../examples/kubernetes.json) and fill in the blanks.
3. run `./bin/acs-engine generate examples/kubernetes.json` to generate the templates in the _output/Kubernetes-UNIQUEID directory. The UNIQUEID is a hash of your master's FQDN prefix.
4. now you can use the `azuredeploy.json` and `azuredeploy.parameters.json` for deployment as described in [deployment usage](../acsengine.md#deployment-usage).

**Note:** If you wish to customize cluster configuaration after the `generate` step, make sure to modify `apimodel.json` in the `_output` directory. This ensures that any computed settings and generated certificates are maintained. For example, if you want to add a second agent pool, edit `apimodel.json` and then run `acs-engine` against that file to generate and updated ARM template. This ensures that during the deploy steps, existing resources remain untouched and new agent pools are created.

This setup mounts the `acs-engine` source directory as a volume into the Docker container.
This means that you can edit your source code normally in your favorite editor on your
machine, while still being able to compile and test inside of the Docker container (the
same environment used in our Continuous Integration system).

When the execution of `devenv.{ps1,sh}` completes, you should find the console logged into the container.
<a href="#deployment-usage"></a>

Now we need to do a one-time call to setup the prerequisites.
### Deploy Templates

Generated templates can be deployed using [the Azure CLI 2.0](https://github.com/Azure/azure-cli) or [Powershell](https://github.com/Azure/azure-powershell).

#### Deploying with Azure CLI 2.0

Azure CLI 2.0 is the latest CLI maintained and supported by Microsoft. For installation instructions see [the Azure CLI GitHub repository](https://github.com/Azure/azure-cli#installation) for the latest release.

```bash
$ az login

$ az account set --subscription "<SUBSCRIPTION NAME OR ID>"

$ az group create \
--name "<RESOURCE_GROUP_NAME>" \
--location "<LOCATION>"

$ az group deployment create \
--name "<DEPLOYMENT NAME>" \
--resource-group "<RESOURCE_GROUP_NAME>" \
--template-file "./_output/<INSTANCE>/azuredeploy.json" \
--parameters "./_output/<INSTANCE>/azuredeploy.parameters.json"
```
make bootstrap

#### Deploying with Powershell

```powershell
Add-AzureRmAccount
Select-AzureRmSubscription -SubscriptionID <SUBSCRIPTION_ID>
New-AzureRmResourceGroup `
-Name <RESOURCE_GROUP_NAME> `
-Location <LOCATION>
New-AzureRmResourceGroupDeployment `
-Name <DEPLOYMENT_NAME> `
-ResourceGroupName <RESOURCE_GROUP_NAME> `
-TemplateFile _output\<INSTANCE>\azuredeploy.json `
-TemplateParameterFile _output\<INSTANCE>\azuredeploy.parameters.json
```

As a final step, in order to get the `acs-engine` tool ready, you should build the sources with:
<a href="#build-from-source"></a>

## Build ACS Engine from Source

### Docker Development Environment

The easiest way to start hacking on `acs-engine` is to use a Docker-based environment. If you already have Docker installed then you can get started with a few commands.

* Windows (PowerShell): `.\scripts\devenv.ps1`
* Linux/OSX (bash): `./scripts/devenv.sh`

This script mounts the `acs-engine` source directory as a volume into the Docker container, which means you can edit your source code in your favorite editor on your machine, while still being able to compile and test inside of the Docker container. This environment mirrors the environment used in the acs-engine continuous integration (CI) system.

When the script `devenv.ps1` or `devenv.sh` completes, you will be left at a command prompt.

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

```
# install and download build dependencies
make prereqs
# build the `acs-engine` binary
make build
```

When the build process completes, verify that `acs-engine` is available, invoking the command without parameters.
You should see something like this:
The build process leaves the compiled `acs-engine` binary in the `bin` directory. Make sure everything completed successfully bu running `bin/acs-engine` without any arguments:

```
# ./bin/acs-engine
Expand All @@ -39,6 +115,7 @@ Usage:
acs-engine [command]
Available Commands:
deploy deploy an Azure Resource Manager template
generate Generate an Azure Resource Manager template
help Help about any command
version Print the version of ACS-Engine
Expand All @@ -52,105 +129,50 @@ Use "acs-engine [command] --help" for more information about a command.

[Here's a quick demo video showing the dev/build/test cycle with this setup.](https://www.youtube.com/watch?v=lc6UZmqxQMs)

# Downloading and Building ACS Engine Locally
## Building on Windows, OSX, and Linux

ACS Engine can also be built and run natively on Windows, OS X, and Linux. Instructions below:
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:

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

Requirements:
- Git for Windows. Download and install [here](https://git-scm.com/download/win)
- Go for Windows. Download and install [here](https://golang.org/dl/), accept all defaults.
- Powershell
### Windows

Build Steps:
Setup steps:

1. Setup your go workspace. This example assumes you are using `c:\gopath` as your workspace:
1. Windows key-R to open the run prompt
2. `rundll32 sysdm.cpl,EditEnvironmentVariables` to open the system variables
3. add `c:\go\bin` to your PATH variables
4. click "new" and add new environment variable GOPATH and set to `c:\gopath`
1. 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` to your PATH variables
4. Click "new" and add new environment variable named `GOPATH` and set the value to `c:\gopath`

Build acs-engine:
1. Windows key-R to open the run prompt
2. `cmd` to open command prompt
3. mkdir %GOPATH%
4. cd %GOPATH%
5. type `go get github.com/Azure/acs-engine` to get the acs-engine Github project
6. type `go get all` to get the supporting components
7. `cd %GOPATH%\src\github.com\Azure\acs-engine`
8. `go build` to build the project
3. `acs-engine` to see the command line parameters

## OS X
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
4. Type `cd %GOPATH%`
5. Type `go get github.com/Azure/acs-engine` to download acs-engine from GitHub
6. Type `go get all` to get the supporting components
7. Type `cd %GOPATH%\src\github.com\Azure\acs-engine`
8. Type `go build` to build the project
9. Run `bin\acs-engine` to see the command line parameters

Requirements:
- Go for OS X. Download and install [here](https://golang.org/dl/)
### OS X and Linux

Build Steps:
Setup steps:

1. Open a command prompt to setup your gopath:
2. `mkdir $HOME/gopath`
2. `mkdir $HOME/go`
3. edit `$HOME/.bash_profile` and add the following lines to setup your go path
```
export PATH=$PATH:/usr/local/go/bin
export GOPATH=$HOME/gopath
export GOPATH=$HOME/go
```
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 `go get all` to get the supporting components
3. `cd $GOPATH/src/github.com/Azure/acs-engine`
4. `go build` to build the project
5. `./acs-engine` to see the command line parameters

## Linux

Requirements:
- Go for Linux
- Download the appropriate archive for your system [here](https://golang.org/dl/)
- sudo tar -C /usr/local -xzf go$VERSION.$OS-$ARCH.tar.gz (replace with your downloaded archive)
- `git`

Build Steps:

1. Setup Go path:
2. `mkdir $HOME/gopath`
3. edit `$HOME/.profile` and add the following lines to setup your go path
```
export PATH=$PATH:/usr/local/go/bin
export GOPATH=$HOME/gopath
```
4. `source $HOME/.profile`

Build acs-engine:
1. type `go get github.com/Azure/acs-engine` to get the acs-engine Github project
2. type `go get all` to get the supporting components
3. `cd $GOPATH/src/github.com/Azure/acs-engine`
4. `go build` to build the project
5. `./acs-engine` to see the command line parameters


# Template Generation

The `acs-engine` takes a json [cluster definition file](clusterdefinition.md) as a parameter and generates 3 or more of the following files:

1. **apimodel.json** - this is the cluster configuration file used for generation
2. **azuredeploy.json** - this is the main ARM (Azure Resource Model) template used to deploy a full Docker enabled cluster
3. **azuredeploy.parameters.json** - this is the parameters file used along with azurdeploy.json during deployment and contains configurable parameters
4. **certificate and access config files** - some orchestrators like Kubernetes require certificate generation, and these generated files and access files like the kube config files are stored along side the model and ARM template files.

As a rule of thumb you should always work with the `apimodel.json` when modifying an existing running deployment. This ensures that all the same settings and certificates are correctly preserved. For example, if you want to add a second agent pool, you would edit `apimodel.json` and then run `acs-engine` against that file to generate the new ARM templates. Then during deployment all existing deployments remain untouched, and only the new agent pools resources are created.

# Generating a template

Here is an example of how to generate a new deployment. This example assumes you are using [examples/kubernetes.json](../examples/kubernetes.json).

1. Before starting ensure you have generated a valid [SSH Public/Private key pair](ssh.md#ssh-key-generation).
2. edit [examples/kubernetes.json](../examples/kubernetes.json) and fill in the blanks.
3. run `./bin/acs-engine generate examples/kubernetes.json` to generate the templates in the _output/Kubernetes-UNIQUEID directory. The UNIQUEID is a hash of your master's FQDN prefix.
4. now you can use the `azuredeploy.json` and `azuredeploy.parameters.json` for deployment as described in [deployment usage](../README.md#deployment-usage).

# Deploying templates

For deployment see [deployment usage](../README.md#deployment-usage).
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 rereqs` to install supporting components
4. Type `make build` to build the project
5. Type `./bin/acs-engine` to see the command line parameters
4 changes: 2 additions & 2 deletions docs/acsengine.zh-CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,8 +139,8 @@ ACS引擎使用json格式的[集群定义文件](clusterdefinition.md)作为输
1. 首先需要准备一个[SSH 公钥私钥对](ssh.md#ssh-key-generation).
2. 编辑[examples/kubernetes.json](../examples/kubernetes.json)将其需要的参数配置好.
3. 运行`./bin/acs-engine generate examples/kubernetes.json`命令在_output/Kubernetes-UNIQUEID目录中生成对应的模板。（UNIQUEID是master节点的FQDN前缀的hash值）
4. 按照README中指定的方式使用`azuredeploy.json`和`azuredeploy.parameters.json`部署容器集群 [deployment usage](../README.md#deployment-usage).
4. 按照README中指定的方式使用`azuredeploy.json`和`azuredeploy.parameters.json`部署容器集群 [deployment usage](../acsengine.md#deployment-usage).

# 部署方法

[部署方式请参考这里](../README.md#deployment-usage).
[部署方式请参考这里](../acsengine.md#deployment-usage).
Loading

0 comments on commit c944b67

Please sign in to comment.