You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jan 11, 2023. It is now read-only.
**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.
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.
91
-
92
-
```bash
93
-
$ az login
94
-
95
-
$ az account set --subscription "<SUBSCRIPTION NAME OR ID>"
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 [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
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.
3
+
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.
4
4
5
-
# Development in Docker
5
+
<ahref="#install-acs-engine"></a>
6
6
7
-
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.
7
+
## Install
8
8
9
-
* Windows (PowerShell): `.\scripts\devenv.ps1`
10
-
* Linux/OSX (bash): `./scripts/devenv.sh`
9
+
Binary downloads for the latest verison of acs-engine are available here:
Download `acs-engine` for your operating system. Extract the binary and copy it to your `$PATH`.
16
+
17
+
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.
18
+
19
+
## Usage
20
+
21
+
`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:
22
+
23
+
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.
24
+
2.**azuredeploy.json**: represents a complete description of all Azure resources required to fulfill the cluster definition from `apimodel.json`.
25
+
3.**azuredeploy.parameters.json**: the parameters file holds a series of custom variables which are used in various locations throughout `azuredeploy.json`.
26
+
4.**certificate and access config files**: orchestrators like Kubernetes require certificates and additional configuration files (e.g. Kubernetes apiserver certificates and kubeconfig).
27
+
28
+
### Generate Templates
29
+
30
+
Here is an example of how to generate a new deployment. This example assumes you are using [examples/kubernetes.json](../examples/kubernetes.json).
31
+
32
+
1. Before starting ensure you have generated a valid [SSH Public/Private key pair](ssh.md#ssh-key-generation).
33
+
2. edit [examples/kubernetes.json](../examples/kubernetes.json) and fill in the blanks.
34
+
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.
35
+
4. now you can use the `azuredeploy.json` and `azuredeploy.parameters.json` for deployment as described in [deployment usage](../acsengine.md#deployment-usage).
36
+
37
+
**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.
11
38
12
-
This setup mounts the `acs-engine` source directory as a volume into the Docker container.
13
-
This means that you can edit your source code normally in your favorite editor on your
14
-
machine, while still being able to compile and test inside of the Docker container (the
15
-
same environment used in our Continuous Integration system).
16
39
17
-
When the execution of `devenv.{ps1,sh}` completes, you should find the console logged into the container.
40
+
<ahref="#deployment-usage"></a>
18
41
19
-
Now we need to do a one-time call to setup the prerequisites.
42
+
### Deploy Templates
20
43
44
+
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).
45
+
46
+
#### Deploying with Azure CLI 2.0
47
+
48
+
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.
49
+
50
+
```bash
51
+
$ az login
52
+
53
+
$ az account set --subscription "<SUBSCRIPTION NAME OR ID>"
As a final step, in order to get the `acs-engine` tool ready, you should build the sources with:
84
+
<ahref="#build-from-source"></a>
85
+
86
+
## Build ACS Engine from Source
87
+
88
+
### Docker Development Environment
89
+
90
+
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.
91
+
92
+
* Windows (PowerShell): `.\scripts\devenv.ps1`
93
+
* Linux/OSX (bash): `./scripts/devenv.sh`
94
+
95
+
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.
96
+
97
+
When the script `devenv.ps1` or `devenv.sh` completes, you will be left at a command prompt.
98
+
99
+
Run the following commands to pull the latest dependencies and build the `acs-engine` tool.
26
100
27
101
```
102
+
# install and download build dependencies
103
+
make prereqs
104
+
# build the `acs-engine` binary
28
105
make build
29
106
```
30
107
31
-
When the build process completes, verify that `acs-engine` is available, invoking the command without parameters.
32
-
You should see something like this:
108
+
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:
33
109
34
110
```
35
111
# ./bin/acs-engine
@@ -39,6 +115,7 @@ Usage:
39
115
acs-engine [command]
40
116
41
117
Available Commands:
118
+
deploy deploy an Azure Resource Manager template
42
119
generate Generate an Azure Resource Manager template
43
120
help Help about any command
44
121
version Print the version of ACS-Engine
@@ -52,105 +129,50 @@ Use "acs-engine [command] --help" for more information about a command.
52
129
53
130
[Here's a quick demo video showing the dev/build/test cycle with this setup.](https://www.youtube.com/watch?v=lc6UZmqxQMs)
54
131
55
-
#Downloading and Building ACS Engine Locally
132
+
## Building on Windows, OSX, and Linux
56
133
57
-
ACS Engine can also be built and run natively on Windows, OS X, and Linux. Instructions below:
134
+
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:
58
135
59
-
## Windows
136
+
1. Go version 1.8 [installation instructions](https://golang.org/doc/install)
137
+
2. Git Version Control [installation instructions](https://git-scm.com/download/)
60
138
61
-
Requirements:
62
-
- Git for Windows. Download and install [here](https://git-scm.com/download/win)
63
-
- Go for Windows. Download and install [here](https://golang.org/dl/), accept all defaults.
64
-
- Powershell
139
+
### Windows
65
140
66
-
Build Steps:
141
+
Setup steps:
67
142
68
-
1. Setup your go workspace. This example assumes you are using `c:\gopath` as your workspace:
69
-
1. Windows key-R to open the run prompt
70
-
2.`rundll32 sysdm.cpl,EditEnvironmentVariables` to open the system variables
71
-
3.add`c:\go\bin` to your PATH variables
72
-
4.click "new" and add new environment variable GOPATH and set to `c:\gopath`
143
+
1. Setup your go workspace. This guide assumes you are using `c:\gopath` as your Go workspace:
144
+
1.Type Windows key-R to open the run prompt
145
+
2.Type `rundll32 sysdm.cpl,EditEnvironmentVariables` to open the system variables
146
+
3.Add`c:\go\bin` to your PATH variables
147
+
4.Click "new" and add new environment variable named `GOPATH` and set the value to `c:\gopath`
73
148
74
149
Build acs-engine:
75
-
1. Windows key-R to open the run prompt
76
-
2.`cmd` to open command prompt
77
-
3. mkdir %GOPATH%
78
-
4. cd %GOPATH%
79
-
5. type `go get github.com/Azure/acs-engine` to get the acs-engine Github project
80
-
6. type `go get all` to get the supporting components
81
-
7.`cd %GOPATH%\src\github.com\Azure\acs-engine`
82
-
8.`go build` to build the project
83
-
3.`acs-engine` to see the command line parameters
84
-
85
-
## OS X
150
+
1. Type Windows key-R to open the run prompt
151
+
2. Type `cmd` to open a command prompt
152
+
3. Type `mkdir %GOPATH%` to create your gopath
153
+
4. Type `cd %GOPATH%`
154
+
5. Type `go get github.com/Azure/acs-engine` to download acs-engine from GitHub
155
+
6. Type `go get all` to get the supporting components
156
+
7. Type `cd %GOPATH%\src\github.com\Azure\acs-engine`
157
+
8. Type `go build` to build the project
158
+
9. Run `bin\acs-engine` to see the command line parameters
86
159
87
-
Requirements:
88
-
- Go for OS X. Download and install [here](https://golang.org/dl/)
160
+
### OS X and Linux
89
161
90
-
Build Steps:
162
+
Setup steps:
91
163
92
164
1. Open a command prompt to setup your gopath:
93
-
2.`mkdir $HOME/gopath`
165
+
2.`mkdir $HOME/go`
94
166
3. edit `$HOME/.bash_profile` and add the following lines to setup your go path
95
167
```
96
168
export PATH=$PATH:/usr/local/go/bin
97
-
export GOPATH=$HOME/gopath
169
+
export GOPATH=$HOME/go
98
170
```
99
171
4.`source $HOME/.bash_profile`
100
-
Build acs-engine:
101
-
1. type `go get github.com/Azure/acs-engine` to get the acs-engine Github project
102
-
2. type `go get all` to get the supporting components
103
-
3.`cd $GOPATH/src/github.com/Azure/acs-engine`
104
-
4.`go build` to build the project
105
-
5.`./acs-engine` to see the command line parameters
106
-
107
-
## Linux
108
-
109
-
Requirements:
110
-
- Go for Linux
111
-
- Download the appropriate archive for your system [here](https://golang.org/dl/)
112
-
- sudo tar -C /usr/local -xzf go$VERSION.$OS-$ARCH.tar.gz (replace with your downloaded archive)
113
-
-`git`
114
-
115
-
Build Steps:
116
-
117
-
1. Setup Go path:
118
-
2.`mkdir $HOME/gopath`
119
-
3. edit `$HOME/.profile` and add the following lines to setup your go path
120
-
```
121
-
export PATH=$PATH:/usr/local/go/bin
122
-
export GOPATH=$HOME/gopath
123
-
```
124
-
4.`source $HOME/.profile`
125
172
126
173
Build acs-engine:
127
-
1. type `go get github.com/Azure/acs-engine` to get the acs-engine Github project
128
-
2. type `go get all` to get the supporting components
129
-
3.`cd $GOPATH/src/github.com/Azure/acs-engine`
130
-
4.`go build` to build the project
131
-
5.`./acs-engine` to see the command line parameters
132
-
133
-
134
-
# Template Generation
135
-
136
-
The `acs-engine` takes a json [cluster definition file](clusterdefinition.md) as a parameter and generates 3 or more of the following files:
137
-
138
-
1.**apimodel.json** - this is the cluster configuration file used for generation
139
-
2.**azuredeploy.json** - this is the main ARM (Azure Resource Model) template used to deploy a full Docker enabled cluster
140
-
3.**azuredeploy.parameters.json** - this is the parameters file used along with azurdeploy.json during deployment and contains configurable parameters
141
-
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.
142
-
143
-
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.
144
-
145
-
# Generating a template
146
-
147
-
Here is an example of how to generate a new deployment. This example assumes you are using [examples/kubernetes.json](../examples/kubernetes.json).
148
-
149
-
1. Before starting ensure you have generated a valid [SSH Public/Private key pair](ssh.md#ssh-key-generation).
150
-
2. edit [examples/kubernetes.json](../examples/kubernetes.json) and fill in the blanks.
151
-
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.
152
-
4. now you can use the `azuredeploy.json` and `azuredeploy.parameters.json` for deployment as described in [deployment usage](../README.md#deployment-usage).
153
-
154
-
# Deploying templates
155
-
156
-
For deployment see [deployment usage](../README.md#deployment-usage).
174
+
1. Type `go get github.com/Azure/acs-engine` to get the acs-engine Github project
175
+
2. Type `cd $GOPATH/src/github.com/Azure/acs-engine` to change to the source directory
176
+
3. Type `make rereqs` to install supporting components
177
+
4. Type `make build` to build the project
178
+
5. Type `./bin/acs-engine` to see the command line parameters
0 commit comments