diff --git a/doc/networking-guide/source/figures/demo_multiple_dhcp_agents.png b/doc/networking-guide/source/figures/demo_multiple_dhcp_agents.png new file mode 100644 index 0000000000..3867039563 Binary files /dev/null and b/doc/networking-guide/source/figures/demo_multiple_dhcp_agents.png differ diff --git a/doc/networking-guide/source/misc-add-ha-for-dhcp.rst b/doc/networking-guide/source/misc-add-ha-for-dhcp.rst index 266deb1338..2b96326bc5 100644 --- a/doc/networking-guide/source/misc-add-ha-for-dhcp.rst +++ b/doc/networking-guide/source/misc-add-ha-for-dhcp.rst @@ -2,9 +2,486 @@ Adding high availability for DHCP ================================= -FIXME (Simple note, needs to be added.) -DHCP agents -~~~~~~~~~~~ +This section describes how to use the agent management (alias agent) and +scheduler (alias agent_scheduler) extensions for DHCP agents +scalability and HA. -FIXME: Content needs to be written; see DHCP agents (http://docs.openstack.org/admin-guide/networking_multi-dhcp-agents.html) +.. note:: + + Use the :command:`neutron ext-list` client command to check if these + extensions are enabled: + + .. code-block:: console + + $ neutron ext-list -c name -c alias + +-----------------+--------------------------+ + | alias | name | + +-----------------+--------------------------+ + | agent_scheduler | Agent Schedulers | + | binding | Port Binding | + | quotas | Quota management support | + | agent | agent | + | provider | Provider Network | + | router | Neutron L3 Router | + | lbaas | Load Balancing service | + | extraroute | Neutron Extra Route | + +-----------------+--------------------------+ + +.. figure:: figures/demo_multiple_dhcp_agents.png + +There will be three hosts in the setup. + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Host + - Description + * - OpenStack controller host - controlnod + - Runs the Networking, Identity, and Compute services that are required + to deploy VMs. The node must have at least one network interface that + is connected to the Management Network. Note that ``nova-network`` should + not be running because it is replaced by Neutron. + * - HostA + - Runs ``nova-compute``, the Neutron L2 agent and DHCP agent + * - HostB + - Same as HostA + +**Hosts for demo** + +Configuration +~~~~~~~~~~~~~ + +**controlnode: neutron server** + +#. Neutron configuration file ``/etc/neutron/neutron.conf``: + + .. code-block:: ini + + [DEFAULT] + core_plugin = linuxbridge + rabbit_host = controlnode + allow_overlapping_ips = True + host = controlnode + agent_down_time = 5 + +#. Update the plug-in configuration file + ``/etc/neutron/plugins/linuxbridge/linuxbridge_conf.ini``: + + .. code-block:: ini + + [vlans] + tenant_network_type = vlan + network_vlan_ranges = physnet1:1000:2999 + [database] + connection = mysql://root:root@127.0.0.1:3306/neutron_linux_bridge + retry_interval = 2 + [linux_bridge] + physical_interface_mappings = physnet1:eth0 + +**HostA and HostB: L2 agent** + +#. Neutron configuration file ``/etc/neutron/neutron.conf``: + + .. code-block:: ini + + [DEFAULT] + rabbit_host = controlnode + rabbit_password = openstack + # host = HostB on hostb + host = HostA + +#. Update the plug-in configuration file + ``/etc/neutron/plugins/linuxbridge/linuxbridge_conf.ini``: + + .. code-block:: ini + + [vlans] + tenant_network_type = vlan + network_vlan_ranges = physnet1:1000:2999 + [database] + connection = mysql://root:root@127.0.0.1:3306/neutron_linux_bridge + retry_interval = 2 + [linux_bridge] + physical_interface_mappings = physnet1:eth0 + +#. Update the nova configuration file ``/etc/nova/nova.conf``: + + .. code-block:: ini + + [DEFAULT] + use_neutron=True + firewall_driver=nova.virt.firewall.NoopFirewallDriver + + [neutron] + admin_username=neutron + admin_password=servicepassword + admin_auth_url=http://controlnode:35357/v2.0/ + auth_strategy=keystone + admin_tenant_name=servicetenant + url=http://100.1.1.10:9696/ + +**HostA and HostB: DHCP agent** + +- Update the DHCP configuration file ``/etc/neutron/dhcp_agent.ini``: + + .. code-block:: ini + + [DEFAULT] + interface_driver = neutron.agent.linux.interface.BridgeInterfaceDriver + +Commands in agent management and scheduler extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following commands require the tenant running the command to have an +admin role. + +.. note:: + + Ensure that the following environment variables are set. These are + used by the various clients to access the Identity service. + + .. code-block:: bash + + export OS_USERNAME=admin + export OS_PASSWORD=adminpassword + export OS_TENANT_NAME=admin + export OS_AUTH_URL=http://controlnode:5000/v2.0/ + +**Settings** + +To experiment, you need VMs and a neutron network: + +.. code-block:: console + + $ nova list + + +-------------------------------------+----------+--------+--------------+ + | ID | Name | Status | Networks | + +-------------------------------------+----------+--------+--------------+ + | c394fcd0-0baa-43ae-a793-201815c3e8ce| myserver1| ACTIVE | net1=10.0.1.3| + | 2d604e05-9a6c-4ddb-9082-8a1fbdcc797d| myserver2| ACTIVE | net1=10.0.1.4| + | c7c0481c-3db8-4d7a-a948-60ce8211d585| myserver3| ACTIVE | net1=10.0.1.5| + +-------------------------------------+----------+--------+--------------+ + + $ neutron net-list + +-------------------------+------+--------------------------------------+ + | id | name | subnets | + +-------------------------+------+--------------------------------------+ + | 89dca1c6-c7d4-4f7a- | | | + | b730-549af0fb6e34 | net1 | f6c832e3-9968-46fd-8e45-d5cf646db9d1 | + +-------------------------+------+--------------------------------------+ + +**Manage agents in neutron deployment** + +Every agent that supports these extensions will register itself with the +neutron server when it starts up. + +#. List all agents: + + .. code-block:: console + + $ neutron agent-list + + +--------------------------------------+--------------------+-------+-------+----------------+ + | id | agent_type | host | alive | admin_state_up | + +--------------------------------------+--------------------+-------+-------+----------------+ + | 1b69828d-6a9b-4826-87cd-1757f0e27f31 | Linux bridge agent | HostA | :-) | True | + | a0c1c21c-d4f4-4577-9ec7-908f2d48622d | DHCP agent | HostA | :-) | True | + | ed96b856-ae0f-4d75-bb28-40a47ffd7695 | Linux bridge agent | HostB | :-) | True | + | f28aa126-6edb-4ea5-a81e-8850876bc0a8 | DHCP agent | HostB | :-) | True | + +--------------------------------------+--------------------+-------+-------+----------------+ + + The output shows information for four agents. The ``alive`` field shows + ``:-)`` if the agent reported its state within the period defined by the + ``agent_down_time`` option in the ``neutron.conf`` file. Otherwise the + ``alive`` is ``xxx``. + +#. List the DHCP agents that host a specified network: + + In some deployments, one DHCP agent is not enough to hold all network + data. In addition, you must have a backup for it even when the + deployment is small. The same network can be assigned to more than one + DHCP agent and one DHCP agent can host more than one network. + +#. List DHCP agents that host a specified network: + + .. code-block:: console + + $ neutron dhcp-agent-list-hosting-net net1 + + +--------------------------------------+-------+----------------+-------+ + | id | host | admin_state_up | alive | + +--------------------------------------+-------+----------------+-------+ + | a0c1c21c-d4f4-4577-9ec7-908f2d48622d | HostA | True | :-) | + +--------------------------------------+-------+----------------+-------+ + +#. List the networks hosted by a given DHCP agent: + + This command is to show which networks a given dhcp agent is managing. + + .. code-block:: console + + $ neutron net-list-on-dhcp-agent a0c1c21c-d4f4-4577-9ec7-908f2d48622d + + +------------------------+------+---------------------------------+ + | id | name | subnets | + +------------------------+------+---------------------------------+ + | 89dca1c6-c7d4-4f7a | | | + | -b730-549af0fb6e34 | net1 | f6c832e3-9968-46fd | + | | | -8e45-d5cf646db9d1 10.0.1.0/24 | + +------------------------+------+---------------------------------+ + +#. Show agent details. + + The :command:`agent-show` command shows details for a specified agent: + + .. code-block:: console + + $ neutron agent-show a0c1c21c-d4f4-4577-9ec7-908f2d48622d + + +--------------------+---------------------------------------------------+ + | Field | Value | + +--------------------+---------------------------------------------------+ + | admin_state_up | True | + | agent_type | DHCP agent | + | alive | False | + | binary | neutron-dhcp-agent | + | configurations |{ | + | | "subnets": 1, | + | | "dhcp_driver": "neutron.agent.linux.dhcp.Dnsmasq",| + | | "networks": 1, | + | | "dhcp_lease_time": 120, | + | | "ports": 3 | + | |} | + | created_at | 2013-03-16T01:16:18.000000 | + | description | | + | heartbeat_timestamp| 2013-03-17T01:37:22.000000 | + | host | HostA | + | id | 58f4ce07-6789-4bb3-aa42-ed3779db2b03 | + | started_at | 2013-03-16T06:48:39.000000 | + | topic | dhcp_agent | + +--------------------+---------------------------------------------------+ + + In this output, ``heartbeat_timestamp`` is the time on the neutron + server. You do not need to synchronize all agents to this time for this + extension to run correctly. ``configurations`` describes the static + configuration for the agent or run time data. This agent is a DHCP agent + and it hosts one network, one subnet, and three ports. + + Different types of agents show different details. The following output + shows information for a Linux bridge agent: + + .. code-block:: console + + $ neutron agent-show ed96b856-ae0f-4d75-bb28-40a47ffd7695 + + +---------------------+--------------------------------------+ + | Field | Value | + +---------------------+--------------------------------------+ + | admin_state_up | True | + | binary | neutron-linuxbridge-agent | + | configurations | { | + | | "physnet1": "eth0", | + | | "devices": "4" | + | | } | + | created_at | 2013-03-16T01:49:52.000000 | + | description | | + | disabled | False | + | group | agent | + | heartbeat_timestamp | 2013-03-16T01:59:45.000000 | + | host | HostB | + | id | ed96b856-ae0f-4d75-bb28-40a47ffd7695 | + | topic | N/A | + | started_at | 2013-03-16T06:48:39.000000 | + | type | Linux bridge agent | + +---------------------+--------------------------------------+ + + The output shows ``bridge-mapping`` and the number of virtual network + devices on this L2 agent. + +**Manage assignment of networks to DHCP agent** + +Now that you have run the :command:`net-list-on-dhcp-agent` and +:command:`dhcp-agent-list-hosting-net` commands, you can add a network to a +DHCP agent and remove one from it. + +#. Default scheduling. + + When you create a network with one port, you can schedule it to an + active DHCP agent. If many active DHCP agents are running, select one + randomly. You can design more sophisticated scheduling algorithms in the + same way as nova-schedule later on. + + .. code-block:: console + + $ neutron net-create net2 + $ neutron subnet-create net2 9.0.1.0/24 --name subnet2 + $ neutron port-create net2 + $ neutron dhcp-agent-list-hosting-net net2 + + +--------------------------------------+-------+----------------+-------+ + | id | host | admin_state_up | alive | + +--------------------------------------+-------+----------------+-------+ + | a0c1c21c-d4f4-4577-9ec7-908f2d48622d | HostA | True | :-) | + +--------------------------------------+-------+----------------+-------+ + + It is allocated to DHCP agent on HostA. If you want to validate the + behavior through the :command:`dnsmasq` command, you must create a subnet for + the network because the DHCP agent starts the dnsmasq service only if + there is a DHCP. + +#. Assign a network to a given DHCP agent. + + To add another DHCP agent to host the network, run this command: + + .. code-block:: console + + $ neutron dhcp-agent-network-add f28aa126-6edb-4ea5-a81e-8850876bc0a8 net2 + Added network net2 to dhcp agent + $ neutron dhcp-agent-list-hosting-net net2 + + +--------------------------------------+-------+----------------+-------+ + | id | host | admin_state_up | alive | + +--------------------------------------+-------+----------------+-------+ + | a0c1c21c-d4f4-4577-9ec7-908f2d48622d | HostA | True | :-) | + | f28aa126-6edb-4ea5-a81e-8850876bc0a8 | HostB | True | :-) | + +--------------------------------------+-------+----------------+-------+ + + Both DHCP agents host the ``net2`` network. + +#. Remove a network from a specified DHCP agent. + + This command is the sibling command for the previous one. Remove + ``net2`` from the DHCP agent for HostA: + + .. code-block:: console + + $ neutron dhcp-agent-network-remove a0c1c21c-d4f4-4577-9ec7-908f2d48622d \ + net2 + Removed network net2 to dhcp agent + $ neutron dhcp-agent-list-hosting-net net2 + + +--------------------------------------+-------+----------------+-------+ + | id | host | admin_state_up | alive | + +--------------------------------------+-------+----------------+-------+ + | f28aa126-6edb-4ea5-a81e-8850876bc0a8 | HostB | True | :-) | + +--------------------------------------+-------+----------------+-------+ + + You can see that only the DHCP agent for HostB is hosting the ``net2`` + network. + +**HA of DHCP agents** + +Boot a VM on net2. Let both DHCP agents host ``net2``. Fail the agents +in turn to see if the VM can still get the desired IP. + +#. Boot a VM on net2: + + .. code-block:: console + + $ neutron net-list + + +-------------------------+------+-----------------------------+ + | id | name | subnets | + +-------------------------+------+-----------------------------+ + | 89dca1c6-c7d4-4f7a- | | | + | b730-549af0fb6e34 | net1 | f6c832e3-9968-46fd-8e45 | + | | | -d5cf646db9d1 10.0.1.0/24 | + | 9b96b14f-71b8-4918-90aa-| | | + | c5d705606b1a | net2 | 6979b71a-0ae8-448c-aa87- | + | | | 65f68eedcaaa 9.0.1.0/24 | + +-------------------------+------+-----------------------------+ + + .. code-block:: console + + $ nova boot --image tty --flavor 1 myserver4 \ + --nic net-id=9b96b14f-71b8-4918-90aa-c5d705606b1a + + .. code-block:: console + + $ nova list + + +-------------------------------------+----------+-------+---------------+ + | ID | Name | Status| Networks | + +-------------------------------------+----------+-------+---------------+ + |c394fcd0-0baa-43ae-a793-201815c3e8ce |myserver1 |ACTIVE | net1=10.0.1.3 | + |2d604e05-9a6c-4ddb-9082-8a1fbdcc797d |myserver2 |ACTIVE | net1=10.0.1.4 | + |c7c0481c-3db8-4d7a-a948-60ce8211d585 |myserver3 |ACTIVE | net1=10.0.1.5 | + |f62f4731-5591-46b1-9d74-f0c901de567f |myserver4 |ACTIVE | net2=9.0.1.2 | + +-------------------------------------+----------+-------+---------------+ + +#. Make sure both DHCP agents hosting ``net2``: + + Use the previous commands to assign the network to agents. + + .. code-block:: console + + $ neutron dhcp-agent-list-hosting-net net2 + + +--------------------------------------+-------+----------------+-------+ + | id | host | admin_state_up | alive | + +--------------------------------------+-------+----------------+-------+ + | a0c1c21c-d4f4-4577-9ec7-908f2d48622d | HostA | True | :-) | + | f28aa126-6edb-4ea5-a81e-8850876bc0a8 | HostB | True | :-) | + +--------------------------------------+-------+----------------+-------+ + +**Test the HA** + +#. Log in to the ``myserver4`` VM, and run ``udhcpc``, ``dhclient`` or + other DHCP client. + +#. Stop the DHCP agent on HostA. Besides stopping the + ``neutron-dhcp-agent`` binary, you must stop the ``dnsmasq`` processes. + +#. Run a DHCP client in VM to see if it can get the wanted IP. + +#. Stop the DHCP agent on HostB too. + +#. Run ``udhcpc`` in the VM; it cannot get the wanted IP. + +#. Start DHCP agent on HostB. The VM gets the wanted IP again. + +**Disable and remove an agent** + +An administrator might want to disable an agent if a system hardware or +software upgrade is planned. Some agents that support scheduling also +support disabling and enabling agents, such as L3 and DHCP agents. After +the agent is disabled, the scheduler does not schedule new resources to +the agent. After the agent is disabled, you can safely remove the agent. +Remove the resources on the agent before you delete the agent. + +To run the following commands, you must stop the DHCP agent on HostA. + +.. code-block:: console + + $ neutron agent-update --admin-state-up False \ + a0c1c21c-d4f4-4577-9ec7-908f2d48622d + $ neutron agent-list + + +--------------------------------------+--------------------+-------+-------+----------------+ + | id | agent_type | host | alive | admin_state_up | + +--------------------------------------+--------------------+-------+-------+----------------+ + | 1b69828d-6a9b-4826-87cd-1757f0e27f31 | Linux bridge agent | HostA | :-) | True | + | a0c1c21c-d4f4-4577-9ec7-908f2d48622d | DHCP agent | HostA | :-) | False | + | ed96b856-ae0f-4d75-bb28-40a47ffd7695 | Linux bridge agent | HostB | :-) | True | + | f28aa126-6edb-4ea5-a81e-8850876bc0a8 | DHCP agent | HostB | :-) | True | + +--------------------------------------+--------------------+-------+-------+----------------+ + +.. code-block:: console + + $ neutron agent-delete a0c1c21c-d4f4-4577-9ec7-908f2d48622d + Deleted agent: a0c1c21c-d4f4-4577-9ec7-908f2d48622d + $ neutron agent-list + + +--------------------------------------+--------------------+-------+-------+----------------+ + | id | agent_type | host | alive | admin_state_up | + +--------------------------------------+--------------------+-------+-------+----------------+ + | 1b69828d-6a9b-4826-87cd-1757f0e27f31 | Linux bridge agent | HostA | :-) | True | + | ed96b856-ae0f-4d75-bb28-40a47ffd7695 | Linux bridge agent | HostB | :-) | True | + | f28aa126-6edb-4ea5-a81e-8850876bc0a8 | DHCP agent | HostB | :-) | True | + +--------------------------------------+--------------------+-------+-------+----------------+ + +After deletion, if you restart the DHCP agent, it appears on the agent +list again.