Assigning Unique External IPs for Ingress Traffic

_topic_map.yml

@@ -475,6 +475,8 @@ Topics:
   - Name: Overcommitting
     File: overcommit
     Distros: openshift-origin,openshift-enterprise
+  - Name: Assigning Unique External IPs for Ingress Traffic  
+    File: tcp_ingress_external_ports
   - Name: Monitoring Routers
     File: router
     Distros: openshift-origin,openshift-enterprise

admin_guide/tcp_ingress_external_ports.adoc

@@ -0,0 +1,123 @@
+[[admin-guide-unique-external-ips-ingress-traffic]]
+= Assigning Unique External IPs for Ingress Traffic
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+
+toc::[]
+
+== Overview
+
+Cluster administrators can assign a unique external IP address to a service. If
+routed correctly, external traffic can reach that service's endpoints via any
+TCP/UDP port the service exposes. This can be simpler than having to manage the
+port space of a limited number of shared IP addresses when manually assigning
+external IPs to services.
+
+There is support for both automatic and manual assignment of IP addresses, and
+each address is guaranteed to be assigned to a maximum of one service. This
+ensures that each service can simply expose its chosen ports regardless of the
+ports exposed by other services.
+
+[[unique-external-ips-ingress-traffic-restrictions]]
+== Restrictions
+
+To use an `*ExternalIP*`, you can:
+
+- Select an IP address from the `*ExternalIPNetworkCIDRs*` range.
+- Have an IP address assigned from a pool. In this case, {product-title} implements a non-cloud version of the LoadBalancer service type and assigns IP addresses to the services.
++
+[CAUTION]
+====
+You must ensure that the IP address pool you assign terminates at one or more
+nodes in your cluster. You can use the existing
+xref:../admin_guide/high_availability.adoc#configuring-ip-failover[`*oadm ipfailover*`] to ensure that the external IPs are highly available.
+====
+
+For manually-configured external IPs, potential port clashes are handled on a
+first-come, first-served basis. If you request a port, it is only available if
+it has not yet been assigned for that IP address. For example:
+
+.Port clash example for manually-configured external IPs
+====
+Two services have been manually configured with the same external
+IP address of 172.7.7.7.
+
+`MongoDB service A` requests port 27017, and then
+`MongoDB service B` requests the same port; the first request gets the port. 
+====
+
+However, port clashes are not an issue for external IPs assigned by the ingress
+controller, because the controller assigns each service a unique address.
+
+[NOTE]
+====
+Ingress IPs can only be assigned if the cluster is not running in the cloud. In
+cloud environments, LoadBalancer-type services configure cloud-specific load
+balancers.
+====
+
+[[unique-external-ips-ingress-traffic-configure-cluster]]
+== Configuring the Cluster to Use Unique External IPs
+
+In non-cloud clusters, `ingressIPNetworkCIDR` is set by default to `172.46.0.0/16`. You could use the default if your cluster environment is not already using this private range. However, if you want to use a different range, then before you assign an ingress IP you must set xref:../install_config/master_node_configuration.adoc#master-node-config-network-config[`ingressIPNetworkCIDR`]
+in the *_/etc/origin/master-config.yaml_* file, then restart the master service.
+
+[[unique-external-ips-ingress-traffic-configure-service]]
+== Configuring an Ingress IP for a Service
+
+To assign an ingress IP:
+
+. Create a YAML file for a LoadBalancer service that requests a specific IP via the `*loadBalancerIP*` setting:
++
+.Sample LoadBalancer Configuration
+====
+----
+apiVersion: v1
+kind: Service
+metadata:
+  name: egress-1
+spec: 
+  ports:
+  - name: db
+    port: 3306
+  loadBalancerIP: 172.46.0.1
+  type: LoadBalancer
+  selector:
+    name: my-db-selector
+----
+====
+. Create a LoadBalancer service on your pod:
++
+----
+$ oc create -f loadbalancer.yaml
+----
+. Check the service for an external IP. For example, for a service named `myservice`:
++
+----
+$ oc get svc myservice
+----
++
+When your LoadBalancer-type service has an external IP assigned, the output
+displays the IP:
++
+----
+NAME         CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+myservice    172.30.74.106   172.46.0.1    80/TCP    30s
+----
+
+[[unique-external-ips-ingress-traffic-routing-cidr]]
+== Routing the Ingress CIDR for Development or Testing
+
+Add a static route directing traffic for the ingress CIDR to a node in the
+cluster. For example:
+
+----
+# route add -net 172.46.0.0/16 gw 10.66.140.17 eth0
+----
+
+In the example above, `172.46.0.0/16` is the `*ingressIPNetworkCIDR*`, and `10.66.140.17` is the node IP.