Skip to content
This repository was archived by the owner on Oct 24, 2023. It is now read-only.

Commit f895db7

Browse files
committed
Quick documentation rationalization (#152)
1 parent 2aa7845 commit f895db7

33 files changed

+67
-44
lines changed

README.md

+27-4
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,36 @@
66

77
## Overview
88

9-
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.
9+
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.
1010

11-
## Under Construction
11+
More info, including a thorough walkthrough is [here](docs/aksengine.md).
1212

13-
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!
13+
Please see the [FAQ](/docs/faq.md) for answers about AKS-Engine and its progenitor ACS-Engine.
1414

15-
Please see the [FAQ](/docs/faq.md) for answers about AKS-Engine and this project transition.
15+
## User guides
16+
17+
[This guide](docs/kubernetes.md) walks you through your first cluster deployment.
18+
19+
These guides cover more advanced features to try out after you have built your first cluster:
20+
21+
* [Cluster Definition](docs/clusterdefinition.md) - describes the components of the cluster definition file
22+
* [Custom VNET](examples/vnet) - shows how to use a custom VNET
23+
* [Attached Disks](examples/disks-storageaccount) - shows how to attach up to 4 disks per node
24+
* [Managed Disks](examples/disks-managed) - shows how to use managed disks
25+
* [Large Clusters](examples/largeclusters) - shows how to create cluster sizes of up to 1200 nodes
26+
27+
## Contributing
28+
29+
Follow the [developers guide](docs/developers.md) to set up your environment.
30+
31+
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.
32+
33+
Please follow these instructions before submitting a PR:
34+
35+
1. Execute `make test` to run unit tests.
36+
2. Manually test deployments if you are making modifications to the templates.
37+
* 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.
38+
3. Make sure that your changes are properly documented and include relevant unit tests.
1639

1740
## Code of conduct
1841

README_zh-CN.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
## 演示链接
1818

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

docs/README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
# Microsoft Azure Kubernetes Engine - Builds Kubernetes Clusters
1+
# AKS-Engine - Builds Kubernetes Clusters
22

33
## Overview
44

55
This cluster definition examples demonstrate how to create a customized Docker Enabled Cluster on Microsoft Azure.
66

77
## User Guides
88

9-
* [AKS Engine](acsengine.md) - shows you how to build and use the AKS engine to generate custom Docker enabled container clusters
9+
* [AKS Engine](aksengine.md) - shows you how to build and use the AKS engine to generate custom Docker enabled container clusters
1010
* [Cluster Definition](clusterdefinition.md) - describes the components of the cluster definition file
1111
* [Kubernetes Walkthrough](kubernetes.md) - shows how to create a Kubernetes enabled Docker cluster on Azure
1212
* [Kubernetes Windows Walkthrough](kubernetes/windows.md) - shows how to create a hybrid Kubernetes Windows enabled Docker cluster on Azure.
File renamed without changes.

docs/acsengine.md docs/aksengine.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine
1+
# AKS-Engine
22

33
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.
44

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

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

148148
# 部署方法
149149

150-
[部署方式请参考这里](../acsengine.md#deployment-usage).
150+
[部署方式请参考这里](../aksengine.md#deployment-usage).

docs/clusterdefinition.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Cluster Definition
1+
# AKS-Engine - Cluster Definition
22

33
## Cluster Defintions for apiVersion "vlabs"
44

docs/custom-vnet.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ By doing this, you will be able to control the properties of the virtual network
1010
You can run this walkthrough on OS X, Windows, or Linux.
1111
- You need an Azure subscription. If you don't have one, you can [sign up for an account](https://azure.microsoft.com/).
1212
- Install the [Azure CLI 2.0](/cli/azure/install-az-cli2).
13-
- Install the [AKS Engine](https://github.com/Azure/aks-engine/blob/master/docs/acsengine.md)
13+
- Install the [AKS Engine](https://github.com/Azure/aks-engine/blob/master/docs/aksengine.md)
1414

1515
## Create the virtual network
1616
*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

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Acs-engine
1+
# AKS-Engine
22

3-
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.
3+
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.
44

55
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.
66

@@ -12,7 +12,7 @@ This design document provides a brief and high-level overview of what aks-engine
1212

1313
### Cluster api model
1414

15-
Acs-engine accepts JSONs of cluster api models as inputs. These api models allow the user to specify cluster configuration items such as
15+
AKS-Engine accepts JSONs of cluster api models as inputs. These api models allow the user to specify cluster configuration items such as
1616

1717
- Master and worker nodes configuration
1818
- Kubernetes version
@@ -227,11 +227,11 @@ The template generator then creates the following artifacts
227227

228228
### ARM Interface
229229

230-
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.
230+
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.
231231

232232
### Kubernetes Client API
233233

234-
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.
234+
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.
235235

236236

237237
Design challenges and proposals

docs/extensions.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Extensions
1+
# AKS-Engine - Extensions
22

33
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.
44

docs/kubernetes.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Kubernetes
1+
# AKS-Engine - Kubernetes
22

33
* Create a Kubernetes Cluster
44
* [Linux](kubernetes/deploy.md) - Create your first Linux Kubernetes cluster

docs/kubernetes/aad.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Kubernetes AAD integration Walkthrough
1+
# AKS-Engine - Kubernetes AAD integration Walkthrough
22

33
This is walkthrough is to help you get start with Azure Active Directory(AAD) integeration with an AKS Engine Kubernetes cluster.
44

docs/kubernetes/deploy.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Install Prerequisites
44

5-
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).
5+
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).
66

77
For installation instructions see [the Azure CLI GitHub repository](https://github.com/Azure/azure-cli#installation) for the latest release.
88

@@ -135,7 +135,7 @@ aks-engine generate --set agentPoolProfiles[0].count=5,agentPoolProfiles[1].name
135135

136136
### Step 5: Submit your Templates to Azure Resource Manager (ARM)
137137

138-
[Deploy the output azuredeploy.json and azuredeploy.parameters.json](../acsengine.md#deployment-usage)
138+
[Deploy the output azuredeploy.json and azuredeploy.parameters.json](../aksengine.md#deployment-usage)
139139

140140
* 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)
141141
* 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-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Using GPUs with Kubernetes
1+
# AKS-Engine - Using GPUs with Kubernetes
22

33
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.
44
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

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Install Pre-requisites
44

5-
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).
5+
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).
66

77
For installation instructions see [the Azure CLI GitHub repository](https://github.com/Azure/azure-cli#installation) for the latest release.
88

docs/serviceprincipal.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine
1+
# AKS-Engine
22

33
## Service Principals
44

docs/ssh.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - SSH
1+
# AKS-Engine - SSH
22

33
# SSH Key Management
44

examples/README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
# Microsoft Azure Kubernetes Engine - Builds Kubernetes Clusters
1+
# AKS-Engine - Builds Kubernetes Clusters
22

33
## Overview
44

55
These cluster definition examples demonstrate how to create a customized Docker Enabled Cluster on Microsoft Azure.
66

77
## Walkthroughs
88

9-
* [AKS Engine](../docs/acsengine.md) - shows you how to use the AKS Engine to generate custom Docker enabled container clusters
9+
* [AKS Engine](../docs/aksengine.md) - shows you how to use the AKS Engine to generate custom Docker enabled container clusters
1010
* [Cluster Definition](../docs/clusterdefinition.md) - describes the components of the cluster definition file
1111
* [DC/OS Walkthrough](../docs/dcos.md) - shows how to create a DC/OS enabled Docker cluster on Azure
1212
* [Kubernetes Walkthrough](../docs/kubernetes.md) - shows how to create a Kubernetes enabled Docker cluster on Azure

examples/customfiles/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Provisioning of master node custom files
1+
# AKS-Engine - Provisioning of master node custom files
22

33
## Overview
44

examples/disks-managed/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Managed Disks
1+
# AKS-Engine - Managed Disks
22

33
## Overview
44

examples/disks-storageaccount/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Attached Disks
1+
# AKS-Engine - Attached Disks
22

33
## Overview
44

examples/k8s-upgrade/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Kubernetes Upgrade
1+
# AKS-Engine - Kubernetes Upgrade
22

33
## Overview
44

examples/keyvault-params/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Key vault referencing for k8s parameters
1+
# AKS-Engine - Key vault referencing for k8s parameters
22

33
## Overview
44

examples/keyvaultcerts/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Key vault certificate deployment
1+
# AKS-Engine - Key vault certificate deployment
22

33
## Overview
44

examples/kubernetes-config/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Kubernetes Features
1+
# AKS-Engine - Kubernetes Features
22

33
## Overview
44

examples/largeclusters/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Large Clusters
1+
# AKS-Engine - Large Clusters
22

33
## Overview
44

examples/multiple-nodepools/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Multiple Node Pools
1+
# AKS-Engine - Multiple Node Pools
22

33
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.
44

examples/networkplugin/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Network Plugin
1+
# AKS-Engine - Network Plugin
22

33
There are 2 different Network Plugin options :
44

examples/networkpolicy/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Network Policy
1+
# AKS-Engine - Network Policy
22

33
There are 2 different Network Policy options :
44

examples/vnet/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine - Custom VNET
1+
# AKS-Engine - Custom VNET
22

33
## Overview
44

examples/windows/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Microsoft Azure Kubernetes Engine
1+
# AKS-Engine
22

33
## Overview
44

releases/Dockerfile.linux

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ LABEL maintainer="Microsoft" \
1212
org.label-schema.license="MIT" \
1313
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." \
1414
org.label-schema.url="https://github.com/Azure/aks-engine" \
15-
org.label-schema.usage="https://github.com/Azure/aks-engine/blob/master/docs/acsengine.md" \
15+
org.label-schema.usage="https://github.com/Azure/aks-engine/blob/master/docs/aksengine.md" \
1616
org.label-schema.build-date=$BUILD_DATE \
1717
org.label-schema.vcs-url="https://github.com/Azure/aks-engine.git" \
1818
org.label-schema.docker.cmd="docker run -v \${PWD}:/aks-engine/workspace -it --rm microsoft/aks-engine:$AKSENGINE_VERSION"

releases/README.Dockerfile.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ $ docker image inspect microsoft/aks-engine:0.16.0 --format "{{json .Config.Labe
2525
"org.label-schema.name": "Azure Kubernetes Engine (aks-engine)",
2626
"org.label-schema.schema-version": "1.0",
2727
"org.label-schema.url": "https://github.com/Azure/aks-engine",
28-
"org.label-schema.usage": "https://github.com/Azure/aks-engine/blob/master/docs/acsengine.md",
28+
"org.label-schema.usage": "https://github.com/Azure/aks-engine/blob/master/docs/aksengine.md",
2929
"org.label-schema.vcs-url": "https://github.com/Azure/aks-engine.git",
3030
"org.label-schema.vendor": "Microsoft",
3131
"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
4444
"org.label-schema.name": "Azure Kubernetes Engine (aks-engine)",
4545
"org.label-schema.schema-version": "1.0",
4646
"org.label-schema.url": "https://github.com/Azure/aks-engine",
47-
"org.label-schema.usage": "https://github.com/Azure/aks-engine/blob/master/docs/acsengine.md",
47+
"org.label-schema.usage": "https://github.com/Azure/aks-engine/blob/master/docs/aksengine.md",
4848
"org.label-schema.vcs-url": "https://github.com/Azure/aks-engine.git",
4949
"org.label-schema.vendor": "Microsoft",
5050
"org.label-schema.version": "0.16.0"

0 commit comments

Comments
 (0)