Simple Yeoman Generator to help get started with the acs-engine.
It's funny - this generator helps generate the file that acs-engine uses to generate the files that are used to deploy a cluster!
This generator works with Linux and Windows nodes. Node count for each Windows and Linux can be specified (0 to not include at all).
It generates the Windows box admin passwords and ssh keys for Linux. These are saved under ./keys post generation.
It generates scripts to deploy the cluster and to delete it again. It also helps import kubectl configs for ease of use (by making a temp env var).
See https://youtu.be/J3CZkL7rt6Y for a video demo of how to use this generator (follow this readme also!).
You'll need Powershell. This is also tested on Ubuntu 16.04.
Install acs-engine in your path.
Install kubectl in your path or just run
az aks install-cli.
Install Azure CLI.
npm install -g generator-acsengine
Use the Docker image
You can pull a pre-prepared environment in "jakkaj/acsengine".
- Install Docker
docker pull jakkaj/acsengine
docker run -d -t jakkaj/acsengine
docker ps -ato find running image id
docker exec -it <containerid> bash
./sp.shto start with your service principal
yo ascengineand you're on your way.
Things you're going to need before you start
Create an Azure Service Principle
Get your subscription id from the portal or by typing
az account list.
Getting started in the docker container
If you're in the docker container, you don't need to install anything.
To get started with a service principal you can just run the following from the home dir:
This will kick off the service principal process and save it to a local folder as "azure_sp.json".
Things to know before you start
The questions you'll be asked as you run the generator are:
How many Windows based nodes would you like?
How many Linux based nodes would you like?
How many Linux based nodes with GPU capability would you like?
- Remember to choose a region (later in the steps) that supports GPU based VMs. See this guide for more information.
What DNS prefix would you like?
- This will be the host dns name of your cluster
Please enter your service principal ClientId (AppId). If you do not know what this is, follow this guide: https://github.com/Azure/acs-engine/blob/master/docs/serviceprincipal.md
- Enter the appId from the service principle create command in to this field
Please enter your service principal password:
- Enter the password from the service principle create command in to this field
Please enter your subscription id:
- Copy this from your Azure portal or in the
az account listcommand
- Copy this from your Azure portal or in the
Please enter an Azure Resource Group name. It will be created if it does not yet exist.
- All resources will be created in this group. You can easily delete this later to clean up your work if you're just trying things out
Please enter an Azure region. Type "az account list-locations" to get the list (use the "name" field!).
- Regions look like "australiasoutheast" or "southeastasia". Make sure you copy the version that has no spaces and all lower case!
Once generated there are some scripts to run.
Generate the acs-engine output
First script take the file generated by this generator and runs it through acs-engine.
It produces files under _output/dnsName (which ever dns prefix you entered during the config stage).
Scripts are located under the Powershell or bash directories. If you're on in bash, substitute the examples where appropriate.
This script will not deploy anything yet!
From powershell run:
.\powershell\1_generate_acs_template.ps1 or ./bash/1_generate_acs_template.sh
Set up the Azure subscription ready to host the cluster
.\powershell\2_prepare_account.ps1 or ./bash/2_prepare_account.sh
This script checks the Azure CLI login status, before creating the new resource group (if it doesn't already exist).
Deploy the cluster
The big show!
.\powershell\3_deploy_cluster.ps1 or ./bash/3_deploy_cluster.sh
This will deploy the cluster by invoking an Azure deployment using the generated ARM Template and values file.
Set up kubectl config
.\powershell\4_set_kubectl_config.ps1 or cd bash . 4_set_kubectl_config.sh
Important note on bash: This script will set an environment variable, so you'll want to run
. 4_set_kubectl_config.sh (not ./4_set_kubectl_config) so it creates the variables in the same shell.
This will help you out by adding a temp env var to your current powershell session to allow kubectl to access your cluster.
You'll have to run this every new powershell session or manually integrate the file in to your central ~/.kube/config file. Check the powershell script
.\powershell\4_set_kubectl_config.ps1 for the path to the config file.
Permanently save the config
On Linux, there is a tool called kubecfg you can install (it's already in the Docker container).
npm install -g kubecfg
Navigate to the path that your config file resides and type:
kubecfg -a <filename>
To remove that file
kubecfg -r <filename>
This will update your .bashrc with the new paths.
You'll need to reload .bashrc after you've run the app (any assistance on how to elegantly do this automatically is welcome!)
Delete the resource group
.\powershell\x_delete_resource_group.ps1 or ./bash/x_delete_resource_group.sh
This will kill the resource group and everything in it. It's irreversible - be very careful you're sure you want to blow this group away!! But it's also handy if you're just playing around.
** Remember, you could have used an existing group with other things in it!! **