From 328ea56e7530c057d54d57e3b719bc643227288c Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Sun, 26 Feb 2017 13:26:14 -0800 Subject: [PATCH 1/8] docs: CNI versioning for 0.3.0 upgrade --- Documentation/spec-upgrades.md | 101 +++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 Documentation/spec-upgrades.md diff --git a/Documentation/spec-upgrades.md b/Documentation/spec-upgrades.md new file mode 100644 index 00000000..b9ac77ec --- /dev/null +++ b/Documentation/spec-upgrades.md @@ -0,0 +1,101 @@ +# CNI Plugin Versions, Compatibility, and Writing Plugins + +## Specification Changes between CNI Specification Versions 0.2.0 and +0.3.0 + +Plugins which conform to the CNI 0.3.0 specification may elect to +return more expressive IPAM JSON that is not compatible with earlier +specification versions. This requires updates to plugins that wish to +conform to the 0.3.0 specification. It **does not** require updates to +plugins that wish to only implement the 0.2.0 and earlier +specifications. + +## Multi-version Compatible Plugins + +Plugins can also choose to support multiple CNI versions. The plugin is +expected to return IPAM output conforming to the CNI specification +version passed in the plugin's configuration on stdin in the +`cniVersion` key. If that key is not present, then CNI specification +version 0.2.0 should be assumed and 0.2.0 conforming JSON returned. +Plugins should return all CNI specification versions they are +compatible with when given the `VERSION` command, so runtimes can +determine each plugins capabilities. + +For example, if the plugin advertises only CNI specification version +0.2.0 support and receives a `cniVersion` key of "0.3.0" the plugin +must return an error. If the plugin advertises CNI specification +support for 0.2.0 and 0.3.0, and receives `cniVersion` key of "0.2.0", +the plugin must return IPAM JSON conforming to the CNI specification +version 0.2.0. + +## libcni API and Go Types Changes in 0.3.0 + +With the 0.5.0 CNI reference plugins and libcni release a number of +important changes were made that affect both runtimes and plugin +authors. These changes make it easier to enhance the libcni and plugin +interfaces going forward. The largest changes are to the `types` +package, which now contains multiple versions of libcni types. The +`current` package contains the latest types, while types compatible +with previous libcni releases will be placed into versioned packages +like `types020` (representing the libcni types that conform to the CNI +specification version 0.2.0). + +The `Result` type is now an interface instead of a plain struct. The +interface has new functions to convert the Result structure between +different versions of the libcni types. Plugins and consumers of libcni +should generally be written to use the Go types of the latest libcni +release, and convert between the latest libcni types and the CNI +specification type they are passed in the `cniVersion` key of plugin +configuration. + +### Plugins + +For example, say your plugins supports both CNI specification version +0.2.0 and 0.3.0. Your plugin receives configuration with a `cniVersion` +key of "0.2.0". This means your plugin should return an IPAM structure +conforming to the CNI specification version 0.2.0. The easiest way to +code your plugin is to always use the most current libcni Result type +(from the `current` package) and then immediately before exiting, +convert that result to the requested CNI specification version result +(eg, `types020`) and print it to stdout. + +``` +import "github.com/containernetworking/cni/pkg/types" +import "github.com/containernetworking/cni/pkg/types/current" + +result := ¤t.Result{} +<<< populate result here >>> +return types.PrintResult(result, << CNI version from stdin net +config>>) +``` + +or if your plugin internally runs IPAM and needs to process the result: + +``` +import "github.com/containernetworking/cni/pkg/types" +import "github.com/containernetworking/cni/pkg/types/current" + +ipamResult, err := ipam.ExecAdd(n.IPAM.Type, args.StdinData) +result, err := current.NewResultFromResult(ipamResult) +<<< manipulate result here >>> +return types.PrintResult(result, << CNI version from stdin net +config>>) +``` + +### Runtimes + +Since libcni functions like AddNetwork() now return a Result interface +rather than a plain structure, only a single additional step is +required to convert that object to a structure you can manipulate +internally. Runtimes should code to the most current Go types provided +by the libcni they vendor into their sources, and can convert from +whatever IPAM result version the plugin provides to the most current +version like so: + +``` +resultInterface, err := cninet.AddNetwork(netconf, rt) +<<< resultInterface could wrap an object of any CNI specification +version >>> +realResult := current.NewResultFromResult(resultInterface) +<<< realResult is a struct, not an interface >>> +``` From fa5344685490c1ddbcfcbcced0a4b62e2032b405 Mon Sep 17 00:00:00 2001 From: Gabe Rosenhouse Date: Sun, 26 Feb 2017 16:53:52 -0800 Subject: [PATCH 2/8] docs: Edits to v0.3.0 upgrade guidance --- Documentation/spec-upgrades.md | 281 ++++++++++++++++++++++++--------- 1 file changed, 204 insertions(+), 77 deletions(-) diff --git a/Documentation/spec-upgrades.md b/Documentation/spec-upgrades.md index b9ac77ec..7cfd2ed5 100644 --- a/Documentation/spec-upgrades.md +++ b/Documentation/spec-upgrades.md @@ -1,101 +1,228 @@ -# CNI Plugin Versions, Compatibility, and Writing Plugins +# How to upgrade to CNI Specification v0.3.0 -## Specification Changes between CNI Specification Versions 0.2.0 and -0.3.0 +Version 0.3.0 of the [CNI Specification](../SPEC.md) provides rich information +about container network configuration, including details of network interfaces +and support for multiple IP addresses. -Plugins which conform to the CNI 0.3.0 specification may elect to -return more expressive IPAM JSON that is not compatible with earlier -specification versions. This requires updates to plugins that wish to -conform to the 0.3.0 specification. It **does not** require updates to -plugins that wish to only implement the 0.2.0 and earlier -specifications. +To support this new data, the specification changed in a couple significant +ways that will impact CNI users, plugin authors, and runtime authors. -## Multi-version Compatible Plugins +This document provides guidance for how to upgrade: -Plugins can also choose to support multiple CNI versions. The plugin is -expected to return IPAM output conforming to the CNI specification -version passed in the plugin's configuration on stdin in the -`cniVersion` key. If that key is not present, then CNI specification -version 0.2.0 should be assumed and 0.2.0 conforming JSON returned. -Plugins should return all CNI specification versions they are -compatible with when given the `VERSION` command, so runtimes can -determine each plugins capabilities. +- [For CNI Users](#for-cni-users) +- [For Plugin Authors](#for-plugin-authors) +- [For Runtime Authors](#for-runtime-authors) -For example, if the plugin advertises only CNI specification version -0.2.0 support and receives a `cniVersion` key of "0.3.0" the plugin -must return an error. If the plugin advertises CNI specification -support for 0.2.0 and 0.3.0, and receives `cniVersion` key of "0.2.0", -the plugin must return IPAM JSON conforming to the CNI specification -version 0.2.0. +**Note**: the CNI Spec is versioned independently from the GitHub releases +for this repo. For example, Release v0.4.0 supports Spec version v0.2.0, +and Release v0.5.0 supports Spec v0.3.0. -## libcni API and Go Types Changes in 0.3.0 +---- -With the 0.5.0 CNI reference plugins and libcni release a number of -important changes were made that affect both runtimes and plugin -authors. These changes make it easier to enhance the libcni and plugin -interfaces going forward. The largest changes are to the `types` -package, which now contains multiple versions of libcni types. The -`current` package contains the latest types, while types compatible -with previous libcni releases will be placed into versioned packages -like `types020` (representing the libcni types that conform to the CNI -specification version 0.2.0). +## For CNI Users +If you maintain CNI configuration files for a container runtime that uses CNI, +ensure that the configuration files specify a `cniVersion` field and that the +version there is supported by your container runtime and CNI plugins. The CNI +spec includes example configuration files for [single plugins](https://github.com/containernetworking/cni/blob/master/SPEC.md#example-configurations) +and for [lists of chained plugins](https://github.com/containernetworking/cni/blob/master/SPEC.md#example-configurations). -The `Result` type is now an interface instead of a plain struct. The -interface has new functions to convert the Result structure between -different versions of the libcni types. Plugins and consumers of libcni -should generally be written to use the Go types of the latest libcni -release, and convert between the latest libcni types and the CNI -specification type they are passed in the `cniVersion` key of plugin -configuration. +Consult the documentation for your runtime and plugins to determine what +CNI spec versions they support. -### Plugins +## For Plugin Authors +This section provides guidance for upgrading plugins to CNI Spec Version 0.3.0. -For example, say your plugins supports both CNI specification version -0.2.0 and 0.3.0. Your plugin receives configuration with a `cniVersion` -key of "0.2.0". This means your plugin should return an IPAM structure -conforming to the CNI specification version 0.2.0. The easiest way to -code your plugin is to always use the most current libcni Result type -(from the `current` package) and then immediately before exiting, -convert that result to the requested CNI specification version result -(eg, `types020`) and print it to stdout. +### General guidance for all plugins (language agnostic) +To provide the smoothest upgrade path, **existing plugins should support +multiple versions of the CNI spec**. In particular, plugins with existing +installed bases should add support for CNI spec version 0.3.0 while maintaining +compatibility with older versions. -``` -import "github.com/containernetworking/cni/pkg/types" -import "github.com/containernetworking/cni/pkg/types/current" +To do this, two changes are required. First, a plugin should advertise which +CNI spec versions it supports. It does this by responding to the `VERSION` +command with the following JSON data: -result := ¤t.Result{} -<<< populate result here >>> -return types.PrintResult(result, << CNI version from stdin net -config>>) +```json +{ + "cniVersion": "0.3.0", + "supportedVersions": [ "0.1.0", "0.2.0", "0.3.0" ] +} ``` -or if your plugin internally runs IPAM and needs to process the result: +Second, for the `ADD` command, a plugin must respect the `cniVersion` field +provided in the [network configuration JSON](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration). +That field is a request for the plugin to return results of a particular format: +- If the `cniVersion` field is not present, then spec v0.2.0 should be assumed + and v0.2.0 format JSON returned. + +- If the plugin doesn't support the version, the plugin must error. + +- Otherwise, the plugin must return a [CNI Result](https://github.com/containernetworking/cni/blob/master/SPEC.md#result) + in the format requested. + +Result formats for older CNI spec versions are available in the +[git history for SPEC.md](https://github.com/containernetworking/cni/commits/master/SPEC.md). + +For example, suppose a plugin, via its `VERSION` response, advertises CNI specification +support for v0.2.0 and v0.3.0. When it receives `cniVersion` key of `0.2.0`, +the plugin must return result JSON conforming to CNI spec version 0.2.0. + +### Specific guidance for plugins written in Go +Plugins written in Go may leverage the Go language packages in this repository +to ease the process of upgrading and supporting multiple versions. CNI +[Library and Plugins Release v0.5.0](https://github.com/containernetworking/cni/releases) +includes important changes to the Golang APIs. Plugins using these APIs will +require some changes now, but should more-easily handle spec changes and +new features going forward. + +For plugin authors, the biggest change is that `types.Result` is now an +interface implemented by concrete struct types in the `types/current` and +`types/020` subpackages. + +Internally, plugins should use the `types/current` structs, and convert +to or from specific versions when required. In most plugins, the only +conversion required will at completion time, when it prints the result as +JSON to stdout. At that point, the result should be printed in the format +requested by the `cniVersion` field present in the network configuration. +Use the library function `types.PrintResult()` for that. + +Additionally, the plugin should advertise which CNI Spec versions it supports +via the 3rd argument to `skel.PluginMain()`. + +Here is some example code + +```go +import ( + "github.com/containernetworking/cni/pkg/skel" + "github.com/containernetworking/cni/pkg/types" + "github.com/containernetworking/cni/pkg/types/current" + "github.com/containernetworking/cni/pkg/version" +) + +func cmdAdd(args *skel.CmdArgs) error { + // determine spec version to use + var netConf struct { + types.NetConf + // other plugin-specific configuration goes here + } + err := json.Unmarshal(args.StdinData, &netConf) + cniVersion := netConf.CNIVersion + + // plugin does its work... + // set up interfaces + // assign addresses, etc + + // construct the result + result := ¤t.Result{ + Interfaces: []*current.Interface{ ... }, + IPs: []*current.IPs{ ... }, + ... + } + + // print result to stdout, in the format defined by the requested cniVersion + return types.PrintResult(result, cniVersion) +} + +func main() { + skel.PluginMain(cmdAdd, cmdDel, version.PluginSupports("0.1.0", "0.2.0", "0.3.0")) +} ``` -import "github.com/containernetworking/cni/pkg/types" -import "github.com/containernetworking/cni/pkg/types/current" -ipamResult, err := ipam.ExecAdd(n.IPAM.Type, args.StdinData) +Alternately, to use the result from a delegated IPAM plugin, the `result` +value might be formed like this: + +```go +ipamResult, err := ipam.ExecAdd(netConf.IPAM.Type, args.StdinData) result, err := current.NewResultFromResult(ipamResult) -<<< manipulate result here >>> -return types.PrintResult(result, << CNI version from stdin net -config>>) ``` -### Runtimes +Other examples of spec v0.3.0-compatible plugins are the +[main plugins in this repo](https://github.com/containernetworking/cni/tree/master/plugins/main) -Since libcni functions like AddNetwork() now return a Result interface -rather than a plain structure, only a single additional step is -required to convert that object to a structure you can manipulate -internally. Runtimes should code to the most current Go types provided -by the libcni they vendor into their sources, and can convert from -whatever IPAM result version the plugin provides to the most current -version like so: +## For Runtime Authors + +This section provides guidance for upgrading container runtimes to support +CNI Spec Version 0.3.0. + +### General guidance for all runtimes + +#### Support multiple CNI spec versions +To provide the smoothest upgrade path and support the broadest range of CNI +plugins, **container runtimes should support multiple versions of the CNI spec**. +In particular, runtimes with existing installed bases should add support for CNI +spec version 0.3.0 while maintaining compatibility with older versions. + +To support multiple versions of the CNI spec, runtimes should be able to +call both new and legacy plugins, and handle the results from either. + +When calling a plugin, the runtime must request that the plugin respond in a +particular format by specifying the `cniVersion` field in the +[Network Configuration](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration) +JSON block. The plugin will then respond with +a [Result](https://github.com/containernetworking/cni/blob/master/SPEC.md#result) +in the format defined by that CNI spec version, and the runtime must parse +and handle this result. + +#### Handle errors due to version incompatibility +Plugins may respond with error indicating that they don't support the requested +CNI version (see [Well-known Error Codes](https://github.com/containernetworking/cni/blob/master/SPEC.md#well-known-error-codes)), +e.g. +```json +{ + "cniVersion": "0.2.0", + "code": 1, + "msg": "CNI version not supported" +} ``` -resultInterface, err := cninet.AddNetwork(netconf, rt) -<<< resultInterface could wrap an object of any CNI specification -version >>> -realResult := current.NewResultFromResult(resultInterface) -<<< realResult is a struct, not an interface >>> +In that case, the runtime may retry with a lower CNI spec version, or take +some other action. + +#### (optional) Discover plugin version support +Runtimes may discover which CNI spec versions are supported by a plugin, by +calling the plugin with the `VERSION` command. The `VERSION` command was +added in CNI spec v0.2.0, so older plugins may not respect it. In the absence +of a successful response to `VERSION`, assume that the plugin only supports +CNI spec v0.1.0. + +#### Handle missing data in v0.3.0 results +The Result for the `ADD` command in CNI spec version 0.3.0 includes a new field +`interfaces`. An IP address in the `ip` field may describe which interface +it is assigned to, by placing a numeric index in the `interface` subfield. + +However, some plugins which are v0.3.0 compatible may nonetheless omit the +`interfaces` field and/or set the `interface` index value to `-1`. Runtimes +should gracefully handle this situation, unless they have good reason to rely +on the existence of the interface data. In that case, provide the user an +error message that helps diagnose the issue. + +### Specific guidance for container runtimes written in Go +Container runtimes written in Go may leverage the Go language packages in this +repository to ease the process of upgrading and supporting multiple versions. +CNI [Library and Plugins Release v0.5.0](https://github.com/containernetworking/cni/releases) +includes important changes to the Golang APIs. Runtimes using these APIs will +require some changes now, but should more-easily handle spec changes and +new features going forward. + +For runtimes, the biggest changes to the Go libraries are in the `types` package. +The top-level `types.Result` is now an opaque interface instead of a struct, and +APIs exposed by other packages, such as the high-level `libcni` package, have +been updated to use this interface. Concrete types are available as subpackages. +The `types/current` subpackage contains the latest (spec v0.3.0) types. + +A container runtime should use `current.NewResultFromResult()` to convert the +opaque `types.Result` to a concrete `current.Result` struct. It may then +work with the fields exposed by that struct: + +```go +// runtime invokes the plugin to get the opaque types.Result +// this may conform to any CNI spec version +resultInterface, err := libcni.AddNetwork(netConf, runtimeConf) + +// upconvert result to the current 0.3.0 spec +result, err := current.NewResultFromResult(resultInterface) + +// use the result fields .... +for _, ip := range result.IPs { ... } ``` From 70c153eb41a3f6e8e6d5cc1ee30241122ef7f713 Mon Sep 17 00:00:00 2001 From: Casey Callendrello Date: Mon, 27 Feb 2017 14:27:56 +0100 Subject: [PATCH 3/8] docs: minor improvements to 0.3.0 upgrade guidance --- Documentation/spec-upgrades.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/Documentation/spec-upgrades.md b/Documentation/spec-upgrades.md index 7cfd2ed5..b24411e4 100644 --- a/Documentation/spec-upgrades.md +++ b/Documentation/spec-upgrades.md @@ -206,10 +206,22 @@ require some changes now, but should more-easily handle spec changes and new features going forward. For runtimes, the biggest changes to the Go libraries are in the `types` package. -The top-level `types.Result` is now an opaque interface instead of a struct, and -APIs exposed by other packages, such as the high-level `libcni` package, have -been updated to use this interface. Concrete types are available as subpackages. -The `types/current` subpackage contains the latest (spec v0.3.0) types. +It has been refactored to make working with versioned results simpler. The top-level +`types.Result` is now an opaque interface instead of a struct, and APIs exposed by +other packages, such as the high-level `libcni` package, have been updated to use +this interface. Concrete types are now per-version subpackages. The `types/current` +subpackage contains the latest (spec v0.3.0) types. + +The versioned types understand how to convert between most versions. However, converting +to a higher version will mean some fields are missing. + +| From | 0.1 | 0.2 | 0.3 | +|--------|-----|-----|-----| +| To 0.1 | ✔ | ✔ | | +| To 0.2 | ✴ | ✔ | ✔ | +| To 0.3 | | ✴ | ✔ | + +*(pairs marked with ✴ will have some missing data)* A container runtime should use `current.NewResultFromResult()` to convert the opaque `types.Result` to a concrete `current.Result` struct. It may then From 119d6f20f5fa843cf9704f163a920a8662323c4c Mon Sep 17 00:00:00 2001 From: Casey Callendrello Date: Mon, 27 Feb 2017 14:57:31 +0100 Subject: [PATCH 4/8] docs: add small upgrade instructions --- Documentation/spec-upgrades.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Documentation/spec-upgrades.md b/Documentation/spec-upgrades.md index b24411e4..9c301aa1 100644 --- a/Documentation/spec-upgrades.md +++ b/Documentation/spec-upgrades.md @@ -22,12 +22,17 @@ and Release v0.5.0 supports Spec v0.3.0. ## For CNI Users If you maintain CNI configuration files for a container runtime that uses CNI, ensure that the configuration files specify a `cniVersion` field and that the -version there is supported by your container runtime and CNI plugins. The CNI -spec includes example configuration files for [single plugins](https://github.com/containernetworking/cni/blob/master/SPEC.md#example-configurations) +version there is supported by your container runtime and CNI plugins. +Configuration files without the version field should be labeled version 0.2.0 +by default. The CNI spec includes example configuration files for +[single plugins](https://github.com/containernetworking/cni/blob/master/SPEC.md#example-configurations) and for [lists of chained plugins](https://github.com/containernetworking/cni/blob/master/SPEC.md#example-configurations). Consult the documentation for your runtime and plugins to determine what -CNI spec versions they support. +CNI spec versions they support. Test any plugin upgrades before deploying to +production. You may find [cnitool](https://github.com/containernetworking/cni/tree/master/cnitool) +useful. Specifically, your configuration version should be the lowest common +version supported by your plugins. ## For Plugin Authors This section provides guidance for upgrading plugins to CNI Spec Version 0.3.0. From 379d47760c76022a634fa737e832ac47c941e474 Mon Sep 17 00:00:00 2001 From: Gabe Rosenhouse Date: Mon, 27 Feb 2017 07:11:04 -0800 Subject: [PATCH 5/8] docs: minor improvements to spec-upgrades --- Documentation/spec-upgrades.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/spec-upgrades.md b/Documentation/spec-upgrades.md index 9c301aa1..d2b70473 100644 --- a/Documentation/spec-upgrades.md +++ b/Documentation/spec-upgrades.md @@ -86,11 +86,11 @@ interface implemented by concrete struct types in the `types/current` and `types/020` subpackages. Internally, plugins should use the `types/current` structs, and convert -to or from specific versions when required. In most plugins, the only -conversion required will at completion time, when it prints the result as -JSON to stdout. At that point, the result should be printed in the format -requested by the `cniVersion` field present in the network configuration. -Use the library function `types.PrintResult()` for that. +to or from specific versions when required. A typical plugin will only need +to do a single conversion. That is when it is about to complete and needs to +print the result JSON in the correct format to stdout. The library +function `types.PrintResult()` simplifies this by converting and printing in +a single call. Additionally, the plugin should advertise which CNI Spec versions it supports via the 3rd argument to `skel.PluginMain()`. @@ -151,7 +151,7 @@ Other examples of spec v0.3.0-compatible plugins are the This section provides guidance for upgrading container runtimes to support CNI Spec Version 0.3.0. -### General guidance for all runtimes +### General guidance for all runtimes (language agnostic) #### Support multiple CNI spec versions To provide the smoothest upgrade path and support the broadest range of CNI From b6e9bf8372ba31b7b4dc6614f646652a1974f83d Mon Sep 17 00:00:00 2001 From: Gabe Rosenhouse Date: Mon, 27 Feb 2017 07:53:09 -0800 Subject: [PATCH 6/8] docs: fill-out and correct version conversion table --- Documentation/spec-upgrades.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/Documentation/spec-upgrades.md b/Documentation/spec-upgrades.md index d2b70473..1543f193 100644 --- a/Documentation/spec-upgrades.md +++ b/Documentation/spec-upgrades.md @@ -217,16 +217,20 @@ other packages, such as the high-level `libcni` package, have been updated to us this interface. Concrete types are now per-version subpackages. The `types/current` subpackage contains the latest (spec v0.3.0) types. -The versioned types understand how to convert between most versions. However, converting -to a higher version will mean some fields are missing. +When up-converting older result types to spec v0.3.0, fields new in +spec v0.3.0 (like `interfaces`) may be empty. Conversely, when +down-converting v0.3.0 results to an older version, any data in those fields +will be lost. | From | 0.1 | 0.2 | 0.3 | |--------|-----|-----|-----| -| To 0.1 | ✔ | ✔ | | -| To 0.2 | ✴ | ✔ | ✔ | -| To 0.3 | | ✴ | ✔ | +| To 0.1 | ✔ | ✔ | x | +| To 0.2 | ✔ | ✔ | x | +| To 0.3 | ✴ | ✴ | ✔ | -*(pairs marked with ✴ will have some missing data)* +✔ : lossless conversion +✴ : higher-version output may have empty fields +x : lower-version output is missing some data A container runtime should use `current.NewResultFromResult()` to convert the opaque `types.Result` to a concrete `current.Result` struct. It may then From bbc23ea761d05b2a0b33ced5db9a37b76e3f6262 Mon Sep 17 00:00:00 2001 From: Gabe Rosenhouse Date: Mon, 27 Feb 2017 07:57:00 -0800 Subject: [PATCH 7/8] docs: table formatting is hard --- Documentation/spec-upgrades.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Documentation/spec-upgrades.md b/Documentation/spec-upgrades.md index 1543f193..4ebcb518 100644 --- a/Documentation/spec-upgrades.md +++ b/Documentation/spec-upgrades.md @@ -228,9 +228,13 @@ will be lost. | To 0.2 | ✔ | ✔ | x | | To 0.3 | ✴ | ✴ | ✔ | -✔ : lossless conversion -✴ : higher-version output may have empty fields -x : lower-version output is missing some data + +Key: +> ✔ : lossless conversion
+> ✴ : higher-version output may have empty fields
+> x : lower-version output is missing some data
+ + A container runtime should use `current.NewResultFromResult()` to convert the opaque `types.Result` to a concrete `current.Result` struct. It may then From 09e5feae1f9ac912f4c4fcfb688b95953a4c7f08 Mon Sep 17 00:00:00 2001 From: Casey Callendrello Date: Tue, 28 Feb 2017 19:44:25 +0100 Subject: [PATCH 8/8] Minor rewording about default config version --- Documentation/spec-upgrades.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/spec-upgrades.md b/Documentation/spec-upgrades.md index 4ebcb518..f6447709 100644 --- a/Documentation/spec-upgrades.md +++ b/Documentation/spec-upgrades.md @@ -23,8 +23,8 @@ and Release v0.5.0 supports Spec v0.3.0. If you maintain CNI configuration files for a container runtime that uses CNI, ensure that the configuration files specify a `cniVersion` field and that the version there is supported by your container runtime and CNI plugins. -Configuration files without the version field should be labeled version 0.2.0 -by default. The CNI spec includes example configuration files for +Configuration files without a version field should be given version 0.2.0. +The CNI spec includes example configuration files for [single plugins](https://github.com/containernetworking/cni/blob/master/SPEC.md#example-configurations) and for [lists of chained plugins](https://github.com/containernetworking/cni/blob/master/SPEC.md#example-configurations). @@ -55,11 +55,11 @@ command with the following JSON data: ``` Second, for the `ADD` command, a plugin must respect the `cniVersion` field -provided in the [network configuration JSON](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration). +provided in the [network configuration JSON](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration). That field is a request for the plugin to return results of a particular format: - If the `cniVersion` field is not present, then spec v0.2.0 should be assumed - and v0.2.0 format JSON returned. + and v0.2.0 format result JSON returned. - If the plugin doesn't support the version, the plugin must error.