Many discrepancies between the SPEC and the code

[Dave Tucker]

For context, I've been playing around with implementing a CNI plugin in Rust.
My assumption was that the spec should be sufficient to do this, but in practice, there is a lot of behaviour that is inconsistent with the documentation.

I will chronicle these discrepencies as I find them in this issue, in the hope that it can be used to reconcile the spec with the code.

---

The spec states:

A CNI plugin, upon receiving an ADD command, should either

• create the interface defined by CNI_IFNAME inside the container at CNI_NETNS, or
• adjust the configuration of the interface defined by CNI_IFNAME inside the container at CNI_NETNS.

https://github.com/containernetworking/cni/blob/main/SPEC.md?plain=1#L221-L223

But later in the same paragraph:

If an interface of the requested name already exists in the container, the CNI plugin MUST return with an error.

https://github.com/containernetworking/cni/blob/main/SPEC.md?plain=1#L227

These two statements seem to contradict each other. The latter implies the existence of an interface called CNI_IFNAME should be an error, but the former implies that in this case, I should adjust the configuration of the interface.

[Dave Tucker]

The plugin returns a result on stdout on success, or an error on stderr if the operation fails. Configuration and results are encoded in JSON.

host-local IPAM returns errors on stdout

[Dave Tucker]

https://github.com/containernetworking/cni/blob/main/SPEC.md#Error

The error spec says that the JSON should have the following keys.
I interpreted this as all the keys.
In practice an error from host-local IPAM includes only msg and code:

{
    "code": 999,
    "msg": "failed to allocate for range 0: 10.88.0.3 has been allocated to foo, duplicate allocation is not allowed"
}

Update: The code doesn't include cniVersion at all. And details is optional.
https://github.com/containernetworking/cni/blob/main/pkg/types/types.go#L172-L176

[Dave Tucker]

https://github.com/containernetworking/cni/blob/main/SPEC.md#add-add-container-to-network-or-apply-modifications

The definition of the JSON input for ADD is missing from this section.

Furthermore, one "gotcha" was that while type is documented as a required key for ipam in the main configuration section... The JSON provided to add can contain other keys which should be passed through to the IPAM plugin.... The CNI plugin only needs to read type so it can execute the delegated plugin.

[Dan Williams]

@dave-tucker thanks for the comments; I think there are definitely some improvements to make here. We'll take a look!

[Casey Callendrello]

host-local IPAM returns errors on stdout

Hah. Oops. Fixing that now.

[Casey Callendrello]

host-local IPAM returns errors on stdout

The spec is unclear; the intended behavior is that diagnostic error messages are output to stderr, and results always go to stdout (even if in error). I'll queue this up to the spec fixes.