Document how to use external-ip (#769)

voyagermesh · Dec 20, 2017 · 60b1ec0 · 60b1ec0
1 parent c5bb13c
commit 60b1ec0
Showing 1 changed file with 57 additions and 11 deletions.
diff --git a/docs/guides/ingress/http/external-svc.md b/docs/guides/ingress/http/external-svc.md
@@ -9,14 +9,60 @@ menu_name: product_voyager_5.0.0-rc.7
 section_menu_id: guides
 ---
 
+# Using External Service as Ingress Backend
 
-Voyager supports `ExternalName` type services via dns resolution or http redirect.
+You can use an external service as a Backend for Kubernetes Ingress. There are 2 options depending on whether the external service has an external IP or DNS record.
 
-## DNS Resolution
-Voyager can forward traffic in both HTTP and TCP mode to the named domain in the external name
-service by resolving dns. For static resolution of DNS address at the HAProxy config is parsed,
-only use the `ingress.appscode.com/use-dns-resolver: "true"` on respective service. To periodically resolve
-dns, [DNS resolvers](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#5.3) must be configured using annotations on the service name.
+## Using External IP
+
+You can introduce any [external IP address as a Kubernetes service](https://github.com/kubernetes/kubernetes/issues/8631#issuecomment-104404768) by creating a matching Service and Endpoint object. Then you can use this service as a backend for your Ingress rules.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: external-ip
+spec:
+  ports:
+  - name: app
+    port: 80
+    protocol: TCP
+    targetPort: 9855
+  clusterIP: None
+  type: ClusterIP
+---
+apiVersion: v1
+kind: Endpoints
+metadata:
+  name: external-ip
+subsets:
+- addresses:
+  # list all external ips for this service
+  - ip: 172.17.0.5
+  ports:
+  - name: app
+    port: 9855
+    protocol: TCP
+```
+
+Now, you can use this `external-ip` Service as a backend in your Ingress definition. For example:
+
+```yaml
+apiVersion: voyager.appscode.com/v1beta1
+kind: Ingress
+metadata:
+  name: test-ings-rhvulnlb
+  namespace: test-x
+spec:
+  backend:
+    serviceName: external-ip
+    servicePort: "80"
+```
+
+
+## Using External Domain
+
+You can introduce an external service into a Kubernetes cluster by creating a [`ExternalName`](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types) type service. Voyager can forward traffic in both HTTP and TCP mode to the named domain in the `ExternalName` service by resolving dns. For static resolution of DNS record when HAProxy config is parsed, only use the `ingress.appscode.com/use-dns-resolver: "true"` annotation on the respective service. To periodically resolve dns, [DNS resolvers](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#5.3) must be configured using annotations on the service name.
 
 |  Keys  |   Value  |  Default |  Description |
 |--------|-----------|----------|-------------|
@@ -57,7 +103,7 @@ spec:
     servicePort: "80"
 ```
 
-## HTTP Redirect
+### HTTP Redirect
 If `ingress.appscode.com/use-dns-resolver` annotation is set to false or missing on a `ExternalName` type service,
 Voyager resolves L7 ingress in the following ways.
 
@@ -72,7 +118,7 @@ spec:
   type: ExternalName
 ```
 
-### Default redirect
+#### Default redirect
 If No BackendRules are configured for the endpoint, Voyager will configure HAProxy to redirect traffic to provided domain and port.
 The redirect code will be 301 (permanent redirect). Scheme (http or https) used by endpoint is preserved on redirect.
 ```
@@ -86,9 +132,8 @@ The generated redirect line in HAProxy config:
 http-request redirect location http[s]://{{e.ExternalName}}:{{ e.Port }} code 301
 ```
 
-### Backend Rule
-If Backendrules are configured, Voyager will not auto generate any redirect rule. This allows users to use full spectrum of HTTP redirection options available
-in HAProxy. To learn about these option, consult [HAProxy documentation](https://www.haproxy.com/doc/aloha/7.0/haproxy/http_redirection.html#redirection-examples).
+#### Backend Rule
+If Backendrules are configured, Voyager will not auto generate any redirect rule. This allows users to use full spectrum of HTTP redirection options available in HAProxy. To learn about these option, consult [HAProxy documentation](https://www.haproxy.com/doc/aloha/7.0/haproxy/http_redirection.html#redirection-examples).
 
 ```
 backend:
@@ -97,3 +142,4 @@ backend:
   serviceName: external-svc-non-dns
   servicePort: "80"
 ```
+