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 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.
- Windows (PowerShell):
.\scripts\devenv.ps1
- Linux (bash):
./scripts/devenv.sh
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. As a final step, in order to get the acs-engine
tool ready, you should build the sources with:
make build
When the build process completes, verify that acs-engine
is available, invoking the command without parameters.
You should see something like this:
# acs-engine
Usage of acs-engine:
-artifacts string
directory where artifacts will be written
-caCertificatePath string
the path to the CA Certificate file
-caKeyPath string
the path to the CA key file
-classicMode
enable classic parameters and outputs
-noPrettyPrint
do not pretty print output
-parametersOnly
only output the parameters
Here's a quick demo video showing the dev/build/test cycle with this setup.
ACS Engine can also be built and run natively on Windows, OS X, and Linux. Instructions below:
Requirements:
- Git for Windows. Download and install here
- Go for Windows. Download and install here, accept all defaults.
- Powershell
Build Steps:
- Setup your go workspace. This example assumes you are using
c:\gopath
as your workspace: - Windows key-R to open the run prompt
rundll32 sysdm.cpl,EditEnvironmentVariables
to open the system variables- add
c:\go\bin
to your PATH variables - click "new" and add new environment variable GOPATH and set to
c:\gopath
- Build acs-engine:
- Windows key-R to open the run prompt
cmd
to open command prompt- mkdir %GOPATH%
- cd %GOPATH%
- type
go get github.com/Azure/acs-engine
to get the acs-engine Github project - type
go get all
to get the supporting components cd %GOPATH%\src\github.com\Azure\acs-engine
go build
to build the projectacs-engine
to see the command line parameters
Requirements:
- Go for OS X. Download and install here
Build Steps:
- Open a command prompt to setup your gopath:
mkdir $HOME/gopath
- edit
$HOME/.bash_profile
and add the following line to setup your go path
export PATH=$PATH:/usr/local/go/bin
export GOPATH=$HOME/gopath
source $HOME/.sh_profile
- Build acs-engine:
- type
go get github.com/Azure/acs-engine
to get the acs-engine Github project - type
go get all
to get the supporting components cd $GOPATH/src/github.com/Azure/acs-engine
go build
to build the project./acs-engine
to see the command line parameters
Requirements:
- Go for Linux
- Download the appropriate archive for your system here
- sudo tar -C /usr/local -xzf go$VERSION.$OS-$ARCH.tar.gz (replace with your downloaded archive)
git
Build Steps:
- Setup Go path:
mkdir $HOME/gopath
- edit
$HOME/.profile
and add the following line to setup your go path
export PATH=$PATH:/usr/local/go/bin
export GOPATH=$HOME/gopath
source $HOME/.profile
- Build acs-engine:
- type
go get github.com/Azure/acs-engine
to get the acs-engine Github project - type
go get all
to get the supporting components cd $GOPATH/src/github.com/Azure/acs-engine
go build
to build the project./acs-engine
to see the command line parameters
The acs-engine
takes a json cluster definition file as a parameter and generates 3 or more of the following files:
- apimodel.json - this is the cluster configuration file used for generation
- azuredeploy.json - this is the main ARM (Azure Resource Model) template used to deploy a full Docker enabled cluster
- azuredeploy.parameters.json - this is the parameters file used along with azurdeploy.json during deployment and contains configurable parameters
- 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.
Here is an example of how to generate a new deployment. This example assumes you are using examples/kubernetes.json.
- Before starting ensure you have generated a valid SSH Public/Private key pair.
- edit examples/kubernetes.json and fill in the blanks.
- run
acs-engine examples/kubernetes.json
to generate the templates in the _output/Kubernetes-UNIQUEID directory. The UNIQUEID is a hash of your master's FQDN prefix. - now you can use the
azuredeploy.json
andazuredeploy.parameters.json
for deployment as described in deployment usage.
For deployment see deployment usage.