Quick documentation rationalization (#152)

README.md

@@ -6,13 +6,36 @@
 
 ## Overview
 
-AKS-Engine leverages ARM (Azure Resource Manager) to build Kubernetes IaaS in Azure. Originally [acs-engine](https://github.com/Azure/acs-engine), the project has moved here (1) to evolve without harming its legacy non-k8s bits that other non-k8s Azure upstream projects depend upon, and (2) to better reflect its affinity with [AKS](https://docs.microsoft.com/en-us/azure/aks), Azure's managed Kubernetes service offering.
+AKS-Engine leverages ARM (Azure Resource Manager) to build Kubernetes IaaS in Azure. AKS-Engine provides convenient tooling to quickly bootstrap clusters, and implements cluster provisioning and lifecycle operations for [AKS](https://docs.microsoft.com/en-us/azure/aks), Azure's managed Kubernetes service offering.
 
-## Under Construction
+More info, including a thorough walkthrough is [here](docs/aksengine.md).
 
-We are currently in transition from acs-engine to aks-engine! Bear with us as we stabilize this space as the future home for building customizable, self-managed Kubernetes on Azure!
+Please see the [FAQ](/docs/faq.md) for answers about AKS-Engine and its progenitor ACS-Engine.
 
-Please see the [FAQ](/docs/faq.md) for answers about AKS-Engine and this project transition.
+## User guides
+
+[This guide](docs/kubernetes.md) walks you through your first cluster deployment.
+
+These guides cover more advanced features to try out after you have built your first cluster:
+
+* [Cluster Definition](docs/clusterdefinition.md) - describes the components of the cluster definition file
+* [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) - shows how to use managed disks
+* [Large Clusters](examples/largeclusters) - shows how to create cluster sizes of up to 1200 nodes
+
+## Contributing
+
+Follow the [developers guide](docs/developers.md) to set up your environment.
+
+To build aks-engine, run `make build`. If you are developing with a working [Docker environment](https://docs.docker.com/engine), you can also run `make dev` (or `makedev.ps1` on Windows) first to start a Docker container and run `make build` inside the container.
+
+Please follow these instructions before submitting a PR:
+
+1. Execute `make test` to run unit tests.
+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 that you are not introducing any regressions.
+3. Make sure that your changes are properly documented and include relevant unit tests.
 
 ## Code of conduct
 

README_zh-CN.md

@@ -16,7 +16,7 @@
 
 ## 演示链接
 
-* [AKS Engine](docs/acsengine.md) - 演示如何使用ACS引擎来生成基于Docker的容器集群
+* [AKS Engine](docs/aksengine.md) - 演示如何使用ACS引擎来生成基于Docker的容器集群
 * [Cluster Definition](docs/clusterdefinition.md) - 详细介绍集群描述文件的格式
 * [DC/OS Walkthrough](docs/dcos.md) - 演示如何使用ACS引擎在Azure上创建DC/OS集群
 * [Kubernetes Walkthrough](docs/kubernetes.md) - 演示如何使用ACS引擎在Azure上创建Kubernetes集群

docs/README.md

@@ -1,12 +1,12 @@
-# Microsoft Azure Kubernetes Engine - Builds Kubernetes Clusters
+# AKS-Engine - Builds Kubernetes Clusters
 
 ## Overview
 
 This cluster definition examples demonstrate how to create a customized Docker Enabled Cluster on Microsoft Azure.
 
 ## User Guides
 
-* [AKS Engine](acsengine.md) - shows you how to build and use the AKS engine to generate custom Docker enabled container clusters
+* [AKS Engine](aksengine.md) - shows you how to build and use the AKS engine to generate custom Docker enabled container clusters
 * [Cluster Definition](clusterdefinition.md) - describes the components of the cluster definition file
 * [Kubernetes Walkthrough](kubernetes.md) - shows how to create a Kubernetes enabled Docker cluster on Azure
 * [Kubernetes Windows Walkthrough](kubernetes/windows.md) - shows how to create a hybrid Kubernetes Windows enabled Docker cluster on Azure.

docs/acsengine.md → docs/aksengine.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine
+# AKS-Engine
 
 The Azure Kubernetes Engine (`aks-engine`) generates ARM (Azure Resource Manager) templates for Kubernetes clusters on Microsoft Azure. The input to aks-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 Kubernetes Service.
 

docs/acsengine.zh-CN.md → docs/aksengine.zh-CN.md

@@ -143,8 +143,8 @@ ACS引擎使用json格式的[集群定义文件](clusterdefinition.md)作为输
 1. 首先需要准备一个[SSH 公钥私钥对](ssh.md#ssh-key-generation).
 2. 编辑[examples/kubernetes.json](../examples/kubernetes.json)将其需要的参数配置好.
 3. 运行`./bin/aks-engine generate examples/kubernetes.json`命令在_output/Kubernetes-UNIQUEID目录中生成对应的模板。（UNIQUEID是master节点的FQDN前缀的hash值）
-4. 按照README中指定的方式使用`azuredeploy.json`和`azuredeploy.parameters.json`部署容器集群 [deployment usage](../acsengine.md#deployment-usage).
+4. 按照README中指定的方式使用`azuredeploy.json`和`azuredeploy.parameters.json`部署容器集群 [deployment usage](../aksengine.md#deployment-usage).
 
 # 部署方法
 
-[部署方式请参考这里](../acsengine.md#deployment-usage).
+[部署方式请参考这里](../aksengine.md#deployment-usage).

docs/clusterdefinition.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Cluster Definition
+# AKS-Engine - Cluster Definition
 
 ## Cluster Defintions for apiVersion "vlabs"
 

docs/custom-vnet.md

@@ -10,7 +10,7 @@ By doing this, you will be able to control the properties of the virtual network
 You can run this walkthrough on OS X, Windows, or Linux.
 - You need an Azure subscription. If you don't have one, you can [sign up for an account](https://azure.microsoft.com/).
 - Install the [Azure CLI 2.0](/cli/azure/install-az-cli2).
-- Install the [AKS Engine](https://github.com/Azure/aks-engine/blob/master/docs/acsengine.md)
+- Install the [AKS Engine](https://github.com/Azure/aks-engine/blob/master/docs/aksengine.md)
 
 ## Create the virtual network
 *You need a virtual network before creating the new cluster. If you already have one, you can skip this step.*

docs/design/proposed-template-refactor.md

@@ -1,6 +1,6 @@
-# Acs-engine
+# AKS-Engine
 
-The Azure Kubernetes Engine (aks-engine) is a command line tool that generates ARM (Azure Resource Manager) templates in order for one to deploy container-based clusters (like Kubernetes , DCOS, Openshift, Docker swarm) on the Azure platform.
+AKS-Engine is a command line tool that generates ARM (Azure Resource Manager) templates in order for one to deploy container-based clusters (like Kubernetes , DCOS, Openshift, Docker swarm) on the Azure platform.
 
 This design document provides a brief and high-level overview of what aks-engine does internally to achieve deployment of containerized clusters. The scope of this document will be limited to the execution of aks-engine when creating Kubernetes clusters.
 
@@ -12,7 +12,7 @@ This design document provides a brief and high-level overview of what aks-engine
 
 ### Cluster api model
 
-Acs-engine accepts JSONs of cluster api models as inputs. These api models allow the user to specify cluster configuration items such as
+AKS-Engine accepts JSONs of cluster api models as inputs. These api models allow the user to specify cluster configuration items such as
 
 - Master and worker nodes configuration
 - Kubernetes version
@@ -227,11 +227,11 @@ The template generator then creates the following artifacts
 
 ### ARM Interface
 
-Acs-engine interfaces with Azure Resource Manager (ARM) through the Azure Go SDK. The Go SDK provides interfaces to perform functions like template deployment, validation.
+AKS-Engine interfaces with Azure Resource Manager (ARM) through the Azure Go SDK. The Go SDK provides interfaces to perform functions like template deployment, validation.
 
 ### Kubernetes Client API
 
-Acs-engine also performs kubernetes cluster management operations (kubectl) through the imported Kubernetes API libraries. The Client API calls are made during the scale and upgrade commands of aks-engine.
+AKS-Engine also performs kubernetes cluster management operations (kubectl) through the imported Kubernetes API libraries. The Client API calls are made during the scale and upgrade commands of aks-engine.
 
 
 Design challenges and proposals

docs/extensions.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Extensions
+# AKS-Engine - Extensions
 
 Extensions in aks-engine provide an easy way for aks-engine users to add pre-packaged functionality into their cluster.  For example, an extension could configure a monitoring solution on an AKS cluster.  The user would not need to know the details of how to install the monitoring solution.  Rather, the user would simply add the extension into the extensionProfiles section of the template.
 

docs/kubernetes.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Kubernetes
+# AKS-Engine - Kubernetes
 
 * Create a Kubernetes Cluster
   * [Linux](kubernetes/deploy.md) - Create your first Linux Kubernetes cluster

docs/kubernetes/aad.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Kubernetes AAD integration Walkthrough
+# AKS-Engine - Kubernetes AAD integration Walkthrough
 
 This is walkthrough is to help you get start with Azure Active Directory(AAD) integeration with an AKS Engine Kubernetes cluster.
 

docs/kubernetes/deploy.md

@@ -2,7 +2,7 @@
 
 ## Install Prerequisites
 
-All the commands in this guide require both the Azure CLI and `aks-engine`. Follow the [installation instructions to download aks-engine before continuing](../acsengine.md#install-aks-engine) or [compile from source](../acsengine.md#build-from-source).
+All the commands in this guide require both the Azure CLI and `aks-engine`. Follow the [installation instructions to download aks-engine before continuing](../aksengine.md#install-aks-engine) or [compile from source](../aksengine.md#build-from-source).
 
 For installation instructions see [the Azure CLI GitHub repository](https://github.com/Azure/azure-cli#installation) for the latest release.
 
@@ -135,7 +135,7 @@ aks-engine generate --set agentPoolProfiles[0].count=5,agentPoolProfiles[1].name
 
 ### Step 5: Submit your Templates to Azure Resource Manager (ARM)
 
-[Deploy the output azuredeploy.json and azuredeploy.parameters.json](../acsengine.md#deployment-usage)
+[Deploy the output azuredeploy.json and azuredeploy.parameters.json](../aksengine.md#deployment-usage)
 
 * To enable the optional network policy enforcement using calico, you have to set the parameter during this step according to this [guide](../kubernetes.md#optional-enable-network-policy-enforcement-using-calico)
 * To enable the optional network policy enforcement using cilium, you have to set the parameter during this step according to this [guide](../kubernetes.md#optional-enable-network-policy-enforcement-using-cilium)

docs/kubernetes/gpu.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Using GPUs with Kubernetes
+# AKS-Engine - Using GPUs with Kubernetes
 
 If you created a Kubernetes cluster with one or multiple agent pool(s) whose VM size is `Standard_NC*` or `Standard_NV*` you can schedule GPU workload on your cluster.
 The NVIDIA drivers are automatically installed on every GPU agent in your cluster, so you don't need to do that manually, unless you require a specific version of the drivers. Currently, the installed driver is version 396.26.

docs/kubernetes/scale.md

@@ -2,7 +2,7 @@
 
 ## Install Pre-requisites
 
-All the commands in this guide require both the Azure CLI and `aks-engine`. Follow the [installation instructions to download aks-engine before continuing](../acsengine.md#install-aks-engine) or [compile from source](../acsengine.md#build-from-source).
+All the commands in this guide require both the Azure CLI and `aks-engine`. Follow the [installation instructions to download aks-engine before continuing](../aksengine.md#install-aks-engine) or [compile from source](../aksengine.md#build-from-source).
 
 For installation instructions see [the Azure CLI GitHub repository](https://github.com/Azure/azure-cli#installation) for the latest release.
 

docs/serviceprincipal.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine
+# AKS-Engine
 
 ## Service Principals
 

docs/ssh.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - SSH
+# AKS-Engine - SSH
 
 # SSH Key Management
 

examples/README.md

@@ -1,12 +1,12 @@
-# Microsoft Azure Kubernetes Engine - Builds Kubernetes Clusters
+# AKS-Engine - Builds Kubernetes Clusters
 
 ## Overview
 
 These cluster definition examples demonstrate how to create a customized Docker Enabled Cluster on Microsoft Azure.
 
 ## Walkthroughs
 
-* [AKS Engine](../docs/acsengine.md) - shows you how to use the AKS Engine to generate custom Docker enabled container clusters
+* [AKS Engine](../docs/aksengine.md) - shows you how to use the AKS Engine to generate custom Docker enabled container clusters
 * [Cluster Definition](../docs/clusterdefinition.md) - describes the components of the cluster definition file
 * [DC/OS Walkthrough](../docs/dcos.md) - shows how to create a DC/OS enabled Docker cluster on Azure
 * [Kubernetes Walkthrough](../docs/kubernetes.md) - shows how to create a Kubernetes enabled Docker cluster on Azure

examples/customfiles/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Provisioning of master node custom files
+# AKS-Engine - Provisioning of master node custom files
 
 ## Overview
 

examples/disks-managed/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Managed Disks
+# AKS-Engine - Managed Disks
 
 ## Overview
 

examples/disks-storageaccount/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Attached Disks
+# AKS-Engine - Attached Disks
 
 ## Overview
 

examples/k8s-upgrade/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Kubernetes Upgrade
+# AKS-Engine - Kubernetes Upgrade
 
 ## Overview
 

examples/keyvault-params/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Key vault referencing for k8s parameters
+# AKS-Engine - Key vault referencing for k8s parameters
 
 ## Overview
 

examples/keyvaultcerts/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Key vault certificate deployment
+# AKS-Engine - Key vault certificate deployment
 
 ## Overview
 

examples/kubernetes-config/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Kubernetes Features
+# AKS-Engine - Kubernetes Features
 
 ## Overview
 

examples/largeclusters/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Large Clusters
+# AKS-Engine - Large Clusters
 
 ## Overview
 

examples/multiple-nodepools/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Multiple Node Pools
+# AKS-Engine - Multiple Node Pools
 
 aks-engine supports creating a Kubernetes cluster with more than one node pool. These pools can have different configurations, such as VM size or storage profile.
 

examples/networkplugin/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Network Plugin
+# AKS-Engine - Network Plugin
 
 There are 2 different Network Plugin options :
 

examples/networkpolicy/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Network Policy
+# AKS-Engine - Network Policy
 
 There are 2 different Network Policy options :
 

examples/vnet/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine - Custom VNET
+# AKS-Engine - Custom VNET
 
 ## Overview
 

examples/windows/README.md

@@ -1,4 +1,4 @@
-# Microsoft Azure Kubernetes Engine
+# AKS-Engine
 
 ## Overview
 

releases/Dockerfile.linux

@@ -12,7 +12,7 @@ LABEL maintainer="Microsoft" \
       org.label-schema.license="MIT" \
       org.label-schema.description="The Azure Kubernetes Engine (aks-engine) generates ARM (Azure Resource Manager) templates for Kubernetes clusters on Microsoft Azure with your choice of DCOS, Kubernetes, or Swarm orchestrators." \
       org.label-schema.url="https://github.com/Azure/aks-engine" \
-      org.label-schema.usage="https://github.com/Azure/aks-engine/blob/master/docs/acsengine.md" \
+      org.label-schema.usage="https://github.com/Azure/aks-engine/blob/master/docs/aksengine.md" \
       org.label-schema.build-date=$BUILD_DATE \
       org.label-schema.vcs-url="https://github.com/Azure/aks-engine.git" \
       org.label-schema.docker.cmd="docker run -v \${PWD}:/aks-engine/workspace -it --rm microsoft/aks-engine:$AKSENGINE_VERSION"

releases/README.Dockerfile.md

@@ -25,7 +25,7 @@ $ docker image inspect microsoft/aks-engine:0.16.0 --format "{{json .Config.Labe
   "org.label-schema.name": "Azure Kubernetes Engine (aks-engine)",
   "org.label-schema.schema-version": "1.0",
   "org.label-schema.url": "https://github.com/Azure/aks-engine",
-  "org.label-schema.usage": "https://github.com/Azure/aks-engine/blob/master/docs/acsengine.md",
+  "org.label-schema.usage": "https://github.com/Azure/aks-engine/blob/master/docs/aksengine.md",
   "org.label-schema.vcs-url": "https://github.com/Azure/aks-engine.git",
   "org.label-schema.vendor": "Microsoft",
   "org.label-schema.version": "0.16.0"
@@ -44,7 +44,7 @@ PS> docker image inspect microsoft/aks-engine:0.16.0 --format "{{json .Config.La
     "org.label-schema.name":  "Azure Kubernetes Engine (aks-engine)",
     "org.label-schema.schema-version":  "1.0",
     "org.label-schema.url":  "https://github.com/Azure/aks-engine",
-    "org.label-schema.usage":  "https://github.com/Azure/aks-engine/blob/master/docs/acsengine.md",
+    "org.label-schema.usage":  "https://github.com/Azure/aks-engine/blob/master/docs/aksengine.md",
     "org.label-schema.vcs-url":  "https://github.com/Azure/aks-engine.git",
     "org.label-schema.vendor":  "Microsoft",
     "org.label-schema.version":  "0.16.0"