Ubuntu Wiki

Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.

• Launchpad Entry: foundations-aa-migrating-to-netplan

• Packages affected: bridge-utils cloud-init juju maas netcfg nplan net-tools ifenslave ifupdown systemd vlan

Summary

Migrate default installs from ifupdown to netplan as a preferred method of describing network configuration for users, and leaving the implementation details to netplan itself. Make sure people can easily describe complex network configurations without worrying about the syntax required by the software that will implement the configuration.

Deprecate ifupdown and previous-generation networking tools in Ubuntu for the 17.10 release. Ambitiously target a unified network stack of netplan, networkd, network-manager, and iputils2 across all 17.10 images in preparation for the 18.04 LTS.

This plan includes the phasing out of outdated tools such as ifupdown and net-tools and the packages which are used as extensions to ifupdown and net-tools; in favor of the preferred, modern alternatives from iproute2: using the 'ip' command, for example.

Release Note

In this release, several networking tools have been modernized or replaced; the table below outlines the most common replacement for well-known commands:

Include table here; e.g ifconfig == ip address / bridgectl addif eth0 br0 == bridge link set ...

Rationale

Increased demand on being able to represent complex network configurations simply as well as some current limitations of ifupdown have lead to the implementation of netplan, which provides a simple configuration syntax and hides the details of syntax of the tools that will support and implement the configuration while still providing feedback on the feasibility of the requested configuration. With new issues such as potentially long network interface names which are not well supported by ifupdown, layered devices and telco requirements; it is time to overhaul the default network configuration tool on Ubuntu and netplan appears to be the perfect solution.

We've also been carrying old tools that have been deprecated upstream for a while. Some of them are unmaintained or not well maintained at all, and many alternatives already do exist. Furthermore, given increasing demand for complex networking scenarios (large cloud uses often require complex layering of different features, such as bridges over bonds over VLANs, etc.), it has shown to be important to improve in the ease of configuring the network.

Use Cases

• ACME wants to set up a new hyper-speed cloud for their clients, and need to configure VLANs on multiple bonded devices, bridged to the various networks. They can use netplan to easily define the network, and let netplan generate and apply the configuration to systemd-networkd or NetworkManager without having to worry about different syntaxes.

• John has been using brctl for a while to add interfaces for new virtual machines to his VM network; but wonders if there is a better way to do it.
• Mulan needs to list interfaces and their IPv4 and IPv6 addresses; she uses 'ip link' and 'ip addr' or 'ip -6 addr' to do so.

Implementation

This section should describe a plan of action to implement the changes discussed. The general summary is below, followed by some notes on specific changes that will be required. The summary includes a rough outline of the implementation plan.

Summary

Migration to netplan and phasing out of old network tools will happen in several phases, which may overlap:

• Phase I: Identify critical-path features for netplan, implement critical-path.
• Phase II: Identify all code change targets, prioritize and fix critical pieces (packages in main, infrastructure)
• Phase III: Implement migration tools for existing installs from ifupdown to an equivalent network YAML v2.
• Phase IV: Identify and implement missing features for MaaS and other specialist users.
• Phase V: Any cleanup, as necessary (package demotions, removals, etc.)

Phase I: Critical-path netplan features

To begin with, we'll need to identify those features we already know are abolutely required as a bare minimum to use netplan /instead of/ ifupdown on all systems.

These should be reviewed and agreed on between Foundations, Desktop and Server teams and carefully selected; it should be limited to critical-path features, not nice-to-haves coming from bias from using ifupdown. We should not aim to duplicate exactly what ifupdown did, but rather take the opportunity to improve on it.

Netplan should already be considered as relatively mature before the deadline; as it is already shipped on systems.

Possibly, provide an initial image without ifupdown for testing.

Also set up transition tracker for packages that are obviously affected by the migration efforts, and start scanning the archive / default installs for other users that may not be declaring a Depends/Recommends/Suggest on affected packages.

Phase II: Code change targets, fixing main and infrastructure

There are multiple packages depending on one of the affected packages selected for replacement: http://paste.ubuntu.com/24500232/:

These, where possible, will need to be modified to use the "newer tools"; iproute2, etc. Packages for which Canonical is upstream will need to be ported (or dropped if it makes sense to do so), and packages where the upstream is elsewhere will need to be checked. Upstreams should be contacted with proposed patches to support the right commands for future-proofing.

When necessary, implement autopkgtests for the affected packages to ensure previous behavior is maintained.

Testing should be ongoing from that point.

Phase III: Implement migration tooling

Old installs still using ifupdown need to be migrated to allow for upgrades from pre-17.10 to the next LTS. Validate the migration code (some is already available in netplan) to ensure the most common upgrade scenarios are supported. Make sure we can leave ifupdown behind and forcefully warn the user, or otherwise gracefully leave the system half-broken.

Go/no-go decision by then?

Phase IV: Specialist features

Identify and implement any "specialist" features. Identification should happen in parallel to the previous phases in collaboration with the MaaS, Juju teams and others; then proceed to implementing anything missing.

Phase V: Polish

Proceed with demotions, cleanups, last efforts for polish. At this point the migration and new implementations should be well tested and deemed stable.

UI Changes

This section only includes GUI changes.

• Drop gnome-nettools

Code Changes

Dropped packages

ifenslave, vlan, bridge-utils may have reverse-depends in main; these need to be reviewed and fixed/demoted/nuked.

netplan

Some features are still missing from netplan; such as proper support for setting the MAC on devices (blocked on some systemd bugs), or setting IPv6 MTU. The relevant missing pieces have bugs open in Launchpad.

systemd

Systemd may have bugs that would block proper use of the new tooling, especially when it comes to netplan generating systemd-networkd configuration -- this configuration is usually based on what the documentation expresses as being available, but actual implementation might fail (cf. MAC address issues in progress).

MaaS

MaaS needs to generate network YAML v2.

cloud-init

Generating/parsing network YAML v2 to apply configuration.

netcfg

netcfg needs to generate network YAML v2 instead of ifupdown configuration. It will need to copy that configuration to the installed system.

ubuntu-fan

Replace uses of bridge-utils / other "old tools" with the new.

Infrastructure changes

Autopkgtests

Many packages may be using net-tools, bridge-utils or vlan to set up their environment for autopkgtest. Review this usage and apply fixes as appropriate.

Image build scripts

Any use of the "old commands" should be ported to the "new commands".

Other infrastructure

Review the use of old tools in Ubuntu infrastructure.

Migration

This impacts tools commonly used in user scripts, they would be broken unless we provide sufficient wrappers/redirections.

• The changes should be well documented, and a clear migration path identified in Release Notes for users.
• Replace some of the most commonly used tools with stubs or wrappers to point to the new way.
• Document changes in slideshow? MOTD?
• Implement a conversion tools in netplan for existing ifupdown configurations.

Test/Demo Plan

Outstanding Issues

Systemd bugs (to be identified precisely).

BoF agenda and discussion

BoF Notes

Proposed workitems for blueprint:

Work items for ubuntu-17.06:
[cyphermox] blog about netplan and its awesomeness: INPROGRESS
[cyphermox] netplan cheerleading: TODO
[cyphermox] document pre-planned out of scope work: TODO
[cyphermox] document/discuss/announce plan on ubuntu-devel@: TODO
[cyphermox] review systemd issues with applying MAC addresses: TODO
[cyphermox] merge MAC address code: TODO
[cyphermox] set up tracker for netplan migration: TODO
[cyphermox] scan on default installs for undocumented uses of ifupdown: TODO
[rharper] IPv6 MTU code: TODO
[cyphermox] speak to mpontillo for netplan crit-path features for MaaS: TODO
[cyphermox] speak to dpb for netplan crit-path features for server: TODO
[cyphermox] speak to tbaumann / balloons / sinzui for netplan crit-path features for Juju: TODO
[cyphermox] speak to willcooke for netplan crit-path features for desktop: TODO
provide an easy way (preseed?) to bring up an ifupdown-less system: TODO
schedule feature work in milestones: TODO


Work items for ubuntu-17.07:
review and fix netcf usage of ifupdown: TODO
review and fix grub-legacy-ec2 usage of old tools: TODO
review and fix ifenslave usage of old tools: TODO
review and fix libvirt-daemon-system usage of old tools: TODO
review and fix lxc1 usage of old tools: TODO
review and fix neutron-linuxbridge-agent usage of old tools: TODO
review and fix nova-compute usage of old tools: TODO
review and fix nova-compute-libvirt usage of old tools: TODO
review and fix nova-network usage of old tools: TODO
review and fix pppoeconf usage of old tools: TODO
review and fix qemu usage of old tools: TODO
review and fix resolvconf usage of old tools: TODO
review and fix ubuntu-fan usage of old tools: TODO
autopkgtests for ifupdown-less install: TODO
review and fix infrastructure for using new tools: TODO
implement MOTD/command-not-found documentation for new commands: TODO
implement wrappers for critical-path tools / warnings: TODO


Work items for ubuntu-17.08:
update seeds to not install ifupdown: TODO
review and postpone or crack down on remaining feature work: TODO
test migration code existing in netplan: TODO
fix/update migration code: TODO
proceed with ifupdown migration by default on install of netplan: TODO
get attention from the proper people for go/no-go decision: TODO
announce changes again / reminder on ubuntu-devel@: TODO


Work items for ubuntu-17.09:
check with MaaS team for extra features still missing: TODO
check with Juju team for extra features still missing: TODO
check with other teams for extra features still missing: TODO
review postponed features and re-target for 18.04: TODO
bug fixes for release-critical bugs in netplan/affected packages: TODO


Work items for ubuntu-17.10:
release note the changes: TODO
cleanup remaining affected packages: TODO
last-minute testing and bugfix: TODO

CategorySpec