MigratingToNetplan
|
Size: 5125
Comment:
|
Size: 7343
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 6: | Line 6: |
| * '''Packages affected''': bridge-utils cloud-init maas netcfg netplan net-tools ifenslave ifupdown systemd vlan | * '''Packages affected''': cloud-init maas netcfg nplan ifupdown juju systemd |
| Line 9: | Line 10: |
| ||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<TableOfContents(2)>>|| | |
| Line 10: | Line 12: |
| Planning for the replacement of ifupdown and overhaul of networking tools in Ubuntu, for the 17.10 release. The target is to aggressively move towards using netplan as the preferred method of configuring the network, making sure it provides the necessary support for the features our users have come to expect, and using NetworkManager and/or systemd-networkd as a preferred "renderer" for the network configuration. | 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. |
| Line 12: | Line 14: |
| 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 ip-route2: using the 'ip' command, for example. | Deprecate ifupdown in Ubuntu for the 17.10 release. Deliver a unified network stack of netplan and networkd/network-manager across all 17.10 images in preparation for the 18.04 LTS. This will make it easier to have a consistent experience across all systems when it comes to configuring network devices; as well as how to do the configuration when dealing with multiple systems at once via MaaS or as provisioned in clouds using cloud-init. |
| Line 16: | Line 21: |
| In this release, several networking tools have been modernized or replaced; the table below outlines the most common replacement for well-known commands: | Ubuntu 17.10 introduces a new default configuration method for network devices, using netplan instead of ifupdown. Configuration is now written as YAML files to /etc/netplan instead of in /etc/network/interfaces. See [[Netplan|Netplan]] for more information about how to configure your network devices. |
| Line 18: | Line 23: |
| /!\ Include table here; e.g ifconfig == ip address / bridgectl addif eth0 br0 == bridge link set ... | Ifupdown is still available in the archive, and can be reinstalled by running the command: "sudo apt install ifupdown". |
| Line 22: | Line 27: |
| We've 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. | Netplan has been implemented to support simple, declarative representation of complex network configurations, as well as address some current limitations of ifupdown. Netplan provides a simple and elegant yaml configuration format with support for multiple backend providers. Some of the shortcomings of ifupdown covered by netplan: * ifupdown cannot represent all configs with a purely declarative syntax; therefore we can not parse the config * all netplan config is purely declarative. * ifupdown can only represent interfaces by name, so it is not portable across devices * netplan uses matching by name, MAC address, driver, etc. * race conditions in complex configs * netplan has the context of hierarchy in the definition of the interfaces, such that this information is carried over to the renderer used and applied in the right ordering. 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 the ease of representing the network config. |
| Line 26: | Line 41: |
| == Assumptions == | * 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 provisions a 17.10 system using MaaS; nplan is used automatically to configure the network on the system. * Mark installs lxd. When starting a guest, netplan correctly handles the network configuration and the guest comes up with the expected network configuration. * Jill bring up a new system for a deployment using juju; the system comes up with netplan instead of /e/n/i configuration and is reachable from the network. * William launches an Ubuntu instance in a public cloud. The system comes up and is reachable from the Internet. |
| Line 28: | Line 47: |
| == Design == | |
| Line 32: | Line 50: |
| 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. |
|
| Line 36: | Line 52: |
| Migration to netplan and phasing out of old network tools will happen in several phases, which may overlap: | Early in the 17.10 cycle, we switch to using netplan by default; this is a rather straightforward change to unseed ifupdown. This can be done as soon as this spec is agreed upon. |
| Line 38: | Line 54: |
| * 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.) |
Some pieces will require code changes: debian-installer (netcfg) will need to be writing the new config format; changing netcfg is a critical, but relatively simple step (netcfg should write both configs to start with). Make a go/no-go decision on whether netplan is appropriately doing its job by the Artful Final Beta; September 28th 2017. This migration plans does not include the removal of ifupdown from the archive. ifupdown will still be available for users who wish to explicitly install it, but would not be automatically installed by default for any Ubuntu deployment. |
| Line 46: | Line 63: |
| /!\ This section only includes GUI changes. | Not applicable. |
| Line 48: | Line 65: |
| * Drop gnome-nettools | |
| Line 52: | Line 68: |
| ==== Dropped packages ==== | |
| Line 54: | Line 69: |
| ifenslave, vlan, bridge-utils may have reverse-depends in main; these need to be reviewed and fixed/demoted/nuked. | ==== debian-installer / netcfg ==== |
| Line 56: | Line 71: |
| ==== 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. |
Netcfg needs to write network V2 YAML as well as e/n/i configuration. |
| Line 81: | Line 74: |
| === 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. |
|
| Line 98: | Line 78: |
| /!\ This impacts tools commonly used in user scripts, they would be broken unless we provide sufficient wrappers/redirections. | There is a '''netplan ifupdown-migrate''' command that exists that may be used by system administrators to convert simple ifupdown configuration to netplan. Typical upgrade scenarios would automatically keep ifupdown installed; and we will rely on users to do the migration themselves. |
| Line 100: | Line 80: |
| * 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. |
|
| Line 106: | Line 82: |
* Testing should be ongoing to make sure there are no regressions. Expect feedback at any step of the migration. This is achieved with autopkgtests in netplan: all new features should include integration tests that exercise them, and can identify regressions caused by other changes or changes to the underlying renderer tools. * Spin up instances of all supported clouds to make sure they work in a world without ifupdown, using netplan instead. * Validate that on installs of server and with "alternate" desktop images, netplan config is written to the installed system by debian-installer. * Test common network designs in place (install a system, configure netplan to the desired design, reboot, and validate that the configuration comes up as expected): * Bridged devices: have the system come up on two separate interfaces on separate networks, bridge them together and apply the right IP addresses and routing. * Bonded devices: bring up system with two bonded devices, ensure that both are correctly added to the virtual bond, system boots correctly and without delay. * DHCP interface: a system can be brought up and installed with DHCP from d-i and will correctly come up and use the configuration supplied from the installer. * Static IP: a system can be brought up and installed with a static IP address from d-i and will correctly come up and use the configuration supplied from the installer. * MaaS installs: system can be brought up with a configuration from MaaS and the configuration supplied will be used by the system as boot. |
|
| Line 118: | Line 104: |
| == Signoff == {{{#!wiki note ''~-Use @``SIG@ to sign-off your team on this Spec.-~'' }}} || '''Team''' || '''Signoff''' || || Foundations || -- [[LaunchpadHome:vorlon]] <<DateTime(2017-05-23T12:50:55-0800)>> || || Server || || || Juju || || |
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: cloud-init maas netcfg nplan ifupdown juju systemd
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 in Ubuntu for the 17.10 release. Deliver a unified network stack of netplan and networkd/network-manager across all 17.10 images in preparation for the 18.04 LTS.
This will make it easier to have a consistent experience across all systems when it comes to configuring network devices; as well as how to do the configuration when dealing with multiple systems at once via MaaS or as provisioned in clouds using cloud-init.
Release Note
Ubuntu 17.10 introduces a new default configuration method for network devices, using netplan instead of ifupdown. Configuration is now written as YAML files to /etc/netplan instead of in /etc/network/interfaces. See Netplan for more information about how to configure your network devices.
Ifupdown is still available in the archive, and can be reinstalled by running the command: "sudo apt install ifupdown".
Rationale
Netplan has been implemented to support simple, declarative representation of complex network configurations, as well as address some current limitations of ifupdown. Netplan provides a simple and elegant yaml configuration format with support for multiple backend providers.
Some of the shortcomings of ifupdown covered by netplan:
- ifupdown cannot represent all configs with a purely declarative syntax; therefore we can not parse the config
- all netplan config is purely declarative.
- ifupdown can only represent interfaces by name, so it is not portable across devices
- netplan uses matching by name, MAC address, driver, etc.
- race conditions in complex configs
- netplan has the context of hierarchy in the definition of the interfaces, such that this information is carried over to the renderer used and applied in the right ordering.
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 the ease of representing the network config.
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 provisions a 17.10 system using MaaS; nplan is used automatically to configure the network on the system.
- Mark installs lxd. When starting a guest, netplan correctly handles the network configuration and the guest comes up with the expected network configuration.
- Jill bring up a new system for a deployment using juju; the system comes up with netplan instead of /e/n/i configuration and is reachable from the network.
- William launches an Ubuntu instance in a public cloud. The system comes up and is reachable from the Internet.
Implementation
Summary
Early in the 17.10 cycle, we switch to using netplan by default; this is a rather straightforward change to unseed ifupdown. This can be done as soon as this spec is agreed upon.
Some pieces will require code changes: debian-installer (netcfg) will need to be writing the new config format; changing netcfg is a critical, but relatively simple step (netcfg should write both configs to start with).
Make a go/no-go decision on whether netplan is appropriately doing its job by the Artful Final Beta; September 28th 2017.
This migration plans does not include the removal of ifupdown from the archive. ifupdown will still be available for users who wish to explicitly install it, but would not be automatically installed by default for any Ubuntu deployment.
UI Changes
Not applicable.
Code Changes
debian-installer / netcfg
Netcfg needs to write network V2 YAML as well as e/n/i configuration.
Migration
There is a netplan ifupdown-migrate command that exists that may be used by system administrators to convert simple ifupdown configuration to netplan. Typical upgrade scenarios would automatically keep ifupdown installed; and we will rely on users to do the migration themselves.
Test/Demo Plan
- Testing should be ongoing to make sure there are no regressions. Expect feedback at any step of the migration. This is achieved with autopkgtests in netplan: all new features should include integration tests that exercise them, and can identify regressions caused by other changes or changes to the underlying renderer tools.
- Spin up instances of all supported clouds to make sure they work in a world without ifupdown, using netplan instead.
- Validate that on installs of server and with "alternate" desktop images, netplan config is written to the installed system by debian-installer.
- Test common network designs in place (install a system, configure netplan to the desired design, reboot, and validate that the configuration comes up as expected):
- Bridged devices: have the system come up on two separate interfaces on separate networks, bridge them together and apply the right IP addresses and routing.
- Bonded devices: bring up system with two bonded devices, ensure that both are correctly added to the virtual bond, system boots correctly and without delay.
- DHCP interface: a system can be brought up and installed with DHCP from d-i and will correctly come up and use the configuration supplied from the installer.
- Static IP: a system can be brought up and installed with a static IP address from d-i and will correctly come up and use the configuration supplied from the installer.
- MaaS installs: system can be brought up with a configuration from MaaS and the configuration supplied will be used by the system as boot.
Outstanding Issues
Systemd bugs (to be identified precisely).
BoF agenda and discussion
BoF Notes
Signoff
Use @SIG@ to sign-off your team on this Spec.
Team |
Signoff |
Foundations |
-- vorlon 2017-05-23 20:50:55 |
Server |
|
Juju |
|
MigratingToNetplan (last edited 2017-06-19 14:05:09 by raharper)