Leases and Reservations


When flannel starts up, it ensures that the host has a subnet lease. If there is an existing lease then it's used, otherwise one is assigned.

Leases can be viewed by checking the contents of etcd. e.g.

$ etcdctl ls /            
$ etcdctl -o extended get /
Key: /
Created-Index: 5
Modified-Index: 5
TTL: 85925
Index: 6


This shows that there is a single lease ( which will expire in 85925 seconds. flannel will attempt to renew the lease before it expires, but if flannel is not running for an extended period then the lease will be lost.

The "PublicIP" value is how flannel knows to reuse this lease when restarted. This means that if the public IP changes, then the flannel subnet will change too.

In case a host is unable to renew its lease before the lease expires (e.g. a host takes a long time to restart and the timing lines up with when the lease would normally be renewed), flannel will then attempt to renew the last lease that it has saved in its subnet config file (which, unless specified, is located at /var/run/flannel/subnet.env)

cat /var/run/flannel/subnet.env

In this case, if flannel fails to retrieve an existing lease from etcd, it will attempt to renew lease specified in FLANNEL_SUBNET ( It will only renew this lease if the subnet specified is valid for the current etcd network configuration otherwise it will allocate a new lease.


flannel also supports reservations for the subnet assigned to a host. Reservations allow a fixed subnet to be used for a given host.

The only difference between a lease and reservation is the etcd TTL value. Simply removing the TTL from a lease will convert it to a reservation. e.g.

etcdctl set -ttl 0 / $(etcdctl get /