Markdown fixes for docs (#1642)

Author: JackStromberg

docs/annotations.md

@@ -1,9 +1,6 @@
 # Annotations
 
-.. note::
-    [Application Gateway for Containers](https://aka.ms/agc) has been released, which introduces numerous performance, resilience, and feature changes. Please consider leveraging Application Gateway for Containers for your next deployment.
-
-    A list of corresponding translations from AGIC to Application Gateway for Containers may be found [here](https://learn.microsoft.com/azure/application-gateway/for-containers/migrate-from-agic-to-agc).
+> **_NOTE:_** [Application Gateway for Containers](https://aka.ms/agc) has been released, which introduces numerous performance, resilience, and feature changes. Please consider leveraging Application Gateway for Containers for your next deployment. A list of corresponding translations from AGIC to Application Gateway for Containers may be found [here](https://learn.microsoft.com/azure/application-gateway/for-containers/migrate-from-agic-to-agc).
 
 ## Introductions
 

docs/developers/build.md

@@ -1,11 +1,11 @@
 # Building the controller
 
 * [Running it locally](#running-it-locally)
-    * [Pre-requisite](#pre-requisite)
-    * [Obtain Azure Credentials](#obtain-azure-credentials)
-    * [Deploy Application Gateway and AKS](#deploy-application-gateway-and-aks)
-    * [Using startup script](#using-startup-script)
-    * [Visual Studio Code (F5 debugging)](#visual-studio-code-f5-debugging)
+  * [Pre-requisite](#pre-requisite)
+  * [Obtain Azure Credentials](#obtain-azure-credentials)
+  * [Deploy Application Gateway and AKS](#deploy-application-gateway-and-aks)
+  * [Using startup script](#using-startup-script)
+  * [Visual Studio Code (F5 debugging)](#visual-studio-code-f5-debugging)
 * [Run on a cluster using a Dev Release](#create-a-dev-release)
 * [CMake options](#cmake-options)
 
@@ -14,6 +14,7 @@
 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).
 
 ### Pre-requisite
+
 * [go >= 1.13](https://golang.org/dl/)
 * OpenSSL
 
@@ -45,6 +46,7 @@ The file will contain a JSON blob with the following shape:
 ```
 
 ### Deploy Application Gateway and AKS
+
 To deploy a fresh setup, please follow the steps for template deployment in the [greenfield](../setup/install-new.md) documentation.
 
 ### Using startup script
@@ -54,10 +56,13 @@ In the `scripts` directory you will find `start.sh`. This script builds and runs
 Steps to run ingress controller:
 
 1. Get your cluster's credentials
+
     ```
     az aks get-credentials --name <cluster-name> --resource-group <group>
     ```
+
 1. Configure: `cp .env.example .env` and modify the environment variables in `.env` to match your config. Here is an example:
+
     ```
     #!/bin/bash
     export AZURE_AUTH_LOCATION="$HOME/.azure/azureAuth.json"
@@ -68,7 +73,9 @@ Steps to run ingress controller:
 
     export APPGW_VERBOSITY_LEVEL="9"
     ```
+
 1. Run: `./scripts/start.sh`
+
     ```
     Cleanup: delete /home/vsonline/go/src/github.com/Azure/application-gateway-kubernetes-ingress/bin
     Compiling...
@@ -83,7 +90,9 @@ Steps to run ingress controller:
     ```
 
 ### Visual Studio Code (F5 debugging)
+
 You can also setup vscode to run the project with `F5` and use breakpoint debugging. For this, you need to setup your `launch.json` file within `.vscode` folder.
+
 ```json
 {
     "version": "0.2.0",
@@ -109,11 +118,13 @@ You can also setup vscode to run the project with `F5` and use breakpoint debugg
 ```
 
 ## Create a Dev Release
+
 To test your changes on a cluster, you can use the [`Dev Release`](https://dev.azure.com/azure/application-gateway-kubernetes-ingress/_release?_a=releases&view=mine&definitionId=12) pipeline. Just select the build version from the drop-down list which matches the build in your PR or against your commit in the main branch.
 
 ![dev release pipeline](../images/dev-release.png)
 
 `Dev Release` generates a new docker image and helm package for your changes. Once the pipeline completes, use helm to install the release on your AKS cluster.
+
 ```bash
 # add the staging helm repository
 helm repo add staging https://appgwingress.blob.core.windows.net/ingress-azure-helm-package-staging/
@@ -140,16 +151,16 @@ You can also find the `version` by opening your build in the `Merge Builds` pipe
 
 This is a CMake-based project. Build targets include:
 
-- `ALL_BUILD` (default target) builds `appgw-ingress` and `dockerize` target
-- `devenv` builds a docker image with configured development environment
-- `vendor` installs dependency using `go mod` in a docker container with image from `devenv` target
-- `appgw-ingress` builds the binary for this controller in a docker container with image from `devenv` target
-- `dockerize` builds a docker image with the binary from `appgw-ingress` target
-- `dockerpush` pushes the docker image to a container registry with prefix defined in CMake variable `<deployment_push_prefix>`
+* `ALL_BUILD` (default target) builds `appgw-ingress` and `dockerize` target
+* `devenv` builds a docker image with configured development environment
+* `vendor` installs dependency using `go mod` in a docker container with image from `devenv` target
+* `appgw-ingress` builds the binary for this controller in a docker container with image from `devenv` target
+* `dockerize` builds a docker image with the binary from `appgw-ingress` target
+* `dockerpush` pushes the docker image to a container registry with prefix defined in CMake variable `<deployment_push_prefix>`
 
 To run the CMake targets:
 
 1. `mkdir build && cd build` creates and enters a build directory
 2. `cmake ..` generates project configuration in the build directory
 3. `cmake --build .` to build the default target,
-    or `cmake --build . --target <target_name>` to specify a target to run from above
+    or `cmake --build . --target <target_name>` to specify a target to run from above

docs/developers/contribute.md

@@ -4,7 +4,7 @@ This is a Golang project. You can find the build instructions of the project in
 
 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.
+the rights to use your contribution. For details, visit [https://cla.microsoft.com](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

docs/developers/design.md

@@ -4,8 +4,6 @@
 
 This document is the detailed design and architecture of the Application Gateway Ingress Controller (AGIC) being built in this repository.
 
-
-
 ## Overview
 
 Application Gateway Ingress Controller (AGIC) is a Kubernetes application, which makes it possible for [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/services/kubernetes-service/) customers to leverage Azure's native [Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) L7 load-balancer to expose cloud software to the Internet. AGIC monitors the Kubernetes cluster it is hosted on and continuously updates an App Gateway, so that selected services are exposed to the Internet.
@@ -17,22 +15,24 @@ The Ingress Controller runs in its own pod on the customer’s AKS. AGIC monitor
 ## High-level architecture
 
 The AGIC is composed of the following three sub components:
+
   1. [K8S Context and Informers](#1-k8s-context-and-informers) - handles events from the cluster and alerts the worker
   2. [Worker](#2-worker) - handles events coming from the informer and perform relevant actions
   3. [Application Gateway Config Builder](#3-application-gateway-config-builder) -  generates the new gateway configuration
 
-
 ![components relationship](../images/component-diagram.png)
 
 ## Components
 
 Let's take a look at each component:
 
 ### 1. K8s Context and Informers
+
 When any change is applied on the k8s cluster by the user, AGIC needs to listen to these changes in order to update the corresponding configuration on the Application Gateway.
 We use the kubernetes informers for this purpose which is a standard for watching resources on the K8S API server.
 
 When AGIC starts, it [sets up informers](../pkg/k8scontext/context.go) for watching following resources:
+
 1. [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/): This is the top-level resource that AGIC monitors. It provides information about the layer-7 routing rules that need to be configured on the App Gateway.
 1. [Service](https://kubernetes.io/docs/concepts/services-networking/service/): Service provides an abstraction over the pods to expose as a network service. AGIC uses the service as logical grouping of pods to extract the IP addresses through the endpoints object created automatically along with the Service.
 1. [Endpoints](https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/): Endpoints provides information about Pod IP Addresses behind a service and is used to populate AppGW's backend pool.
@@ -43,17 +43,20 @@ When AGIC starts, it [sets up informers](../pkg/k8scontext/context.go) for watch
 When starting the informers, AGIC also provides event handlers for each for create/update/delete operations on the resource. This handler is responsible for enqueuing an event .
 
 ### 2. Worker
+
 [Worker](../../pkg/worker.go) is responsible for processing the events and performing updates.
 
 When Worker's `Run` function is called, it starts as a separate thread and waits on the `Work` channel. When an informers add an event to the channel, worker dequeues the event and checks whether the event is noise or is relevant. Events that are coming from unwatched namespaces and unreferenced pods/endpoints are skipped to reduce the churn. If the the last worker loop was run less than 1 second ago, it sleeps for the remainder and wakes up to space out the updates.  
 After this, worker starts draining the rest of the events and calling the `ProcessEvent` function to process the event.
 
 `ProcessEvent` function does the following:
+
 1. Check if the Application Gateway is in `Running` or `Starting` operational state.
 1. Updates all ingress resources with public/private IP address of the App Gateway.
 1. Generate new config and update the Application Gateway.
 
 ### 3. Application Gateway Config Builder
+
 This [component](../../pkg/appgw/configbuilder.go) is responsible for using the information in the local kubernetes cache and generating the corresponding Application Gateway configuration as an output.
 
 Worker invokes the `Build` on this component which then generates various gateways sub-resources starting from leaf sub-resources like `probes`, `http settings` up to the `request routing rules`.

docs/developers/developer-guideline.md

@@ -1,9 +1,11 @@
 # Application Gateway Ingress Controller Development Guide
+
 Welcome to the Application Gateway Ingress Controller development guide!
 
 ## Table of contents
+
 - [Understanding the architecture](design.md)
 - [Building and running the controller](build.md)
 - [Installing the latest nightly build](nightly.md)
 - [Running tests](test.md)
-- [Contribution Guidelines](contribute.md)
+- [Contribution Guidelines](contribute.md)

docs/developers/nightly.md

@@ -3,26 +3,29 @@
 To install the latest nightly release,
 
 1. Add the nightly helm repository
-    ```
+
+    ```bash
     helm repo add agic-nightly https://appgwingress.blob.core.windows.net/ingress-azure-helm-package-staging/
     helm repo update
     ```
 
-2. Check the available version
+1. Check the available version
 
     **Latest version**: ![nightly release (latest by date)](https://img.shields.io/badge/dynamic/yaml?url=https://appgwingress.blob.core.windows.net/ingress-azure-helm-package-staging/index.yaml&label=nightly&query=entries[%22ingress-azure%22][0].appVersion&color=green)  
-    
+
     or  
-    
+
     You can look up the version in the repo using helm.
-    ```
+
+    ```bash
     helm search repo agic-nightly
     ```
 
-2.  Install using the same helm command by using the staging repository.
-    ```
+1. Install using the same helm command by using the staging repository.
+
+    ```bash
     helm install ingress-azure \
       -f helm-config.yaml \
       agic-nightly/ingress-azure \
       --version <version>
-    ```
+    ```

docs/developers/test.md

@@ -5,25 +5,30 @@
 * [Testing Tips](#testing-tips)
 
 ## Unit Tests
+
 As is the convention in go, unit tests for the `.go` file you want to test live in the same folder and end with `_test.go`.
 We use the `ginkgo`/`gomega`  testing framework for writing the tests.
 
 To execute the tests, use
+
 ```bash
 go test -v -tags unittest ./...
 ```
 
 ## E2E Tests
+
 E2E tests are going to test the specific scenarios with a real AKS and App Gateway setup with AGIC installed on it.
 
 E2E tests are automatically run every day 3 AM in the morning using an [E2E pipeline](https://dev.azure.com/azure/application-gateway-kubernetes-ingress/_release?_a=releases&view=mine&definitionId=14).
 
 If you have cluster with AGIC installed, you can run e2e tests simply by:
+
 ```bash
 go test -v -tags e2e ./...
 ```
 
 You can also execute the `run-e2e.sh` which is used in the E2E pipeline to invoke the tests. This script will install AGIC with the version provided.
+
 ```bash
 export version="<agic-version>"
 export applicationGatewayId="<resource-id>"
@@ -34,8 +39,10 @@ export identityClientId="<agic-identity-client-id>"
 ```
 
 ## Testing Tips
+
 * If you just want to run a specific set of tests, then an easy way is add `F` (Focus) to the `It`, `Context`, `Describe` directive in the test.
     For example:
+
     ```go
     FContext("Test obtaining a single certificate for an existing host", func() {
         cb := newConfigBuilderFixture(nil)
@@ -51,4 +58,4 @@ export identityClientId="<agic-identity-client-id>"
             Expect(*actualSecretID).To(Equal(expectedSecret))
         })
     })
-    ```
+    ```

docs/faq.md

@@ -1,7 +1,6 @@
 # Frequrently Asked Questions: [WIP]
 
-.. note::
-    [Application Gateway for Containers](https://aka.ms/agc) has been released, which introduces numerous performance, resilience, and feature changes. Please consider leveraging Application Gateway for Containers for your next deployment.
+> **_NOTE:_** [Application Gateway for Containers](https://aka.ms/agc) has been released, which introduces numerous performance, resilience, and feature changes. Please consider leveraging Application Gateway for Containers for your next deployment.
 
 * [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)

docs/features/agic-reconcile.md

@@ -1,22 +1,26 @@
 ## Reconcile scenario (BETA)
 
-.. note::
-    [Application Gateway for Containers](https://aka.ms/agc) has been released, which introduces numerous performance, resilience, and feature changes. Please consider leveraging Application Gateway for Containers for your next deployment.
+> **_NOTE:_** [Application Gateway for Containers](https://aka.ms/agc) has been released, which introduces numerous performance, resilience, and feature changes. Please consider leveraging Application Gateway for Containers for your next deployment.
 
-When an Application Gateway is deployed through ARM template, a requirement is that the gateway configuration should contain a probe, listener, rule, backend pool and backend http setting. When such a template is re-deployed with minor changes (for example to WAF rules) on Gateway that is being controlled by AGIC, all the AGIC written rules are removed. Given such change on Application Gateway doesn’t trigger any events on AGIC, AGIC doesn’t reconcile the gateway back to the expected state. 
+When an Application Gateway is deployed through ARM template, a requirement is that the gateway configuration should contain a probe, listener, rule, backend pool and backend http setting. When such a template is re-deployed with minor changes (for example to WAF rules) on Gateway that is being controlled by AGIC, all the AGIC written rules are removed. Given such change on Application Gateway doesn’t trigger any events on AGIC, AGIC doesn’t reconcile the gateway back to the expected state.
 
 ## Solution
+
 To address the problem above, AGIC periodically checks if the latest gateway configuration is different from what it cached, and reconcile if needed to make gateway configuration is eventual correct.
 
 ## How to configure reconcile
+
 There are two ways to configure AGIC reconcile via helm, and to use the new feature, make sure the AGIC version is at least at 1.2.0-rc1
 
 ### Configure inside helm values.yaml
+
 `reconcilePeriodSeconds: 30`, it means AGIC checks the reconciling in every 30 seconds.
 Acceptable values are between 30 and 300.
 
 ### Configure from helm command line
+
 Configure from helm install command(first time install) and helm upgrade command, helm version is v3
+
 ```bash
 # helm fresh install
 helm intall <releaseName> -f helm-config.yaml application-gateway-kubernetes-ingress/ingress-azure --version 1.2.0-rc3 --set reconcilePeriodSeconds=30 

docs/features/appgw-ssl-certificate.md

@@ -1,9 +1,9 @@
 ### Prerequisites
 
-.. note::
-    [Application Gateway for Containers](https://aka.ms/agc) has been released, which introduces numerous performance, resilience, and feature changes. Please consider leveraging Application Gateway for Containers for your next deployment.
+> **_NOTE:_** [Application Gateway for Containers](https://aka.ms/agc) has been released, which introduces numerous performance, resilience, and feature changes. Please consider leveraging Application Gateway for Containers for your next deployment.
 
 This documents assumes you already have the following Azure tools and resources installed:
+
 - [AKS](https://azure.microsoft.com/en-us/services/kubernetes-service/) with [Advanced Networking](https://docs.microsoft.com/en-us/azure/aks/configure-azure-cni) enabled
 - [App Gateway v2](https://docs.microsoft.com/en-us/azure/application-gateway/create-zone-redundant) in the same virtual network as AKS
 - [AAD Pod Identity](https://github.com/Azure/aad-pod-identity) installed on your AKS cluster
@@ -12,12 +12,15 @@ This documents assumes you already have the following Azure tools and resources
 Please use [Greenfield Deployment](https://github.com/Azure/application-gateway-kubernetes-ingress/blob/master/docs/setup/install-new.md) to install nonexistents.
 
 To use the new feature, make sure the AGIC version is at least at 1.2.0-rc3
+
 ```bash
 helm install application-gateway-kubernetes-ingress/ingress-azure -f helm-config.yaml --version 1.2.0-rc3 --generate-name
 ```
 
 ## Create a certificate and configure the certificate to AppGw
+
 The certificate below should only be used for testing purpose.
+
 ```bash
 appgwName=""
 resgp=""
@@ -44,6 +47,7 @@ az network application-gateway ssl-cert create \
 ```
 
 ## Configure certificate from Key Vault to AppGw
+
 To configfure certificate from key vault to Application Gateway, an user-assigned managed identity will need to be created and assigned to AppGw, the managed identity will need to have GET secret access to KeyVault.
 
 ```bash
@@ -107,6 +111,7 @@ az network application-gateway ssl-cert create \
 ```
 
 ## Testing the key vault certificate on Ingress
+
 Since we have certificate from Key Vault configured in Application Gateway, we can then add the new annotation `appgw.ingress.kubernetes.io/appgw-ssl-certificate: mykvsslcert` in Kubernetes ingress to enable the feature.
 
 ```bash