:_mod-docs-content-type: ASSEMBLY
[id="configuring-ipfailover"]
= Configuring IP failover
include::_attributes/common-attributes.adoc[]
:context: configuring-ipfailover

toc::[]

[role="_abstract"]
To provide high availability for Virtual IP addresses and ensure services remain accessible when nodes fail in {product-title}, you can configure IP failover using Keepalived.

IP failover uses link:http://www.keepalived.org/[Keepalived] to host a set of externally accessible Virtual IP (VIP) addresses on a set of hosts. Each VIP address is only serviced by a single host at a time. Keepalived uses the Virtual Router Redundancy Protocol (VRRP) to determine which host, from the set of hosts, services which VIP. If a host becomes unavailable, or if the service that Keepalived is watching does not respond, the VIP is switched to another host from the set. This means a VIP is always serviced as long as a host is available.

Every VIP in the set is serviced by a node selected from the set. If a single node is available, the VIPs are served. There is no way to explicitly distribute the VIPs over the nodes, so there can be nodes with no VIPs and other nodes with many VIPs. If there is only one node, all VIPs are on it.

The administrator must ensure that all of the VIP addresses meet the following requirements:

* Accessible on the configured hosts from outside the cluster.
* Not used for any other purpose within the cluster.

Keepalived on each node determines whether the needed service is running. If it is, VIPs are supported and Keepalived participates in the negotiation to determine which node serves the VIP. For a node to participate, the service must be listening on the watch port on a VIP or the check must be disabled.

[NOTE]
====
Each VIP in the set might be served by a different node.
====

IP failover monitors a port on each VIP to determine whether the port is reachable on the node. If the port is not reachable, the VIP is not assigned to the node. If the port is set to `0`, this check is suppressed. The check script does the needed testing.

When a node running Keepalived passes the check script, the VIP on that node can enter the `master` state based on its priority and the priority of the current master and as determined by the preemption strategy.

A cluster administrator can provide a script through the `OPENSHIFT_HA_NOTIFY_SCRIPT` variable, and this script is called whenever the state of the VIP on the node changes. Keepalived uses the `master` state when it is servicing the VIP, the `backup` state when another node is servicing the VIP, or in the `fault` state when the check script fails. The notify script is called with the new state whenever the state changes.

You can create an IP failover deployment configuration on {product-title}. The IP failover deployment configuration specifies the set of VIP addresses, and the set of nodes on which to service them. A cluster can have multiple IP failover deployment configurations, with each managing its own set of unique VIP addresses. Each node in the IP failover configuration runs an IP failover pod, and this pod runs Keepalived.

When using VIPs to access a pod with host networking, the application pod runs on all nodes that are running the IP failover pods. This enables any of the IP failover nodes to become the master and service the VIPs when needed. If application pods are not running on all nodes with IP failover, either some IP failover nodes never service the VIPs or some application pods never receive any traffic. Use the same selector and replication count, for both IP failover and the application pods, to avoid this mismatch.

While using VIPs to access a service, any of the nodes can be in the IP failover set of nodes, since the service is reachable on all nodes, no matter where the application pod is running. Any of the IP failover nodes can become master at any time. The service can either use external IPs and a service port or it can use a `NodePort`. Setting up a `NodePort` is a privileged operation.

When using external IPs in the service definition, the VIPs are set to the external IPs, and the IP failover monitoring port is set to the service port. When using a node port, the port is open on every node in the cluster, and the service load-balances traffic from whatever node currently services the VIP. In this case, the IP failover monitoring port is set to the `NodePort` in the service definition.

[IMPORTANT]
====
Even though a service VIP is highly available, performance can still be affected. Keepalived makes sure that each of the VIPs is serviced by some node in the configuration, and several VIPs can end up on the same node even when other nodes have none. Strategies that externally load-balance across a set of VIPs can be thwarted when IP failover puts multiple VIPs on the same node.
====

When you use `ExternalIP`, you can set up IP failover to have the same VIP range as the `ExternalIP` range. You can also disable the monitoring port. In this case, all of the VIPs appear on same node in the cluster. Any user can set up a service with an `ExternalIP` and make it highly available.

[IMPORTANT]
====
There are a maximum of 254 VIPs in the cluster.
====

include::modules/nw-ipfailover-environment-variables.adoc[leveloffset=+1]

include::modules/nw-ipfailover-configuration.adoc[leveloffset=+1]

include::modules/nw-ipfailover-configuring-check-notify-scripts.adoc[leveloffset=+1]

include::modules/nw-ipfailover-configuring-vrrp-preemption.adoc[leveloffset=+1]

//Omitted the following procedure for now. We can update it to use `oc debug` if needed.
//include::modules/nw-ipfailover-configuring-keepalived-multicast.adoc[leveloffset=+1]

include::modules/nw-ipfailover-vrrp-ip-offset.adoc[leveloffset=+1]

include::modules/nw-ipfailover-configuring-more-than-254.adoc[leveloffset=+1]

include::modules/nw-ipfailover-cluster-ha-ingress.adoc[leveloffset=+1]

[role="_additional-resources"]
.Additional resources
* xref:../../networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-externalip.adoc#configuration-externalip_configuring-externalip[Configuration for ExternalIP]

* link:https://kubernetes.io/docs/concepts/services-networking/service/#external-ips[Kubernetes documentation on ExternalIP]

include::modules/nw-ipfailover-remove.adoc[leveloffset=+1]

//[role="_additional-resources"]
//== Additional resources
//TCP connection
