This repository has been archived by the owner on Oct 24, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 521
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add documentation for acs-engine (#60)
* initial walkthrough docs * fix typos
- Loading branch information
Showing
95 changed files
with
7,416 additions
and
6,683 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| # Microsoft Azure Container Service Engine - Builds Docker Enabled Clusters | ||
|
|
||
| ## Overview | ||
|
|
||
| This cluster definition examples demonstrate how to create a customized Docker Enabled Cluster on Microsoft Azure. | ||
|
|
||
| ## User Guides | ||
|
|
||
| * [ACS Engine](acsengine.md) - shows you how to build and use the ACS engine to generate custom Docker enabled container clusters | ||
| * [Cluster Definition](clusterdefinition.md) - describes the components of the cluster definition file | ||
| * [DCOS Walkthrough](dcos.md) - shows how to create a DCOS enabled Docker cluster on Azure | ||
| * [Kubernetes Walkthrough](kubernetes.md) - shows how to create a Kubernetes enabled Docker cluster on Azure | ||
| * [Swarm Walkthrough](swarm.md) - shows how to create a Swarm enabled Docker cluster on Azure | ||
| * [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 | ||
| * [Managed Disks](../examples/disks-managed) (under private preview) - shows how to use managed disks | ||
| * [Large Clusters](../examples/largeclusters) - shows how to create cluster sizes of up to 1200 nodes | ||
| * [Windows Clusters](../examples/windows) - shows how to create windows or mixed Microsoft Windows and Linux Docker clusters on Microsoft Azure |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| # 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. | ||
|
|
||
| # Downloading and Building ACS Engine | ||
|
|
||
| Here are the instructions for downloading and building the ACS Engine for Windows, OS X, and Linux. | ||
|
|
||
| ## Windows | ||
|
|
||
| Here is how to download and building ACS Engine: | ||
|
|
||
| 1. Download and install [git for windows](https://git-scm.com/download/win) | ||
| 2. Download and install [Go for Windows](https://golang.org/dl/), accept all defaults. | ||
| 3. 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` | ||
| 4. 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 | ||
| 9. `acs-engine` to see the command line parameters | ||
|
|
||
| ## OS X | ||
|
|
||
| 1. Download and install [Go for OS X](https://golang.org/dl/) | ||
| 2. Open a command prompt to setup your gopath: | ||
| 1. `mkdir $HOME/go` | ||
| 2. edit `$HOME/.profile` and add the following line to setup your go path | ||
| ``` | ||
| export PATH=$PATH:/usr/local/go/bin | ||
| export GOPATH=$HOME/gopath | ||
| ``` | ||
| 3. `source $HOME/.profile` | ||
| 3. 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 | ||
|
|
||
| For Linux, ensure Docker is installed, and follow the developer instructions at https://github.com/Azure/acs-engine#development-docker to build and use the ACS Engine. | ||
|
|
||
| # 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/dcos.json](../examples/dcos.json). | ||
|
|
||
| 1. Before starting ensure you have generated a valid [SSH Public/Private key pair](SSHKeyManagement.md). | ||
| 2. edit [examples/dcos.json](../examples/dcos.json) and fill in the blanks. | ||
| 3. run `acs-engine examples/dcos.json` to generate the templates in the _output/DCOS184-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 | ||
|
|
||
| # Deploying templates | ||
|
|
||
| For deployment see [deployment usage](../README.md#deployment-usage). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| # Microsoft Azure Container Service Engine - Cluster Definition | ||
|
|
||
| ##Cluster Defintions for apiVersion "vlabs" | ||
|
|
||
| Here are the cluster definitions for apiVersion "vlabs" | ||
|
|
||
| ### apiVersion | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |apiVersion|yes|The version of the template. For "vlabs" the value is "vlabs".| | ||
|
|
||
| ### orchestratorProfile | ||
| `orchestratorProfile` describes the orchestrator settings. | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |orchestratorType|yes|This specifies the orchestrator type for the cluster.| | ||
|
|
||
| Here are the valid values for the orchestrator types: | ||
|
|
||
| 1. `DCOS` - this represents the [DC/OS orchestrator](dcos.md). [Older versions of DCOS173 and DCOS184 may be specified](../examples/dcos-versions). | ||
| 2. `Kubernetes` - this represents the [Kubernetes orchestrator](kubernetes.md). | ||
| 3. `Swarm` - this represents the [Swarm orchestrator](swarm.md). | ||
|
|
||
| ### masterProfile | ||
| `masterProfile` describes the settings for master configuration. | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |count|yes|Masters have count value of 1, 3, or 5 masters| | ||
| |dnsPrefix|yes|this is the dns prefix for the masters FQDN. The master FQDN is used for SSH or commandline access. This must be a unique name. ([bring your own VNET examples](../examples/vnet))| | ||
| |firstConsecutiveStaticIP|only required when vnetSubnetId specified|this is the IP address of the first master. IP Addresses will be assigned consecutively to additional master nodes.| | ||
| |vmsize|yes|Describes a valid [Azure VM Sizes](https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-windows-sizes/). These are restricted machines with at least 2 cores and 100GB of ephemeral disk space.| | ||
| |vnetSubnetId|no|specifies the Id of an alternate VNET subnet. The subnet id must specify a valid VNET ID owned by the same subscription. ([bring your own VNET examples](../examples/vnet))| | ||
|
|
||
| ### agentPoolProfiles | ||
| A cluster can have 0 to 12 agent pool profiles. Agent Pool Profiles are used for creating agents with different capabilities such as VMSizes, VMSS or Availability Set, Public/Private access, [attached storage disks](../examples/disks-storageaccount), [attached managed disks](../examples/disks-managed), or [Windows](../examples/windows). | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |availabilityProfile|no, defaults to `VirtualMachineScaleSets`| You can choose between `VirtualMachineScaleSets` and `AvailabilitySet`. As a rule of thumb always choose `VirtualMachineScaleSets` unless you need features such as dynamic attached disks or require Kubernetes| | ||
| |count|yes|Describes the node count| | ||
| |diskSizesGB|no|describes an array of up to 4 attached disk sizes. Valid disk size values are between 1 and 1024.| | ||
| |dnsPrefix|required if agents are to be exposed publically with a load balancer|this is the dns prefix that forms the FQDN to access the loadbalancer for this agent pool. This must be a unique name among all agent pools.| | ||
| |name|yes|This is the unique name for the agent pool profile. The resources of the agent pool profile are derived from this name.| | ||
| |ports|only required if needed for exposing services publically|Describes an array of ports need for exposing publically. A tcp probe is configured for each port and only opens to an agent node if the agent node is listening on that port. A maximum of 150 ports may be specified.| | ||
| |storageProfile|no, defaults to `StorageAccount`|specifies the storage profile to use. Valid values are [StorageAccount](../examples/disks-storageaccount) or [ManagedDisks](../examples/disks-managed)| | ||
| |vmsize|yes|Describes a valid [Azure VM Sizes](https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-windows-sizes/). These are restricted to machines with at least 2 cores| | ||
| |vnetSubnetId|no|specifies the Id of an alternate VNET subnet. The subnet id must specify a valid VNET ID owned by the same subscription. ([bring your own VNET examples](../examples/vnet))| | ||
|
|
||
| ### linuxProfile | ||
|
|
||
| `linuxProfile` provides the linux configuration for each linux node in the cluster | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |adminUsername|yes|describes the username to be used on all linux clusters| | ||
| |ssh.publicKeys.keyData|yes|The public SSH key used for authenticating access to all Linux nodes in the cluster. Here are instructions for [generating a public/private key pair](ssh.md#ssh-key-generation).| | ||
|
|
||
| ### servicePrincipalProfile | ||
|
|
||
| `servicePrincipalProfile` describes an Azure Service credentials to be used by the cluster for self-configuration. See [service principal](serviceprincipal.md) for more details on creation. | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |servicePrincipalClientID|yes, for Kubernetes clusters|describes the Azure client id. It is recommended to use a separate client ID per cluster| | ||
| |servicePrincipalClientSecret|yes, for Kubernetes clusters|describes the Azure client secret. It is recommended to use a separate client secret per client id| | ||
|
|
||
| ##Cluster Defintions for apiVersion "2016-03-30" | ||
|
|
||
| Here are the cluster definitions for apiVersion "2016-03-30". This matches the api version of the Azure Container Service Engine. | ||
|
|
||
| ### apiVersion | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |apiVersion|yes|The version of the template. For "2016-03-30" the value is "2016-03-30".| | ||
|
|
||
| ### orchestratorProfile | ||
| `orchestratorProfile` describes the orchestrator settings. | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |orchestratorType|yes|This specifies the orchestrator type for the cluster.| | ||
|
|
||
| Here are the valid values for the orchestrator types: | ||
|
|
||
| 1. `DCOS` - this represents the [DC/OS orchestrator](dcos.md). | ||
| 2. `Swarm` - this represents the [Swarm orchestrator](swarm.md). | ||
|
|
||
| ### masterProfile | ||
| `masterProfile` describes the settings for master configuration. | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |count|yes|Masters have count value of 1, 3, or 5 masters| | ||
| |dnsPrefix|yes|this is the dns prefix for the masters FQDN. The master FQDN is used for SSH or commandline access. This must be a unique name. ([bring your own VNET examples](../examples/vnet))| | ||
|
|
||
| ### agentPoolProfiles | ||
| For apiVersion "2016-03-30", a cluster may have only 1 agent pool profiles. | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |count|yes|Describes the node count| | ||
| |dnsPrefix|required if agents are to be exposed publically with a load balancer|this is the dns prefix that forms the FQDN to access the loadbalancer for this agent pool. This must be a unique name among all agent pools.| | ||
| |name|yes|This is the unique name for the agent pool profile. The resources of the agent pool profile are derived from this name.| | ||
| |vmsize|yes|Describes a valid [Azure VM Sizes](https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-windows-sizes/). These are restricted to machines with at least 2 cores| | ||
|
|
||
| ### linuxProfile | ||
|
|
||
| `linuxProfile` provides the linux configuration for each linux node in the cluster | ||
|
|
||
| |Name|Required|Description| | ||
| |---|---|---| | ||
| |adminUsername|yes|describes the username to be used on all linux clusters| | ||
| |ssh.publicKeys.keyData|yes|The public SSH key used for authenticating access to all Linux nodes in the cluster. Here are instructions for [generating a public/private key pair](ssh.md#ssh-key-generation).| |
Oops, something went wrong.