diff --git a/README.md b/README.md index f278d95ac..09af62665 100644 --- a/README.md +++ b/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 diff --git a/README_zh-CN.md b/README_zh-CN.md index d4eb2a453..2248a9b38 100644 --- a/README_zh-CN.md +++ b/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集群 diff --git a/docs/README.md b/docs/README.md index bf9d83472..22a419c2c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Builds Kubernetes Clusters +# AKS-Engine - Builds Kubernetes Clusters ## Overview @@ -6,7 +6,7 @@ This cluster definition examples demonstrate how to create a customized Docker E ## 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. diff --git a/docs/acsengine-code-delivery.md b/docs/aksengine-code-delivery.md similarity index 100% rename from docs/acsengine-code-delivery.md rename to docs/aksengine-code-delivery.md diff --git a/docs/acsengine.md b/docs/aksengine.md similarity index 99% rename from docs/acsengine.md rename to docs/aksengine.md index d714dda01..a6e41eaf0 100644 --- a/docs/acsengine.md +++ b/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. diff --git a/docs/acsengine.zh-CN.md b/docs/aksengine.zh-CN.md similarity index 96% rename from docs/acsengine.zh-CN.md rename to docs/aksengine.zh-CN.md index b710c95d1..9cc778f30 100644 --- a/docs/acsengine.zh-CN.md +++ b/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). diff --git a/docs/clusterdefinition.md b/docs/clusterdefinition.md index 6695796e1..31c50816f 100644 --- a/docs/clusterdefinition.md +++ b/docs/clusterdefinition.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Cluster Definition +# AKS-Engine - Cluster Definition ## Cluster Defintions for apiVersion "vlabs" diff --git a/docs/custom-vnet.md b/docs/custom-vnet.md index ef736da38..19a8c086c 100644 --- a/docs/custom-vnet.md +++ b/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.* diff --git a/docs/design/proposed-template-refactor.md b/docs/design/proposed-template-refactor.md index 7d2b22934..f4820bfdf 100644 --- a/docs/design/proposed-template-refactor.md +++ b/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 diff --git a/docs/extensions.md b/docs/extensions.md index a8865291f..c30bc8622 100644 --- a/docs/extensions.md +++ b/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. diff --git a/docs/kubernetes.md b/docs/kubernetes.md index 08ca3c929..50d5d24f4 100644 --- a/docs/kubernetes.md +++ b/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 diff --git a/docs/kubernetes/aad.md b/docs/kubernetes/aad.md index f42269eed..fd47a9221 100644 --- a/docs/kubernetes/aad.md +++ b/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. diff --git a/docs/kubernetes/deploy.md b/docs/kubernetes/deploy.md index 72ce7f659..72630d6f6 100644 --- a/docs/kubernetes/deploy.md +++ b/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) diff --git a/docs/kubernetes/gpu.md b/docs/kubernetes/gpu.md index 66a2fcb07..aa94fafa7 100644 --- a/docs/kubernetes/gpu.md +++ b/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. diff --git a/docs/kubernetes/scale.md b/docs/kubernetes/scale.md index c3be64d99..3f56a65b1 100644 --- a/docs/kubernetes/scale.md +++ b/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. diff --git a/docs/serviceprincipal.md b/docs/serviceprincipal.md index 83e4621ed..68ac0cbe6 100644 --- a/docs/serviceprincipal.md +++ b/docs/serviceprincipal.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine +# AKS-Engine ## Service Principals diff --git a/docs/ssh.md b/docs/ssh.md index ddb4fbb7b..8d6d44d0f 100644 --- a/docs/ssh.md +++ b/docs/ssh.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - SSH +# AKS-Engine - SSH # SSH Key Management diff --git a/examples/README.md b/examples/README.md index 62dae8a12..01f3c65d1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Builds Kubernetes Clusters +# AKS-Engine - Builds Kubernetes Clusters ## Overview @@ -6,7 +6,7 @@ These cluster definition examples demonstrate how to create a customized Docker ## 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 diff --git a/examples/customfiles/README.md b/examples/customfiles/README.md index 4d26ff3bc..b25a9a605 100644 --- a/examples/customfiles/README.md +++ b/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 diff --git a/examples/disks-managed/README.md b/examples/disks-managed/README.md index 6d837e0fc..91ee3f102 100644 --- a/examples/disks-managed/README.md +++ b/examples/disks-managed/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Managed Disks +# AKS-Engine - Managed Disks ## Overview diff --git a/examples/disks-storageaccount/README.md b/examples/disks-storageaccount/README.md index 7ee8f3ab6..58b818fc3 100644 --- a/examples/disks-storageaccount/README.md +++ b/examples/disks-storageaccount/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Attached Disks +# AKS-Engine - Attached Disks ## Overview diff --git a/examples/k8s-upgrade/README.md b/examples/k8s-upgrade/README.md index f1da75799..1096c416f 100644 --- a/examples/k8s-upgrade/README.md +++ b/examples/k8s-upgrade/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Kubernetes Upgrade +# AKS-Engine - Kubernetes Upgrade ## Overview diff --git a/examples/keyvault-params/README.md b/examples/keyvault-params/README.md index 4dbc12212..21bd963d8 100644 --- a/examples/keyvault-params/README.md +++ b/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 diff --git a/examples/keyvaultcerts/README.md b/examples/keyvaultcerts/README.md index 40cb69258..582533ab3 100644 --- a/examples/keyvaultcerts/README.md +++ b/examples/keyvaultcerts/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Key vault certificate deployment +# AKS-Engine - Key vault certificate deployment ## Overview diff --git a/examples/kubernetes-config/README.md b/examples/kubernetes-config/README.md index 14bada813..fcc941e32 100644 --- a/examples/kubernetes-config/README.md +++ b/examples/kubernetes-config/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Kubernetes Features +# AKS-Engine - Kubernetes Features ## Overview diff --git a/examples/largeclusters/README.md b/examples/largeclusters/README.md index 9cc950653..9ca42a661 100644 --- a/examples/largeclusters/README.md +++ b/examples/largeclusters/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Large Clusters +# AKS-Engine - Large Clusters ## Overview diff --git a/examples/multiple-nodepools/README.md b/examples/multiple-nodepools/README.md index c7049e87a..81b2ea240 100644 --- a/examples/multiple-nodepools/README.md +++ b/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. diff --git a/examples/networkplugin/README.md b/examples/networkplugin/README.md index fa267c69d..a28171a81 100644 --- a/examples/networkplugin/README.md +++ b/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 : diff --git a/examples/networkpolicy/README.md b/examples/networkpolicy/README.md index 19bb0dd3a..566fd3895 100644 --- a/examples/networkpolicy/README.md +++ b/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 : diff --git a/examples/vnet/README.md b/examples/vnet/README.md index b9ead0e21..dbd3afcb3 100644 --- a/examples/vnet/README.md +++ b/examples/vnet/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine - Custom VNET +# AKS-Engine - Custom VNET ## Overview diff --git a/examples/windows/README.md b/examples/windows/README.md index e9ddb14f4..28df5daaf 100644 --- a/examples/windows/README.md +++ b/examples/windows/README.md @@ -1,4 +1,4 @@ -# Microsoft Azure Kubernetes Engine +# AKS-Engine ## Overview diff --git a/releases/Dockerfile.linux b/releases/Dockerfile.linux index fbb95da73..429cdb670 100644 --- a/releases/Dockerfile.linux +++ b/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" diff --git a/releases/README.Dockerfile.md b/releases/README.Dockerfile.md index d07640c85..c96e2a820 100644 --- a/releases/README.Dockerfile.md +++ b/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"