docs: mkdocs based docs (Azure#373)

o-otte · Jul 16, 2019 · 9bed6a4 · 9bed6a4
1 parent 9e3405e
commit 9bed6a4
Show file tree

Hide file tree

Showing 19 changed files with 447 additions and 278 deletions.
diff --git a/_config.yml b/_config.yml
diff --git a/docs/.index b/docs/.index
@@ -0,0 +1,11 @@
+title: Page Title
+collapse: true
+arrange:
+    - index.md
+    - setup
+    - tutorial.md
+    - annotations.md
+    - features
+    - how-tos
+    - faq.md
+    - troubleshooting.md
diff --git a/docs/annotations.md b/docs/annotations.md
@@ -1,7 +1,11 @@
-## Introduction
+# Annotations
+
+## Introductions
+
 Kubernetes Ingress specification allows for annotations. We use annotations to expose Application Gateway specific features that can't be exposed using the ingress specification. It is important to note that annotations defined on an ingress resource are applied to all HTTP setting, backend pools and listeners defined within a given ingress resource.
 
-### List of supported annotations
+## List of supported annotations
+
 | Annotation Key | Value Type | Default Value |
 | -- | -- | -- |
 | [appgw.ingress.kubernetes.io/backend-path-prefix](#backend-path-prefix) | `string` | `nil` |
@@ -12,14 +16,17 @@ Kubernetes Ingress specification allows for annotations. We use annotations to e
 | [appgw.ingress.kubernetes.io/request-timeout](#request-timeout) | `int32` (seconds) | `30` |
 
 ## Backend Path Prefix
+
 This annotation allows the backend path specified in an ingress resource to be re-written with prefix specified in this annotation. This allows users to expose services whose endpoints are different than endpoint names used to expose a service in an ingress resource.
 
 ### Usage
+
 ```yaml
 appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>
 ```
 
 ### Example
+
 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
@@ -43,18 +50,21 @@ In the example above we have defined an ingress resource named `go-server-ingres
 ***NOTE:*** In the above example we have only one rule defined. However, the annotations is applicable to the entire ingress resource so if a user had defined multiple rules the backend path prefix would be setup for each of the paths sepcified. Thus, if a user wants different rules with different path prefixes (even for the same service) they would need to define different ingress resources.
 
 ## SSL Redirect
+
 Application Gateway [can be configured](https://docs.microsoft.com/en-us/azure/application-gateway/application-gateway-redirect-overview)
 to automatically redirect HTTP URLs to their HTTPS counterparts. When this
 annotation is present and TLS is properly configured, Kubernetes Ingress
 controller will create a [routing rule with a redirection configuration](https://docs.microsoft.com/en-us/azure/application-gateway/redirect-http-to-https-portal#add-a-routing-rule-with-a-redirection-configuration)
 and apply the changes to your App Gateway. The redirect created will be HTTP `301 Moved Permanently`.
 
 ### Usage
+
 ```yaml
 appgw.ingress.kubernetes.io/ssl-redirect: "true"
 ```
 
 ### Example
+
 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
@@ -78,17 +88,20 @@ spec:
           servicePort: 80
 ```
 
-# Connection Draining
+## Connection Draining
+
 `connection-draining`: This annotation allows to specify whether to enable connection draining.
 `connection-draining-timeout`: This annotation allows to specify a timeout after which Application Gateway will terminate the requests to the draining backend endpoint.
 
 ### Usage
+
 ```yaml
 appgw.ingress.kubernetes.io/connection-draining: "true"
 appgw.ingress.kubernetes.io/connection-draining-timeout: 60
 ```
 
 ### Example
+
 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
@@ -109,15 +122,18 @@ spec:
           servicePort: 80
 ```
 
-# Cookie Based Affinity
+## Cookie Based Affinity
+
 This annotation allows to specify whether to enable cookie based affinity.
 
 ### Usage
+
 ```yaml
 appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
 ```
 
 ### Example
+
 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
@@ -137,15 +153,18 @@ spec:
           servicePort: 80
 ```
 
-# Request Timeout
+## Request Timeout
+
 This annotation allows to specify the request timeout in seconds after which Application Gateway will fail the request if response is not received.
 
 ### Usage
+
 ```yaml
 appgw.ingress.kubernetes.io/request-timeout: 20
 ```
 
 ### Example
+
 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
@@ -163,4 +182,4 @@ spec:
         backend:
           serviceName: go-server-service
           servicePort: 80
-```
+```
diff --git a/docs/css/extra.css b/docs/css/extra.css
@@ -0,0 +1,35 @@
+div.col-md-9 h1:first-of-type {
+    text-align: center;
+    font-size: 60px;
+    font-weight: 300;
+}
+
+div.col-md-9>p:first-of-type {
+    text-align: center;
+}
+
+div.col-md-9 p.admonition-title:first-of-type {
+    text-align: left;
+}
+
+div.col-md-9 h1:first-of-type .headerlink {
+    display: none;
+}
+
+code.no-highlight {
+    color: black;
+}
+
+/* Definition List styles */
+
+dd {
+    padding-left: 20px;
+}
+
+li.toctree-l2:first-child {
+    display: none;
+}
+
+li.toctree-l3:first-child {
+    display: none;
+}
diff --git a/docs/build.md → docs/developers/build.md b/docs/build.md → docs/developers/build.md
@@ -1,4 +1,6 @@
-## Building
+# Building the controller
+
+## CMake options
 
 This is a CMake-based project. Build targets include:
 
@@ -16,19 +18,22 @@ To run the CMake targets:
 3. `cmake --build .` to build the default target,
     or `cmake --build . --target <target_name>` to specify a target to run from above
 
-
 ## Running it locally
+
 This section outlines the environment variables and files necessary to successfully compile and run the Go binary, then connect it to an [Azure Kubernetes Service](https://docs.microsoft.com/en-us/azure/aks/intro-kubernetes).
 
 ### Obtain Azure Credentials
 
 In order to run the Go binary locally and control a remote AKS server, you need Azure credentials. These will be stored in a JSON file in your home directory.
 
 Follow [these instructions](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/containerinstance?view=azure-dotnet#authentication) to create the `$HOME/.azure/azureAuth.json` file. The file is generated via:
+
 ```bash
 az ad sp create-for-rbac --subscription <your-azure-subscription-id> --sdk-auth > $HOME/.azure/azureAuth.json
 ```
+
 The file will contain a JSON blob with the following shape:
+
 ```json
 {
   "clientId": "...",
@@ -45,8 +50,10 @@ The file will contain a JSON blob with the following shape:
 ```
 
 ### Startup Script
+
 In the `scripts` directory you will find `start.sh`. This script builds and runs the ingress controller on your local machine and connects to a remote AKS cluster. A `.env` file in the root of the repository is required.
 
 Steps to run ingress controller:
- 1. Configure: `cp .env.example .env` and modify the environment variables in `.env` to match your config
- 2. Run: `./scripts/start.sh`
+
+1. Configure: `cp .env.example .env` and modify the environment variables in `.env` to match your config
+1. Run: `./scripts/start.sh`
diff --git a/docs/developers/contribute.md b/docs/developers/contribute.md
@@ -0,0 +1,14 @@
+# Contribution Guidelines
+
+This is a Golang project. You can find the build instructions of the project in the [Developer Guide](build.md).
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,14 +1,15 @@
 # Frequrently Asked Questions: [WIP]
 
-* [What is an Ingress Controller?](#what-is-an-ingress-controller?)
-* [Can single ingress controller instance manage multiple Application Gateway?](#can-single-ingress-controller-instance-manage-multiple-application-gateway?)
+* [What is an Ingress Controller](#what-is-an-ingress-controller)
+* [Can single ingress controller instance manage multiple Application Gateway](#can-single-ingress-controller-instance-manage-multiple-application-gateway)
+
+## What is an Ingress Controller
 
-## What is an Ingress Controller?
 Kubernetes allows creation of `deployment` and `service` resource to expose a group of pods internally in the cluster. To expose the same service externally, an [`Ingress`](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource is defined which provides load balancing, SSL termination and name-based virtual hosting.
 To satify this `Ingress` resource, an Ingress Controller is required which listens for any changes to `Ingress` resources and configures the load balancer policies.
 
 The Application Gateway Ingress Controller allows [Azure Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) to be used as the ingress for an [Azure Kubernetes Service](https://azure.microsoft.com/en-us/services/kubernetes-service/) aka AKS cluster.
 
+## Can single ingress controller instance manage multiple Application Gateway
 
-## Can single ingress controller instance manage multiple Application Gateway?
 Currently, One instance of Ingress Controller can only be associated to one Application Gateway.
diff --git a/docs/features.md b/docs/features.md
diff --git a/docs/features/multiple-namespaces.md b/docs/features/multiple-namespaces.md
@@ -116,5 +116,5 @@ to the `production` backend pool.
 By default AGIC will configure App Gateway based on annotated Ingress within
 any namespace. Should you want to limit this behaviour you have the following
 options:
-  - limit the namespaces, by explicitly defining namespaces AGIC should observe via the `watchNamespace` YAML key in [helm-config.yaml](examples/helm-config.yaml)
+  - limit the namespaces, by explicitly defining namespaces AGIC should observe via the `watchNamespace` YAML key in [helm-config.yaml](../examples/sample-helm-config.yaml)
   - use [Role/RoleBinding](https://docs.microsoft.com/en-us/azure/aks/azure-ad-rbac) to limit AGIC to specific namespaces
diff --git a/docs/features/private-ip.md b/docs/features/private-ip.md
@@ -24,6 +24,7 @@ armAuth:
 This will make the ingress controller filter the ipconfigurations for a Private IP when configuring the frontend listeners on the Application Gateway.
 Controller will panic and crash if `usePrivateIP: true` and no Private IP is assigned.
 
-Notes:
-1) Application Gateway v2 SKU manadates a Public IP. For meeting compliance requirement where the Application Gateway should be completely private, Attach a [`Network Security Group`](https://docs.microsoft.com/en-us/azure/virtual-network/security-overview) to the Application Gateway's subnet to restrict traffic.
-2) To expose the Ingress both on public and private, current recommedation is to deploy two Application Gateways with respective Ingress Controllers, one with Public IP and one with Private IP.
+**Notes:**
+
+1. Application Gateway v2 SKU manadates a Public IP. For meeting compliance requirement where the Application Gateway should be completely private, Attach a [`Network Security Group`](https://docs.microsoft.com/en-us/azure/virtual-network/security-overview) to the Application Gateway's subnet to restrict traffic.
+1. To expose the Ingress both on public and private, current recommedation is to deploy two Application Gateways with respective Ingress Controllers, one with Public IP and one with Private IP.
diff --git a/docs/features/probes.md b/docs/features/probes.md
@@ -33,10 +33,11 @@ Kubernetes API Reference:
 * [Container Probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes)
 * [HttpGet Action](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#httpgetaction-v1-core)
 
-*Note:*
-1) `readinessProbe` and `livenessProbe` are supported when configured with `httpGet`.
-2) Probing on a port other than the one exposed on the pod is currently not supported.
-3) `HttpHeaders`, `InitialDelaySeconds`, `SuccessThreshold` are not supported.
+**Note:**
+
+1. `readinessProbe` and `livenessProbe` are supported when configured with `httpGet`.
+1. Probing on a port other than the one exposed on the pod is currently not supported.
+1. `HttpHeaders`, `InitialDelaySeconds`, `SuccessThreshold` are not supported.
 
 ###  Without `readinessProbe` or `livenessProbe`
 If the above probes are not provided, then Ingress Controller make an assumption that the service is reachable on `Path` specified for `backend-path-prefix` annotation or the `path` specified in the `ingress` definition for the service.

diff --git a/docs/how-to.md b/docs/how-to.md
diff --git a/docs/how-tos/helm-upgrade.md b/docs/how-tos/helm-upgrade.md
@@ -6,32 +6,35 @@ using [a Helm repository hosted on GitHub](https://azure.github.io/application-g
 Before we begin the upgrade procedure, ensure that you have added the required repository:
 
 - View your currently added Helm repositories with:
+
     ```bash
     helm repo list
     ```
 
 - Add the AGIC repo with:
+
     ```bash
     helm repo add \
         application-gateway-kubernetes-ingress \
         https://azure.github.io/application-gateway-kubernetes-ingress/helm/
     ```
 
+## Upgrade
 
-### Upgrade
-1) Refresh the AGIC Helm repository to get the latest release:
+1. Refresh the AGIC Helm repository to get the latest release:
 
     ```bash
     helm repo update
     ```
 
-2) View available versions of the `application-gateway-kubernetes-ingress` chart:
+1. View available versions of the `application-gateway-kubernetes-ingress` chart:
 
-    ```bash
+    ``` bash
     helm search -l application-gateway-kubernetes-ingress
     ```
 
     Sample response:
+
     ```bash
     NAME                                                    CHART VERSION   APP VERSION     DESCRIPTION
     application-gateway-kubernetes-ingress/ingress-azure    0.7.0-rc1       0.7.0-rc1       Use Azure Application Gateway as the ingress for an Azure...
@@ -40,22 +43,23 @@ Before we begin the upgrade procedure, ensure that you have added the required r
 
     Latest available version from the list above is: `0.7.0-rc1`
 
-2) View the Helm charts currently installed:
+1. View the Helm charts currently installed:
 
     ```bash
     helm list
     ```
 
     Sample response:
-    ```
+
+    ```bash
     NAME            REVISION        UPDATED                         STATUS  CHART                   APP VERSION     NAMESPACE
     odd-billygoat   22              Fri Jun 21 15:56:06 2019        FAILED  ingress-azure-0.7.0-rc1 0.7.0-rc1       default
     ```
 
     The Helm chart installation from the sample response above is named `odd-billygoat`. We will
     use this name for the rest of the commands. Your actual deployment name will most likely differ.
 
-2) Upgrade the Helm deployment to a new version:
+1. Upgrade the Helm deployment to a new version:
 
     ```bash
     helm upgrade \
@@ -67,23 +71,24 @@ Before we begin the upgrade procedure, ensure that you have added the required r
 ## Rollback
 
 Should the Helm deployment fail, you can rollback to a previous release.
-1) Get the last known healthy release number:
+
+1. Get the last known healthy release number:
 
     ```bash
     helm history odd-billygoat
     ```
 
     Sample output:
 
-    ```
+    ```bash
     REVISION        UPDATED                         STATUS          CHART                   DESCRIPTION
     1               Mon Jun 17 13:49:42 2019        DEPLOYED        ingress-azure-0.6.0     Install complete
     2               Fri Jun 21 15:56:06 2019        FAILED          ingress-azure-xx        xxxx
     ```
 
     From the sample output of the `helm history` command it looks like the last successful deployment of our `odd-billygoat` was revision `1`
 
-2) Rollback to the last successful revision:
+1. Rollback to the last successful revision:
 
     ```bash
     helm rollback odd-billygoat 1