From 9bed6a450e0bf05467aabcd0eb187b545197ec80 Mon Sep 17 00:00:00 2001 From: Akshay Gupta Date: Tue, 16 Jul 2019 12:32:06 -0700 Subject: [PATCH] docs: mkdocs based docs (#373) --- _config.yml | 3 - docs/.index | 11 ++ docs/annotations.md | 31 +++- docs/css/extra.css | 35 ++++ docs/{ => developers}/build.md | 15 +- docs/developers/contribute.md | 14 ++ docs/faq.md | 9 +- docs/features.md | 6 - docs/features/multiple-namespaces.md | 2 +- docs/features/private-ip.md | 7 +- docs/features/probes.md | 9 +- docs/how-to.md | 5 - docs/how-tos/helm-upgrade.md | 25 +-- docs/how-tos/lets-encrypt.md | 254 +++++++++++++-------------- docs/index.md | 18 ++ docs/{ => setup}/install-existing.md | 54 +++--- docs/{ => setup}/install-new.md | 64 ++++--- docs/tutorial.md | 115 ++++++------ mkdocs.yml | 48 +++++ 19 files changed, 447 insertions(+), 278 deletions(-) delete mode 100644 _config.yml create mode 100644 docs/.index create mode 100644 docs/css/extra.css rename docs/{ => developers}/build.md (93%) create mode 100644 docs/developers/contribute.md delete mode 100644 docs/features.md delete mode 100644 docs/how-to.md create mode 100644 docs/index.md rename docs/{ => setup}/install-existing.md (78%) rename docs/{ => setup}/install-new.md (82%) create mode 100644 mkdocs.yml diff --git a/_config.yml b/_config.yml deleted file mode 100644 index f6e567d46..000000000 --- a/_config.yml +++ /dev/null @@ -1,3 +0,0 @@ -theme: jekyll-theme-cayman -title: Azure Application Gateway Ingress Controller. -markdown: GFM diff --git a/docs/.index b/docs/.index new file mode 100644 index 000000000..4744d106b --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/annotations.md b/docs/annotations.md index cc3a1e1a3..b67785e9d 100644 --- 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: ``` ### Example + ```yaml apiVersion: extensions/v1beta1 kind: Ingress @@ -43,6 +50,7 @@ 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 @@ -50,11 +58,13 @@ controller will create a [routing rule with a redirection configuration](https:/ 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 -``` \ No newline at end of file +``` diff --git a/docs/css/extra.css b/docs/css/extra.css new file mode 100644 index 000000000..cb7aa8548 --- /dev/null +++ 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 b/docs/developers/build.md similarity index 93% rename from docs/build.md rename to docs/developers/build.md index 35e2a4b16..f36f0ccea 100644 --- a/docs/build.md +++ b/docs/developers/build.md @@ -1,4 +1,6 @@ -## Building +# Building the controller + +## CMake options This is a CMake-based project. Build targets include: @@ -16,8 +18,8 @@ To run the CMake targets: 3. `cmake --build .` to build the default target, or `cmake --build . --target ` 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 @@ -25,10 +27,13 @@ This section outlines the environment variables and files necessary to successfu 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 --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 new file mode 100644 index 000000000..a69c8cb19 --- /dev/null +++ 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 [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. diff --git a/docs/faq.md b/docs/faq.md index f2a9a09a4..8f3b13afa 100644 --- 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. \ No newline at end of file diff --git a/docs/features.md b/docs/features.md deleted file mode 100644 index e65557289..000000000 --- a/docs/features.md +++ /dev/null @@ -1,6 +0,0 @@ -# Features - -* [Multiple Namespaces Support](features/multiple-namespaces.md) -* [Private IP for internal routing](features/private-ip.md) -* [Backend Health Probes](features/probes.md) -* [Cookie Based Affinity](features/cookie-affinity.md) diff --git a/docs/features/multiple-namespaces.md b/docs/features/multiple-namespaces.md index 45aa8bbe6..335fce431 100644 --- 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 index 388a2c4dc..093e68bc6 100644 --- 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 index 23758b472..191aec6e2 100644 --- 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 deleted file mode 100644 index 6f05b7222..000000000 --- a/docs/how-to.md +++ /dev/null @@ -1,5 +0,0 @@ -# How-Tos - -* [How to integrate with `lets encrypt` for automatic certificate issuance and rotation ?](how-tos/lets-encrypt.md) -* [How to expose a WebSocket server ?](how-tos/websockets.md) -* [How to upgrade/rollback AGIC using helm](how-tos/helm-upgrade.md) diff --git a/docs/how-tos/helm-upgrade.md b/docs/how-tos/helm-upgrade.md index 2f840401d..c81f10c6f 100644 --- 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,14 +43,15 @@ 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 ``` @@ -55,7 +59,7 @@ Before we begin the upgrade procedure, ensure that you have added the required r 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,7 +71,8 @@ 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 @@ -75,7 +80,7 @@ Should the Helm deployment fail, you can rollback to a previous release. 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 @@ -83,7 +88,7 @@ Should the Helm deployment fail, you can rollback to a previous release. 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 diff --git a/docs/how-tos/lets-encrypt.md b/docs/how-tos/lets-encrypt.md index 88befb220..432999199 100644 --- a/docs/how-tos/lets-encrypt.md +++ b/docs/how-tos/lets-encrypt.md @@ -1,135 +1,133 @@ -## Certificate issuance with LetsEncrypt.org +# Certificate issuance with LetsEncrypt.org This section configures your AKS to leverage [LetsEncrypt.org](https://letsencrypt.org/) and automatically obtain a TLS/SSL certificate for your domain. The certificate will be installed on Application Gateway, which will perform SSL/TLS termination for your AKS cluster. The setup described here uses the -[cert-manager](https://github.com/jetstack/cert-manager) Kubernetes add-on, which automates the creation and management of -certificates. +[cert-manager](https://github.com/jetstack/cert-manager) Kubernetes add-on, which automates the creation and management of certificates. Follow the steps below to install [cert-manager](https://docs.cert-manager.io) on your existing AKS cluster. -##### 1. Helm Chart - -Run the following script to install the `cert-manager` helm chart. This will: - - create a new `cert-manager` namespace on your AKS - - create the following CRDs: Certificate, Challenge, ClusterIssuer, Issuer, Order - - install cert-manager chart (from [docs.cert-manager.io)](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#steps) - - -```bash -#!/bin/bash - -# Install the CustomResourceDefinition resources separately -kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.8/deploy/manifests/00-crds.yaml - -# Create the namespace for cert-manager -kubectl create namespace cert-manager - -# Label the cert-manager namespace to disable resource validation -kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true - -# Add the Jetstack Helm repository -helm repo add jetstack https://charts.jetstack.io - -# Update your local Helm chart repository cache -helm repo update - -# Install the cert-manager Helm chart -helm install \ - --name cert-manager \ - --namespace cert-manager \ - --version v0.8.0 \ - jetstack/cert-manager -``` - -##### 2. ClusterIssuer Resource - -Create a `ClusterIssuer` resource. It is required by `cert-manager` to represent the `Lets Encrypt` certificate -authority where the signed certificates will be obtained. - -By using the non-namespaced `ClusterIssuer` resource, cert-manager will issue certificates that can be consumed from -multiple namespaces. `Let’s Encrypt` uses the ACME protocol to verify that you control a given domain name and to issue -you a certificate. More details on configuring `ClusterIssuer` properties -[here](https://docs.cert-manager.io/en/latest/tasks/issuers/index.html). `ClusterIssuer` will instruct `cert-manager` -to issue certificates using the `Lets Encrypt` staging environment used for testing (the root certificate not present -in browser/client trust stores). - -The default challenge type in the YAML below is `http01`. Other challenges are documented on [letsencrypt.org - Challenge Types](https://letsencrypt.org/docs/challenge-types/) - -**IMPORTANT:** Update `` in the YAML below - -```bash -#!/bin/bash -kubectl apply -f - < - # ACME server URL for Let’s Encrypt’s staging environment. - # The staging environment will not issue trusted certificates but is - # used to ensure that the verification process is working properly - # before moving to production - server: https://acme-staging-v02.api.letsencrypt.org/directory - privateKeySecretRef: - # Secret resource used to store the account's private key. - name: example-issuer-account-key - # Enable the HTTP-01 challenge provider - # you prove ownership of a domain by ensuring that a particular - # file is present at the domain - http01: {} -EOF -``` - -##### 3. Deploy App - -Create an Ingress resource to Expose the `guestbook` application using the Application Gateway with the Lets Encrypt Certificate. - -Ensure you Application Gateway has a public Frontend IP configuration with a DNS name (either using the -default `azure.com` domain, or provision a `Azure DNS Zone` service, and assign your own custom domain). -Note the annotation `certmanager.k8s.io/cluster-issuer: letsencrypt-staging`, which tells cert-manager to process the -tagged Ingress resource. - -**IMPORTANT:** Update `` in the YAML below with your own domain (or the Application Gateway one, for example -'kh-aks-ingress.westeurope.cloudapp.azure.com') - -```bash -kubectl apply -f - < - secretName: guestbook-secret-name - rules: - - host: - http: - paths: - - backend: - serviceName: frontend - servicePort: 80 -EOF -``` - -After a few seconds, you can access the `guestbook` service through the Application Gateway HTTPS url using the automatically issued **staging** `Lets Encrypt` certificate. -Your browser may warn you of an invalid cert authority. The staging certificate is issued by `CN=Fake LE Intermediate X1`. This is an indication that the system worked as expected and you are ready for your production certificate. - - -##### 4. Production Certificate -Once your staging certificate is setup successfully you can switch to a production ACME server: - 1. Replace the staging annotation on your Ingress resource with: `certmanager.k8s.io/cluster-issuer: letsencrypt-prod` - 2. Delete the existing staging `ClusterIssuer` you created in the previous step and create a new one by replacing the ACME server from the ClusterIssuer YAML above with `https://acme-v02.api.letsencrypt.org/directory` - -##### 5. Certificate Expiration and Renewal -Before the `Lets Encrypt` certificate expires, `cert-manager` will automatically update the certificate in the Kubernetes secret store. At that point, Application Gateway Ingress Controller will apply the updated secret referenced in the ingress resources it is using to configure the Application Gateway. \ No newline at end of file +1. Helm Chart + + Run the following script to install the `cert-manager` helm chart. This will: + + - create a new `cert-manager` namespace on your AKS + - create the following CRDs: Certificate, Challenge, ClusterIssuer, Issuer, Order + - install cert-manager chart (from [docs.cert-manager.io)](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#steps) + + ```bash + #!/bin/bash + + # Install the CustomResourceDefinition resources separately + kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.8/deploy/manifests/00-crds.yaml + + # Create the namespace for cert-manager + kubectl create namespace cert-manager + + # Label the cert-manager namespace to disable resource validation + kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true + + # Add the Jetstack Helm repository + helm repo add jetstack https://charts.jetstack.io + + # Update your local Helm chart repository cache + helm repo update + + # Install the cert-manager Helm chart + helm install \ + --name cert-manager \ + --namespace cert-manager \ + --version v0.8.0 \ + jetstack/cert-manager + ``` + +2. ClusterIssuer Resource + + Create a `ClusterIssuer` resource. It is required by `cert-manager` to represent the `Lets Encrypt` certificate + authority where the signed certificates will be obtained. + + By using the non-namespaced `ClusterIssuer` resource, cert-manager will issue certificates that can be consumed from + multiple namespaces. `Let’s Encrypt` uses the ACME protocol to verify that you control a given domain name and to issue + you a certificate. More details on configuring `ClusterIssuer` properties + [here](https://docs.cert-manager.io/en/latest/tasks/issuers/index.html). `ClusterIssuer` will instruct `cert-manager` + to issue certificates using the `Lets Encrypt` staging environment used for testing (the root certificate not present + in browser/client trust stores). + + The default challenge type in the YAML below is `http01`. Other challenges are documented on [letsencrypt.org - Challenge Types](https://letsencrypt.org/docs/challenge-types/) + + **IMPORTANT:** Update `` in the YAML below + + ```bash + #!/bin/bash + kubectl apply -f - < + # ACME server URL for Let’s Encrypt’s staging environment. + # The staging environment will not issue trusted certificates but is + # used to ensure that the verification process is working properly + # before moving to production + server: https://acme-staging-v02.api.letsencrypt.org/directory + privateKeySecretRef: + # Secret resource used to store the account's private key. + name: example-issuer-account-key + # Enable the HTTP-01 challenge provider + # you prove ownership of a domain by ensuring that a particular + # file is present at the domain + http01: {} + EOF + ``` + +3. Deploy App + + Create an Ingress resource to Expose the `guestbook` application using the Application Gateway with the Lets Encrypt Certificate. + + Ensure you Application Gateway has a public Frontend IP configuration with a DNS name (either using the + default `azure.com` domain, or provision a `Azure DNS Zone` service, and assign your own custom domain). + Note the annotation `certmanager.k8s.io/cluster-issuer: letsencrypt-staging`, which tells cert-manager to process the + tagged Ingress resource. + + **IMPORTANT:** Update `` in the YAML below with your own domain (or the Application Gateway one, for example + 'kh-aks-ingress.westeurope.cloudapp.azure.com') + + ```bash + kubectl apply -f - < + secretName: guestbook-secret-name + rules: + - host: + http: + paths: + - backend: + serviceName: frontend + servicePort: 80 + EOF + ``` + + After a few seconds, you can access the `guestbook` service through the Application Gateway HTTPS url using the automatically issued **staging** `Lets Encrypt` certificate. + Your browser may warn you of an invalid cert authority. The staging certificate is issued by `CN=Fake LE Intermediate X1`. This is an indication that the system worked as expected and you are ready for your production certificate. + +4. Production Certificate + Once your staging certificate is setup successfully you can switch to a production ACME server: + 1. Replace the staging annotation on your Ingress resource with: `certmanager.k8s.io/cluster-issuer: letsencrypt-prod` + 1. Delete the existing staging `ClusterIssuer` you created in the previous step and create a new one by replacing the ACME server from the ClusterIssuer YAML above with `https://acme-v02.api.letsencrypt.org/directory` + +5. Certificate Expiration and Renewal + Before the `Lets Encrypt` certificate expires, `cert-manager` will automatically update the certificate in the Kubernetes secret store. At that point, Application Gateway Ingress Controller will apply the updated secret referenced in the ingress resources it is using to configure the Application Gateway. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..129a016f1 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,18 @@ +# Introduction + +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. + +As shown in the figure below, the ingress controller runs as a pod within the AKS cluster. It consumes [Kubernetes `Ingress` Resources](http://kubernetes.io/docs/user-guide/ingress/) and converts them to an Azure Application Gateway configuration which allows the gateway to load-balance traffic to Kubernetes pods. + +![Azure Application Gateway + AKS](images/architecture.png) + +## Reporting Issues + +The best way to report an issue is to create a Github Issue for the project. Please include the following information when creating the issue: + +* Subscription ID for AKS cluster. +* Subscription ID for Application Gateway. +* AKS cluster name/ARM Resource ID. +* Application Gateway name/ARM Resource ID. +* Ingress resource definition that might causing the problem. +* The Helm configuration used to install the ingress controller. diff --git a/docs/install-existing.md b/docs/setup/install-existing.md similarity index 78% rename from docs/install-existing.md rename to docs/setup/install-existing.md index 7716805bc..f904d5b2e 100644 --- a/docs/install-existing.md +++ b/docs/setup/install-existing.md @@ -1,24 +1,31 @@ -# Table of Contents +# Brownfield Deployment + +## Table of Contents + - [Prerequisites](#prerequisites) - [Setting up Authentication with Azure Resource Manager (ARM)](#setting-up-authentication-with-azure-resource-manager) - * [Setting up aad-pod-identity](#setting-up-aad-pod-identity) - + [Create Azure Identity on ARM](#create-azure-identity-on-arm) + - [Setting up aad-pod-identity](#setting-up-aad-pod-identity) + -[Create Azure Identity on ARM](#create-azure-identity-on-arm) - [Install Ingress Controller using Helm](#install-ingress-controller-as-a-helm-chart) -# Setting up Application Gateway ingress controller on AKS +## Setting up Application Gateway ingress controller on AKS + The Application Gateway Ingress controller runs as pod within the AKS cluster. It listens to [Kubernetes Ingress Resources](https://kubernetes.io/docs/concepts/services-networking/ingress/) from the Kubernetes API server and converts them to Azure Application Gateway configuration and updates the Application Gateway through the Azure Resource Manager (ARM). In order to install the ingress controller on AKS we use [Helm](https://docs.microsoft.com/en-us/azure/aks/kubernetes-helm). -## Prerequisites -* An existing [Azure Application Gateway v2](https://docs.microsoft.com/en-us/azure/application-gateway/create-zone-redundant). -* An existing Azure Kubernetes Service cluster with [Advanced Networking](https://docs.microsoft.com/en-us/azure/aks/configure-azure-cni) enabled. -* The [aad-pod-identity](https://github.com/Azure/aad-pod-identity) service is installed on the AKS cluster. +### Prerequisites + +- An existing [Azure Application Gateway v2](https://docs.microsoft.com/en-us/azure/application-gateway/create-zone-redundant). +- An existing Azure Kubernetes Service cluster with [Advanced Networking](https://docs.microsoft.com/en-us/azure/aks/configure-azure-cni) enabled. +- The [aad-pod-identity](https://github.com/Azure/aad-pod-identity) service is installed on the AKS cluster. + +### Setting up Authentication with Azure Resource Manager -## Setting up Authentication with Azure Resource Manager Since the ingress controller needs to talk to the Kubernetes API server and the Azure Resource Manager it will need an identity to access both these entities. Since we are currently supporting only a non-RBAC cluster, the ingress controller currently does not need an identity to talk to the Kubernetes API server but needs and identity to talk to ARM. ### Setting up aad-pod-identity + The [aad-pod-identity](https://github.com/Azure/aad-pod-identity) gives a clean way of exposing an existing Azure AD identity to a pod. Kindly follow the [aad-pod-identity installation instructions](https://github.com/Azure/aad-pod-identity#deploy-the-azure-aad-identity-infra) to deploy the aad-pod-identity service on your AKS cluster. This is a pre-requisite for installing the ingress controller. #### Create Azure Identity on ARM @@ -28,15 +35,21 @@ The [aad-pod-identity](https://github.com/Azure/aad-pod-identity) gives a clean ```bash az identity create -g -n ``` -2. Find the principal, resource and client ID for this identity + +1. Find the principal, resource and client ID for this identity + ```bash az identity show -g -n ``` -3. Assign this new identity `Contributor` access on the application gateway + +1. Assign this new identity `Contributor` access on the application gateway + ```bash az role assignment create --role Contributor --assignee --scope ``` -4. Assign this new identity `Reader` access on the resource group that the application gateway belongs to + +1. Assign this new identity `Reader` access on the resource group that the application gateway belongs to + ```bash az role assignment create --role Reader --assignee --scope ``` @@ -50,7 +63,7 @@ The [aad-pod-identity](https://github.com/Azure/aad-pod-identity) gives a clean helm repo update ``` -2. Edit [helm-config.yaml](examples/sample-helm-config.yaml) and fill in the values for `appgw` and `armAuth` +1. Edit [helm-config.yaml](../examples/sample-helm-config.yaml) and fill in the values for `appgw` and `armAuth` ```yaml # This file contains the essential configs for the ingress controller helm chart @@ -97,18 +110,19 @@ The [aad-pod-identity](https://github.com/Azure/aad-pod-identity) gives a clean ``` **NOTE:** The `` and `` are the properties of the Azure AD Identity you setup in the previous section. You can retrieve this information by running the following command: - ```bash - az identity show -g -n - ``` - Where `` is the resource group in which AKS cluster is running (this would have the prefix `MC_`). + ```bash + az identity show -g -n + ``` + + Where `` is the resource group in which AKS cluster is running (this would have the prefix `MC_`). -3. Install the helm chart `application-gateway-kubernetes-ingress` with the `helm-config.yaml` configuration from the previous step +1. Install the helm chart `application-gateway-kubernetes-ingress` with the `helm-config.yaml` configuration from the previous step ```bash helm install -f application-gateway-kubernetes-ingress/ingress-azure ``` -4. Check the log of the newly created pod to verify if it started properly +1. Check the log of the newly created pod to verify if it started properly -Refer to the [tutorials](tutorial.md) to understand how you can expose an AKS service over HTTP or HTTPS, to the internet, using an Azure Application Gateway. +Refer to the [tutorials](../tutorial.md) to understand how you can expose an AKS service over HTTP or HTTPS, to the internet, using an Azure Application Gateway. diff --git a/docs/install-new.md b/docs/setup/install-new.md similarity index 82% rename from docs/install-new.md rename to docs/setup/install-new.md index 496185b9d..1ef2e7b0a 100644 --- a/docs/install-new.md +++ b/docs/setup/install-new.md @@ -1,32 +1,35 @@ -# Table of Contents +# Greenfield Deployment + +## Table of Contents + - [Deploying the infrastructure on Azure](#deploying-the-infrastructure-on-azure) - [Setting up Application Gateway Ingress Controller on AKS](#setting-up-application-gateway-ingress-controller-on-aks) ## Deploying the infrastructure on Azure To create the pre-requisite Azure resources, you can use the following template. It creates: -1) Azure Virtual Network with 2 subnets. -2) Azure Application Gateway v2. -3) Azure Kubernetes Service cluster with required permission to deploy nodes in the Virtual Network. You have an option to deploy RBAC enabled AKS cluster -4) User Assigned Identity to initialize the aad-pod-identity service and ingress controller. -5) Set required RBACs. +1. Azure Virtual Network with 2 subnets. +1. Azure Application Gateway v2. +1. Azure Kubernetes Service cluster with required permission to deploy nodes in the Virtual Network. You have an option to deploy RBAC enabled AKS cluster +1. User Assigned Identity to initialize the aad-pod-identity service and ingress controller. +1. Set required RBACs. -## Prerequisites +### Prerequisites The steps below require the following software to be installed on your workstation: - 1. `az` - Azure CLI: [installation instructions](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) - 1. `kubectl` - Kubernetes command-line tool: [installation instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl) - 1. `helm` - tool for managing pre-configured Kubernetes resources: [installation instructions](https://github.com/helm/helm/releases/latest) +1. `az` - Azure CLI: [installation instructions](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) +1. `kubectl` - Kubernetes command-line tool: [installation instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl) +1. `helm` - tool for managing pre-configured Kubernetes resources: [installation instructions](https://github.com/helm/helm/releases/latest) -## Steps +### Steps 1. Create an Azure Active Directory (Azure AD) [service principal](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals#service-principal-object) object. This object will be assigned to the AKS cluster in the template. As a result of executing the commands below you will have an `appId`, `password`, and `objectId` values. Execute the following commands: 1. `az ad sp create-for-rbac --skip-assignment` - creates an AD service principal object. Record and securely store the values for the `appId` and `password` keys from the JSON output of this command. ([Read more about RBAC](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview)) 1. `az ad sp show --id --query "objectId"` - retrieves the `objectId` of the newly created service principal. Replace `` with the value for the `appId` key from the JSON output of the previous command. Record the `objectId` value returned. -2. After creating the service principal in the step above, click to create a custom template deployment. Provide the appId for servicePrincipalClientId, password and objectId in the parameters. +1. After creating the service principal in the step above, click to create a custom template deployment. Provide the appId for servicePrincipalClientId, password and objectId in the parameters. Note: For deploying an *RBAC* enabled cluster, set `aksEnabledRBAC` parameter to `true`. @@ -46,12 +49,14 @@ The steps below require the following software to be installed on your workstati After the deployment completes, you will find the parameters needed for the steps below in the deployment outputs window. (Navigate to the deployment's output by following this path in the [Azure portal](https://portal.azure.com/): `Home 🠆 *resource group* 🠆 Deployments 🠆 *new deployment* 🠆 Outputs`) Example: - ![Deployment Output](images/deployment-output.png) + ![Deployment Output](../images/deployment-output.png) ## Setting up Application Gateway Ingress Controller on AKS ### Overview + With the instructions in the previous section we created and configured a new Azure Kubernetes Service (AKS) cluster. We are now ready to deploy to our new Kubernetes infrastructure. The instructions below will guide us through the proccess of installing the following 2 components on our new AKS: + 1. **Azure Active Directory Pod Identity** - Provides token-based access to the [Azure Resource Manager (ARM)](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview) via user-assigned identity. Adding this system will result in the installation of the following within your AKS cluster: 1. Custom Kubernetes resource definitions: `AzureIdentity`, `AzureAssignedIdentity`, `AzureIdentityBinding` 1. [Managed Identity Controller (MIC)](https://github.com/Azure/aad-pod-identity#managed-identity-controllermic) component @@ -60,29 +65,34 @@ With the instructions in the previous section we created and configured a new Az Steps: -1) To configure kubectl to connect to the deployed Azure Kubernetes Cluster, follow these [instructions](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough#connect-to-the-cluster). +1. To configure kubectl to connect to the deployed Azure Kubernetes Cluster, follow these [instructions](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough#connect-to-the-cluster). + +1. Add aad pod identity service to the cluster using the following command. This service will be used by the ingress controller. You can refer [aad-pod-identity](https://github.com/Azure/aad-pod-identity) for more information. + + - *RBAC disabled* AKS cluster -2) Add aad pod identity service to the cluster using the following command. This service will be used by the ingress controller. You can refer [aad-pod-identity](https://github.com/Azure/aad-pod-identity) for more information. - * *RBAC disabled* AKS cluster - ```bash kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment.yaml ``` - * *RBAC enabled* AKS cluster - + - *RBAC enabled* AKS cluster + ```bash kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment-rbac.yaml ``` -3) Install [Helm](https://docs.microsoft.com/en-us/azure/aks/kubernetes-helm) and run the following to add `application-gateway-kubernetes-ingress` helm package: +1. Install [Helm](https://docs.microsoft.com/en-us/azure/aks/kubernetes-helm) and run the following to add `application-gateway-kubernetes-ingress` helm package: + + - *RBAC disabled* AKS cluster - * *RBAC disabled* AKS cluster - ```bash helm init helm repo add application-gateway-kubernetes-ingress https://azure.github.io/application-gateway-kubernetes-ingress/helm/ helm repo update ``` - * *RBAC enabled* AKS cluster - + - *RBAC enabled* AKS cluster + ```bash kubectl create serviceaccount --namespace kube-system tiller-sa kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller-sa @@ -91,7 +101,7 @@ Steps: helm repo update ``` -4) Edit [helm-config.yaml](examples/sample-helm-config.yaml) and fill in the values for `appgw` and `armAuth` +1. Edit [helm-config.yaml](../examples/sample-helm-config.yaml) and fill in the values for `appgw` and `armAuth` ```yaml # This file contains the essential configs for the ingress controller helm chart @@ -138,10 +148,12 @@ Steps: ``` **NOTE:** The `` and `` are the properties of the Azure AD Identity you setup in the previous section. You can retrieve this information by running the following command: - ```bash - az identity show -g -n - ``` - Where `` is the resource group in which the top level AKS cluster object, Application Gateway and Managed Identify are deployed. + + ```bash + az identity show -g -n + ``` + + Where `` is the resource group in which the top level AKS cluster object, Application Gateway and Managed Identify are deployed. Then execute the following to the install the Application Gateway ingress controller package. @@ -149,4 +161,4 @@ Steps: helm install -f helm-config.yaml application-gateway-kubernetes-ingress/ingress-azure ``` -Jump next to **[tutorials](tutorial.md)** to understand how you can expose an AKS service over HTTP or HTTPS, to the internet, using an Azure Application Gateway. +Jump next to **[tutorials](../tutorial.md)** to understand how you can expose an AKS service over HTTP or HTTPS, to the internet, using an Azure Application Gateway. diff --git a/docs/tutorial.md b/docs/tutorial.md index 98ebc6d34..c266dfaac 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -1,20 +1,22 @@ -# Table of Contents +# Tutorials + +These tutorials help illustrate the usage of [Kubernetes Ingress Resources](https://kubernetes.io/docs/concepts/services-networking/ingress/) to expose an example Kubernetes service through the [Azure Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) over HTTP or HTTPS. + +## Table of Contents + - [Prerequisites](#prerequisites) - [Deploy `guestbook` application](#deploy-guestbook-application) - [Expose services over HTTP](#expose-services-over-http) - [Expose services over HTTPS](#expose-services-over-https) - * [Without specified hostname](#without-specified-hostname) - * [With specified hostname](#with-specified-hostname) + - [Without specified hostname](#without-specified-hostname) + - [With specified hostname](#with-specified-hostname) - [Integrate with other services](#integrate-with-other-services) -# Tutorials -These tutorials help illustrate the usage of [Kubernetes Ingress Resources](https://kubernetes.io/docs/concepts/services-networking/ingress/) to expose an example Kubernetes service through the [Azure Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) over HTTP or HTTPS. - ## Prerequisites - Installed `ingress-azure` helm chart. - - **Greenfield Deployment**: If you are starting from scratch, refer to these [installation](install-new.md) instructions which outlines steps to deploy an AKS cluster with Application Gateway and install application gateway ingress controller on the AKS cluster. - - **Brownfield Deployment**: If you have an existing AKS cluster and Application Gateway, refer to these [installation](install-existing.md) instructions to install application gateway ingress controller on the AKS cluster. + - [**Greenfield Deployment**](setup/install-new.md): If you are starting from scratch, refer to these installation instructions which outlines steps to deploy an AKS cluster with Application Gateway and install application gateway ingress controller on the AKS cluster. + - [**Brownfield Deployment**](setup/install-existing.md): If you have an existing AKS cluster and Application Gateway, refer to these instructions to install application gateway ingress controller on the AKS cluster. - If you want to use HTTPS on this application, you will need a x509 certificate and its private key. ## Deploy `guestbook` application @@ -24,15 +26,14 @@ The guestbook application is a canonical Kubernetes application that composes of Follow the instructions below to deploy the guestbook application. 1. Download `guestbook-all-in-one.yaml` from [here](https://raw.githubusercontent.com/kubernetes/examples/master/guestbook/all-in-one/guestbook-all-in-one.yaml) -2. Deploy `guestbook-all-in-one.yaml` into your AKS cluster by running +1. Deploy `guestbook-all-in-one.yaml` into your AKS cluster by running - ```bash - kubectl apply -f guestbook-all-in-one.yaml - ``` + ```bash + kubectl apply -f guestbook-all-in-one.yaml + ``` Now, the `guestbook` application has been deployed. - ## Expose services over HTTP In order to expose the guestbook application we will using the following ingress resource: @@ -58,13 +59,13 @@ as a default backend of the Application Gateway. Save the above ingress resource as `ing-guestbook.yaml`. -1. Deploy `ing-guestbook.yaml` by running +1. Deploy `ing-guestbook.yaml` by running: ```bash kubectl apply -f ing-guestbook.yaml ``` -2. Check the log of the ingress controller for deployment status. +1. Check the log of the ingress controller for deployment status. Now the `guestbook` application should be available. You can check this by visiting the public address of the Application Gateway. @@ -75,43 +76,41 @@ public address of the Application Gateway. Without specifying hostname, the guestbook service will be available on all the host-names pointing to the application gateway. -1. Before deploying ingress, you need to create a kubernetes secret to host the certificate and private key. - You can create a kubernetes secret by running +1. Before deploying ingress, you need to create a kubernetes secret to host the certificate and private key. You can create a kubernetes secret by running ```bash kubectl create secret tls --key --cert ``` -2. Define the following ingress. In the ingress, specify the name of the secret in the `secretName` section. +1. Define the following ingress. In the ingress, specify the name of the secret in the `secretName` section. ```yaml - apiVersion: extensions/v1beta1 - kind: Ingress - metadata: - name: guestbook - annotations: - kubernetes.io/ingress.class: azure/application-gateway - spec: - tls: - - secretName: - rules: - - http: - paths: - - backend: - serviceName: frontend - servicePort: 80 + apiVersion: extensions/v1beta1 + kind: Ingress + metadata: + name: guestbook + annotations: + kubernetes.io/ingress.class: azure/application-gateway + spec: + tls: + - secretName: + rules: + - http: + paths: + - backend: + serviceName: frontend + servicePort: 80 ``` - *NOTE:* Replace `` in the above Ingress Resource with the name of your secret. - Store the above Ingress Resource in a file name `ing-guestbook-tls.yaml`. + *NOTE:* Replace `` in the above Ingress Resource with the name of your secret. Store the above Ingress Resource in a file name `ing-guestbook-tls.yaml`. -3. Deploy ing-guestbook-tls.yaml by running +1. Deploy ing-guestbook-tls.yaml by running ```bash kubectl apply -f ing-guestbook-tls.yaml ``` -4. Check the log of the ingress controller for deployment status. +1. Check the log of the ingress controller for deployment status. Now the `guestbook` application will be available on both HTTP and HTTPS. @@ -144,13 +143,13 @@ By specifying hostname, the guestbook service will only be available on the spec servicePort: 80 ``` -2. Deploy `ing-guestbook-tls-sni.yaml` by running +1. Deploy `ing-guestbook-tls-sni.yaml` by running ```bash kubectl apply -f ing-guestbook-tls-sni.yaml ``` -3. Check the log of the ingress controller for deployment status. +1. Check the log of the ingress controller for deployment status. Now the `guestbook` application will be available on both HTTP and HTTPS only on the specified host (`` in this example). @@ -158,22 +157,22 @@ Now the `guestbook` application will be available on both HTTP and HTTPS only on The following ingress will allow you to add additional paths into this ingress and redirect those paths to other services: -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: guestbook - annotations: - kubernetes.io/ingress.class: azure/application-gateway -spec: - rules: - - http: - paths: - - path: - backend: - serviceName: - servicePort: 80 - - backend: - serviceName: frontend - servicePort: 80 -``` + ```yaml + apiVersion: extensions/v1beta1 + kind: Ingress + metadata: + name: guestbook + annotations: + kubernetes.io/ingress.class: azure/application-gateway + spec: + rules: + - http: + paths: + - path: + backend: + serviceName: + servicePort: 80 + - backend: + serviceName: frontend + servicePort: 80 + ``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..2a052970e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,48 @@ +site_name: Application Gateway Ingress Controller +repo_name: "Azure/application-gateway-kubernetes-ingress" +repo_url: "https://github.com/Azure/application-gateway-kubernetes-ingress" + +theme: + name: readthedocs + highlightjs: true + hljs_languages: + - yaml + - rust + - bash + - go + shortcuts: + help: 191 # ? + next: 78 # n + previous: 80 # p + search: 83 # s + +plugins: + - search + - awesome-pages: + filename: .index + collapse_single_pages: true + - exclude: + glob: + - examples/guestbooks/* + - examples/sample-app/* + +extra_css: + - css/extra.css + +markdown_extensions: + - pymdownx.arithmatex + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:pymdownx.emoji.to_svg + - pymdownx.inlinehilite + - pymdownx.magiclink + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde