From f3e811bb45bf63ec19160e507e5a471e3103ba30 Mon Sep 17 00:00:00 2001
From: Avinash Sridharan <avinash.sridharan@microsoft.com>
Date: Sat, 16 Feb 2019 23:22:47 -0800
Subject: [PATCH] Added documentation for the backend-path-prefix annotation.

---
 README.md           |  3 +++
 docs/annotations.md | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 docs/annotations.md

diff --git a/README.md b/README.md
index a8065efe9..868fd2aa7 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,9 @@ The Application Gateway Ingress Controller allows the [Azure Application Gateway
 ## Usage
 Refer to the [tutorials](docs/tutorial.md) to understand how you can expose an AKS service over HTTP or HTTPS, to the internet, using an Azure Application Gateway.
 
+## Annotations
+The Kubernetes Ingress specification does not allow all features of Application Gateway to be exposed through the ingress resource. Therefore we have introduced application gateway ingress controller specific annotations to expose application gateway features through an ingress resource. Please refer to the [annotations](docs/annotations.md) to understand the various annotations supported by the ingress controller, and the corresponding features that can be turned on in the application gateway for a given annotation.
+
 ## 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.
diff --git a/docs/annotations.md b/docs/annotations.md
new file mode 100644
index 000000000..320744ee5
--- /dev/null
+++ b/docs/annotations.md
@@ -0,0 +1,37 @@
+# Table of Contents
+- [Introduction](#introduction)
+- [Backend path prefix](#backend-path-prefix)
+
+## Introduction
+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.
+
+## Bakend 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
+piVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: go-server-ingress-bkprefix
+  namespace: test-ag
+  annotations:
+    kubernetes.io/ingress.class: azure/application-gateway
+    appgw.ingress.kubernetes.io/backend-path-prefix: "/test/"
+spec:
+  rules:
+  - http:
+      paths:
+      - path: /hello/
+        backend:
+          serviceName: go-server-service
+          servicePort: 80
+```
+In the example above we have defined an ingress resource named `go-server-ingress-bkprefix` with an annotation `appgw.ingress.kubernetes.io/backend-path-prefix: "/test/"` . The annotation tells application gateway to create an HTTP setting which will have a path prefix override for the path `/hello` to `/test/`. 
+
+***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. 
\ No newline at end of file