From c11c26915e4b84e298e7e5b6d13602ac7a5c587a Mon Sep 17 00:00:00 2001 From: Cole Mickens Date: Wed, 26 Oct 2016 15:41:17 -0700 Subject: [PATCH] Add devenv for building/testing/validating under Docker --- .dockerignore | 6 +- .gitattributes | 1 + .gitignore | 4 -- Dockerfile | 22 ++++--- Makefile | 8 +-- README.md | 153 ++++++++++++++++++++++++++------------------ scripts/dev.sh | 4 -- scripts/devenv.ps1 | 8 +++ scripts/devenv.sh | 12 ++++ scripts/generate.sh | 12 ---- 10 files changed, 135 insertions(+), 95 deletions(-) create mode 100644 .gitattributes delete mode 100644 scripts/dev.sh create mode 100644 scripts/devenv.ps1 create mode 100755 scripts/devenv.sh delete mode 100644 scripts/generate.sh diff --git a/.dockerignore b/.dockerignore index 33122bb45..cb38a6cac 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,2 +1,4 @@ -./acsengine -./acsengine.exe +acs-engine +acs-engine.exe +_output/ +.git/ diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..aecf25037 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* -crlf diff --git a/.gitignore b/.gitignore index ba470e8d9..990646b7e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,3 @@ -*.anthony.json -deployVM0.ps1 -noparams.json -output* acs-engine.exe acs-engine _output/ diff --git a/Dockerfile b/Dockerfile index d91ed0f01..dd2071c69 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,17 +1,23 @@ FROM buildpack-deps:xenial +ENV GO_VERSION 1.7.3 +ENV KUBECTL_VERSION 1.4.4 +ENV AZURE_CLI_VERSION 0.1.0b8 + RUN apt-get update \ - && apt-get -y upgrade \ - && apt-get -y install python-pip make build-essential curl openssl vim jq \ - && rm -rf /var/lib/apt/lists/* + && apt-get -y upgrade \ + && apt-get -y install python-pip make build-essential curl openssl vim jq \ + && rm -rf /var/lib/apt/lists/* -RUN curl 'https://godeb.s3.amazonaws.com/godeb-amd64.tar.gz' > /tmp/godeb.tar.gz \ - && (cd /tmp/; tar zvxf godeb.tar.gz; ./godeb install 1.7.3) +RUN mkdir /tmp/godeb \ + && curl "https://godeb.s3.amazonaws.com/godeb-amd64.tar.gz" > /tmp/godeb/godeb.tar.gz \ + && (cd /tmp/godeb; tar zvxf godeb.tar.gz; ./godeb install "${GO_VERSION}") \ + && rm -rf /tmp/godeb -RUN pip install azure-cli==0.1.0b8 +RUN pip install "azure-cli==${AZURE_CLI_VERSION}" -RUN curl https://storage.googleapis.com/kubernetes-release/release/v1.4.4/bin/linux/amd64/kubectl > /usr/local/bin/kubectl \ - && chmod +x /usr/local/bin/kubectl +RUN curl "https://storage.googleapis.com/kubernetes-release/release/v${KUBECTL_VERSION}/bin/linux/amd64/kubectl" > /usr/local/bin/kubectl \ + && chmod +x /usr/local/bin/kubectl ENV GOPATH /gopath ENV PATH "${PATH}:${GOPATH}/bin" diff --git a/Makefile b/Makefile index 5f2216ba9..ba85a5663 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,8 @@ .NOTPARALLEL: build: - go generate -v + go get . + go generate -v ./... go build -v test: @@ -16,7 +17,6 @@ lint: ci: validate-generated build test lint -dev: - docker build -t acs-engine . - docker run -it -v `pwd`:/acs-engine -w /acs-engine acs-engine /bin/bash +devenv: + ./scripts/devenv.sh diff --git a/README.md b/README.md index 7202e5192..0fce83e92 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,115 @@ -# ACSEngine - Template generator +# Azure Container Service ARM Template Generator -Template generator builds a custom template based on user requirements. Examples exist under clusterdefinitions folder. +## Overview -# Building the Application +`acs-engine` is a tool that produces ARM (Azure Resource Manager) templates for deploying various container orchestrators into Azure. +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 an Azure Container Service cluster. -To build the application: +## Development (Docker) -1. set $GOPATH (example c:\gopath) - (under Windows `SET GOPATH=c:\gopath`) -2. `go get gopkg.in/yaml.v2` -3. `go get github.com/ghodss/yaml` -4. `cd $GOPATH/github.com/Azure/acs-engine` -5. `go build` to produce the acsengine binary +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. -# Developer Instructions +* Windows (PowerShell): `.\scripts\devenv.ps1` +* Linux (bash): `.\scripts\devenv.sh` -If you want to develop and submit changes, follow these additional steps: +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). -1. Add $GOPATH\bin to your path - (under Windows `SET PATH=%PATH%;%GOPATH%\bin`) -2. `go get -u github.com/jteeuwen/go-bindata` +[Here's a quick demo video showing the dev/build/test cycle with this setup.](https://www.youtube.com/watch?v=lc6UZmqxQMs) -Then everytime you adjust content in parts directory: +## Development (Native) -1. `cd $GOPATH/github.com/Azure/acs-engine/pkg/acsengine` -2. `go generate` to generate source files needed -3. `cd $GOPATH/github.com/Azure/acs-engine` -4. `go build` to produce the acsengine binary +### Requirements +- PowerShell (Windows) +- `bash` + `make` (Linux) +- `git` +- `go` (with a properly configured GOPATH) -# Generating a Template +### Building (Linux) -Once build run the generator with the command ```./acsengine -CLUSTER_DEFINITION_FILE``` where ```CLUSTER_DEFINITION_FILE``` is the -path to the cluster definition you want to use. The application -outputs therequired ARM template. This can be piped to a file for -later use (see below). - -There are some example definition files in the folder `clusterdefinitions`. - -# Using a Template - -Generated templates can be deployed using the Azure CLI or Powershell. - -## Deploying with Powershell - -To deploy an ACS instance using Powershell and your generated template -run the following two commands: - -``` Powershell -New-AzureRmResourceGroup -Name -Location -Force -New-AzureRmResourceGroupDeployment -Name -ResourceGroupName RGName -TemplateFile +```shell +make build ``` -## Deploying with Azure CLI - -To deploy an ACS instance using the Azure CLI and your generated -template run the following two commands: - -``` bash -azure group create -azure group deployment create -f +### Building (Windows, PowerShell) +```shell +cd ${env:GOPATH}/github.com/Azure/acs-engine +go get . +go build . ``` -# Using a Docker container -The ```scripts``` directory contains helper scripts that will assist -with the using a Docker container to work with the appication. +## Contributing -## dev.sh +Please follow these instructions before submitting a PR: -Run a Go container with the application source code mounted into the -container. You can edit the code in your favorite editor on the client -while building and running the container. +1. Execute `make ci` to run the checkin validation tests. -## generate.sh +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 you're not + introducing any sort of regression. -Generate a template from a given configuration and store it in the -```generated``` folder. For example, to generate a Swarm template use: +## Usage (Template Generation) -``` bash -./scripts/generate.sh swarm.json +Usage is best demonstrated with an example: + +```shell +$ vim examples/kubernetes.classic.json + +# insert your preferred, unique DNS prefix +# insert your SSH public key + +$ ./acs-engine examples/kubernetes.classic.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.) + +## Usage (Deployment) + +Generated templates can be deployed using +[the Azure CLI](https://github.com/Azure/azure-cli) or +[Powershell](https://github.com/Azure/azure-powershell). + +### Deploying with Azure CLI + +```bash +$ az login + +$ az account set --name "" + +$ az group create \ + --name="" \ + --location="" + +$ az group deployment create \ + --name="" \ + --resource-group="" \ + --template-file="./_output//azuredeploy.json" +``` + +### Deploying with Powershell + +```powershell +Add-AzureRmAccount + +Select-AzureRmSubscription -SubscriptionID + +New-AzureRmResourceGroup ` + -Name ` + -Location + +New-AzureRmResourceGroupDeployment ` + -Name ` + -ResourceGroupName ` + -TemplateFile _output\\azuredeploy.json +``` + diff --git a/scripts/dev.sh b/scripts/dev.sh deleted file mode 100644 index a9e690a34..000000000 --- a/scripts/dev.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/bash - -docker run --rm -it -v "$PWD":/usr/src/acsengine -w /usr/src/acsengine golang bash - diff --git a/scripts/devenv.ps1 b/scripts/devenv.ps1 new file mode 100644 index 000000000..0eea746db --- /dev/null +++ b/scripts/devenv.ps1 @@ -0,0 +1,8 @@ +$pwd = (Get-Location).Path + +docker build --pull -t acs-engine . +docker run -it ` + -v ${pwd}:/gopath/src/github.com/Azure/acs-engine ` + -w /gopath/src/github.com/Azure/acs-engine ` + acs-engine /bin/bash + diff --git a/scripts/devenv.sh b/scripts/devenv.sh new file mode 100755 index 000000000..d00caf469 --- /dev/null +++ b/scripts/devenv.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash + +set -eu -o pipefail +set -x + +docker build --pull -t acs-engine . + +docker run -it \ + -v `pwd`:/gopath/src/github.com/Azure/acs-engine \ + -w /gopath/src/github.com/Azure/acs-engine \ + acs-engine /bin/bash + diff --git a/scripts/generate.sh b/scripts/generate.sh deleted file mode 100644 index ff5124627..000000000 --- a/scripts/generate.sh +++ /dev/null @@ -1,12 +0,0 @@ -#!/bin/bash - -if [ ! -d generated ] -then - mkdir -p generated -fi - -TEMPLATE_NAME=$1 - - - -docker run --rm -it -v "$PWD":/usr/src/acsengine -w /usr/src/acsengine golang bash -c "go build && ./acsengine clusterdefinitions/$TEMPLATE_NAME > generated/$TEMPLATE_NAME"