Open vSwitch¶
This page is the starting point for Open vSwitch, the openvswitch role: the containers openvswitch_db and
openvswitch_vswitchd, on the compute and network nodes of the example inventory (inventory/multinode:105-108),
selected by the tag openvswitch. The play runs only while enable_ovs_dpdk is no; ovs-dpdk has its own play and
tag (site.yml:611-639). The risk register item on an openvswitch_vswitchd restart or recreate is
R7. The lists below say where the study covers how to operate it, its impact, its
dependencies and the evidence, what to check around a run and what stays open; the service card follows them.
Note
Key answers
- Bridges and ports, changed in 2024.1: the external bridges and their ports are set by the
openvswitch_bridge(fail_mode: standalone) andopenvswitch_portmodules run insidekolla_toolbox, no longer by the image scriptkolla_ensure_openvswitch_configured; neither task notifies a handler (roles/openvswitch/tasks/post-config.yml:25-53) CODE (Before and after a run). - New
hostnamekey, changed in 2024.1: post-config also writesexternal_ids:hostnamefromansible_facts.fqdn, and a change of it, like one ofsystem-idorhw-offload, notifiesRestart openvswitch-vswitchd container(post-config.yml:3-23,roles/openvswitch/defaults/main.yml:106) CODE. Whether the first 2024.1 run reports it changed, and so restartsopenvswitch_vswitchd, is NOT AVAILABLE. conf.dbconversion at start, new in the 2024.1 image: theopenvswitch-db-serverimage convertsconf.dbwhenovsdb-tool needs-conversionsays yes, before the Kolla-Ansible start script repeats the same test (kolladocker/openvswitch/openvswitch-db-server/extend_start.sh:8-10,roles/openvswitch/templates/start-ovsdb-server.j2:5-7) CODE.- Restart semantics still hold: same handlers in the same order, now through
kolla_container(roles/openvswitch/handlers/main.yml:1-44); the play hasserial: kolla_serial, default0(site.yml:616) CODE. What a restart does to VM traffic is NOT AVAILABLE.
Where to look¶
Operate¶
- Scenario: Reconfigure Neutron §4 (row "Open vSwitch"), Update container images §4 (OVS image change)
- Command: Reconfigure Neutron §1.1
- Command quick lookup by tag, row
-t openvswitch reconfigure: hosts touched with the default inventory: network and all computes (theopenvswitchgroup,inventory/multinode:105-108); can restartopenvswitch_dbandopenvswitch_vswitchdwhen the check detects drift, andopenvswitch_vswitchdwhen post-config reports a change (roles/openvswitch/tasks/check-containers.yml:2-18,post-config.yml:22-23) CODE.
Impact and risk¶
Dependencies¶
- Dependencies: Component dependencies §2, Component dependencies §4
Evidence¶
- Fact sheet: – (
ovs-dpdk: fact sheet A §6) - Image side: Kolla images §5 (rows
openvswitch-*), Kolla images §2.5 - Also: handlers: Tags §5; the container module: Repository architecture §6
Before and after a run¶
- The order inside the role still holds: config-host, config, check-containers, a flush of the handlers, then
post-config (
roles/openvswitch/tasks/deploy.yml:2-11);reconfigureimports that file (reconfigure.yml:2) andupgradelists the same five steps itself (upgrade.yml:2-11) CODE. The handlers are, in this order,Restart openvswitch-db-server container(which notifiesWaiting for openvswitch_db service to be ready, anovs-vsctl --no-wait showretried 30 times with a 2 s delay) andRestart openvswitch-vswitchd container, bothrecreate_or_restart_containerand both skipped whenkolla_actionisconfig(roles/openvswitch/handlers/main.yml:2-44) CODE. A db restart does not notify the vswitchd handler (:16-17). - Post-config runs after the flush (
deploy.yml:8-11), so a change it reports notifiesRestart openvswitch-vswitchd containeragain, and that restart runs at the end of the play CODE:- Changed in 2024.1: the first task, renamed
Set system-id, hostname and hw-offload, sets three keys through theopenvswitch_dbmodule inkolla_toolbox:external_ids:system-id(openvswitch_system_id, defaultansible_facts.hostname), the newexternal_ids:hostname(openvswitch_hostname, defaultansible_facts.fqdn) andother_config:hw-offload(present or absent fromopenvswitch_hw_offload), on the hosts that runopenvswitch_vswitchd(post-config.yml:3-23,roles/openvswitch/defaults/main.yml:105-107) CODE. 2023.1 wrote onlysystem-idandhw-offload. Whether the module reports changed when it adds the new key, or ok when a value is already set, is NOT AVAILABLE: its code is not in the studied sources (the kolla-toolbox image installs theopenvswitch.openvswitchcollection,<3, kolladocker/kolla-toolbox/requirements.yml:13-14). Nothing in the start scripts setshostname(roles/openvswitch/templates/start-ovsdb-server.j2:1-11). - Changed in 2024.1:
Ensuring OVS bridge is properly setupruns theopenvswitch_bridgemodule withfail_mode: standalonefor each name ofneutron_bridge_name, and the newEnsuring OVS ports are properly setupruns theopenvswitch_portmodule for each bridge and interface pair ofneutron_bridge_nameandneutron_external_interface, both throughkolla_toolbox, on network hosts and on computes whencomputes_need_external_bridge(post-config.yml:25-53) CODE. Neither task has anotify. 2023.1 randocker exec openvswitch_db kolla_ensure_openvswitch_configured, a script that fails when the interface does not exist (kolladocker/openvswitch/openvswitch-db-server/ovs_ensure_configured.sh:7-10); the image still ships it (Dockerfile.j2:8), but no task ofansible/calls it any more (grep). Whether the modules fail on a missing interface, and what settingfail_modedoes to an existing bridge, is NOT AVAILABLE.
- Changed in 2024.1: the first task, renamed
- Image changes and upgrade: an OVS image change makes
Check openvswitch containersreport drift on everyopenvswitchhost of the batch, and the handlers recreate the containers there; with the defaultkolla_serialof0the batch is the whole group (check-containers.yml:2-18,site.yml:611-624) CODE.kolla-ansible upgradeandreconfigurepassANSIBLE_SERIALaskolla_serial(tools/kolla-ansible:296, :522, :531), soANSIBLE_SERIAL=<n> kolla-ansible -t openvswitch upgrade, or--limitbatches, bound how many hosts are recreated in one batch CODE. Whether VM networking is interrupted on every compute at the same time is NOT AVAILABLE (Update container images §4, R7). - First 2024.1 check after an upgrade from 2023.1: the check compares the systemd unit too, and its text changed,
so an
openvswitch_dboropenvswitch_vswitchdwhose unit 2023.1 wrote, and that no 2024.1 run has recreated or restarted yet, is restarted by the first 2024.1 check (F16) CODE. - conf.db at start, new in the 2024.1 image:
kolla_startsources the image's extend_start chain before it runs the command (kolladocker/base/start.sh:18-24). Inopenvswitch-db-serverthat chain createsconf.dbif absent, then runsovsdb-tool convertwhenovsdb-tool needs-conversionanswersyes(kolladocker/openvswitch/openvswitch-base/extend_start.sh:12,docker/openvswitch/openvswitch-db-server/Dockerfile.j2:9,extend_start.sh:3-10). Kolla-Ansible'sstart-ovsdb-server, unchanged, repeats the test before it runsovsdb-server(roles/openvswitch/templates/start-ovsdb-server.j2:5-11; commandstart-ovsdb-server 127.0.0.1,openvswitch-db-server.json.j2:2) CODE. What a failed conversion does to the start is NOT AVAILABLE. - Log ownership, new in the 2024.1 image: every OVS container start runs
chown -R openvswitch:openvswitch /var/log/kolla/openvswitch(kolladocker/openvswitch/openvswitch-base/extend_start.sh:10), and the db and vswitchd images create their log file owned byopenvswitch(openvswitch-db-server/extend_start.sh:12-15,openvswitch-vswitchd/extend_start.sh:3-6) CODE. kolla marks theopenvswitchuser "unused" (kolla/common/users.py:280-283); whether the image has that user is NOT AVAILABLE (Kolla images §5, rowopenvswitch-base). - Podman only, new in 2024.1: config-host creates
/run/openvswitchon the host whenkolla_container_engineispodman(roles/openvswitch/tasks/config-host.yml:12-20); the optionalovs-vsctlhost wrapper (openvswitch_ovs_vsctl_wrapper_enabled, defaultfalse) now execs throughkolla_container_engine(roles/openvswitch/templates/ovs-vsctl.j2:3,tasks/config.yml:56-67,defaults/main.yml:99) CODE. - Tags §3.1, row
openvswitch: safe on its own "yes if unchanged"; prerequisite: theopenvswitchkernel module, loaded and persisted by config-host (config-host.yml:2-7) CODE. - Reconfigure a single service
§3:
openvswitchis one of the tags that can restart the containers that Tags §3.1 traces to running VMs CODE; what those restarts do to running VMs is NOT AVAILABLE.
Known limits and open points¶
- Known bugs and limitations, row
openvswitch: post-config restartsopenvswitch_vswitchdwhen theopenvswitch_dbmodule reports changed, now for three keys (roles/openvswitch/tasks/post-config.yml:3-23) CODE. Whether it reports changed on an unchanged host: NOT AVAILABLE. - Known bugs and limitations, row
ovs-dpdk:pullimportsservice-images-pull, which readsovsdpdk_servicesthroughkolla_role_name: "ovsdpdk"(roles/ovs-dpdk/tasks/pull.yml:2-3,vars/main.yml:4,roles/service-images-pull/tasks/main.yml:14); the NIC mapping file is still written once (gen_configonly if the file is absent,roles/ovs-dpdk/files/ovs-dpdkctl.sh:350-353). Changed in 2024.1: the notify is now spelledWait for dpdk tunnel ip, like the handler (roles/ovs-dpdk/handlers/main.yml:21, :88), so a restart ofovsdpdk_dbreaches it; the handler still has no port (:88-92), and ansible-core 2.16.20wait_forwith neitherportnorpathsleeps for the wholetimeout, here 300 s (modules/wait_for.py:541-542) CODE. See fact sheet A §6. - Q3: "Data-plane loss during an
openvswitch_vswitchdrestart or recreate". Status: NOT AVAILABLE. - What is not known, row "
openvswitch_vswitchdrestart or recreate": the sources do not establish whether the OpenFlow tables are lost, whether the OVS agent orovn-controllerreprograms them, and whether all VM traffic on the host is interrupted, and for how long. Same table: whether VM network traffic stops underkolla-ansible stop. - What is not known:
whether services started by a shell wrapper that does not
execthem receive SIGTERM before the container stops is NOT AVAILABLE;start-ovsrunsovs-vswitchdandstart-ovsdb-serverrunsovsdb-serverwithoutexec(roles/openvswitch/templates/start-ovs.j2:2,start-ovsdb-server.j2:11) CODE. The image's newovs_wrapper, which traps TERM and QUIT, is not used by any Kolla-Ansible template (kolladocker/openvswitch/openvswitch-base/ovs_wrapper.sh:3-19,Dockerfile.j2:36; grep ofansible/) (Kolla images §2.6). - Q14, answered from the source CODE: the OVS images have no one-shot
branch (no
KOLLA_BOOTSTRAP/KOLLA_UPGRADEin kolladocker/openvswitch/*, grep). - F13, "The Nova deploy order" still puts nova-compute before OVS and the Neutron
agents on new computes (
site.yml:609importsnova.ymlbefore the openvswitch play at:611) CODE; NOT AVAILABLE whether instances can be scheduled on such a compute before the later plays finish. - fact sheet A §6.8, "Operationally notable" for
the
ovs-dpdkrole (no fact sheet coversopenvswitch): a restart ofovsdpdk_dbnotifies, among others,Restart ovsdpdk-vswitchd container(roles/ovs-dpdk/handlers/main.yml:16-22) CODE. - Kolla images §6, item 13: an
openvswitch_vswitchdrestart replaces only the userspace daemon; the kernel module stays loaded andconf.db, on theopenvswitch_dbvolume, keeps bridges and ports (roles/openvswitch/defaults/main.yml:86) CODE. NOT AVAILABLE Whether the OpenFlow tables are lost and must be reprogrammed by the OVS agent orovn-controller.
Service card¶
The rows of the card are explained in How to read a service card.
| Item | Value |
|---|---|
| Play | site.yml:611 |
| Tags | openvswitch |
| Play host patterns | openvswitch |
| Node types in play (example inventory) | compute, network |
| Node types running its containers | compute, network |
| Containers | openvswitch_db, openvswitch_vswitchd |
deploy/reconfigure flow (tasks/) |
config-host → config → check-containers → flush handlers → post-config |
| Task files | check-containers.yml, check.yml, config-host.yml, config.yml, config_validate.yml, deploy-containers.yml, deploy.yml, main.yml, post-config.yml, precheck.yml, pull.yml, reconfigure.yml, stop.yml, upgrade.yml |
| Templates | openvswitch-db-server.json.j2, openvswitch-vswitchd.json.j2, ovs-vsctl.j2, start-ovs.j2, start-ovsdb-server.j2 |
| Handlers (definition order) | Restart openvswitch-db-server container; Waiting for openvswitch_db service to be ready; Restart openvswitch-vswitchd container |
| Key variables | enable_openvswitch, neutron_bridge_name, neutron_external_interface, computes_need_external_bridge |
| Role dependencies | none |
Related¶
- Reconfigure Neutron —
-t neutrondoes not touch Open vSwitch, which has a separate play and tag - Update container images — what an OVS image change recreates, and how to batch it
- Component dependencies §4 —
openvswitch_dbandopenvswitch_vswitchdforward all VM traffic - Neutron —
neutron_openvswitch_agentprograms the OVS flows - OVN —
ovn_controllerprograms OVS from the SB DB - Components — the other component pages