Skip to content

Commit

Permalink
Merge pull request #768 from asears/md-doc-lint-updates-3
Browse files Browse the repository at this point in the history
Fix linting issues in docs, add headers to json example, update errors into table
  • Loading branch information
squeed authored Jun 10, 2020
2 parents 0016c95 + 9ec274a commit 11db36c
Show file tree
Hide file tree
Showing 4 changed files with 78 additions and 48 deletions.
3 changes: 1 addition & 2 deletions CODE-OF-CONDUCT.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
## Community Code of Conduct
# Community Code of Conduct

CNI follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).

28 changes: 15 additions & 13 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ it easier to get your contribution accepted.

We gratefully welcome improvements to documentation as well as to code.

# Certificate of Origin
## Certificate of Origin

By contributing to this project you agree to the Developer Certificate of
Origin (DCO). This document was created by the Linux Kernel community and is a
simple statement that you, as a contributor, have the legal right to make the
contribution. See the [DCO](DCO) file for details.

# Email and Chat
## Email and Chat

The project uses the cni-dev email list, IRC chat, and Slack:
- Email: [cni-dev](https://groups.google.com/forum/#!forum/cni-dev)
Expand All @@ -39,14 +39,15 @@ This is a rough outline of how to prepare a contribution:
- Make sure your commit messages are in the proper format (see below).
- Push your changes to a topic branch in your fork of the repository.
- If you changed code:
- add automated tests to cover your changes, using the [Ginkgo](https://onsi.github.io/ginkgo/) & [Gomega](https://onsi.github.io/gomega/) style
- if the package did not previously have any test coverage, add it to the list
- add automated tests to cover your changes, using the [Ginkgo](https://onsi.github.io/ginkgo/) & [Gomega](https://onsi.github.io/gomega/) style
- if the package did not previously have any test coverage, add it to the list
of `TESTABLE` packages in the `test.sh` script.
- run the full test script and ensure it passes
- run the full test script and ensure it passes
- Make sure any new code files have a license header (this is now enforced by automated tests)
- Submit a pull request to the original repository.

## How to run the test suite

We generally require test coverage of any new features or bug fixes.

Here's how you can run the test suite on any system (even Mac or Windows) using
Expand All @@ -67,15 +68,15 @@ cd libcni
go test
```

# Acceptance policy
## Acceptance policy

These things will make a PR more likely to be accepted:

* a well-described requirement
* tests for new code
* tests for old code!
* new code and tests follow the conventions in old code and tests
* a good commit message (see below)
- a well-described requirement
- tests for new code
- tests for old code!
- new code and tests follow the conventions in old code and tests
- a good commit message (see below)

In general, we will merge a PR once two maintainers have endorsed it.
Trivial changes (e.g., corrections to spelling) may get waved through.
Expand All @@ -87,7 +88,7 @@ We follow a rough convention for commit messages that is designed to answer two
questions: what changed and why. The subject line should feature the what and
the body of the commit should describe the why.

```
```md
scripts: add the test-cluster command

this uses tmux to setup a test cluster that you can easily kill and
Expand All @@ -98,7 +99,7 @@ Fixes #38

The format can be described more formally as follows:

```
```md
<subsystem>: <what changed>
<BLANK LINE>
<why this change was made>
Expand All @@ -112,6 +113,7 @@ This allows the message to be easier to read on GitHub as well as in various
git tools.

## 3rd party plugins

So you've built a CNI plugin. Where should it live?

Short answer: We'd be happy to link to it from our [list of 3rd party plugins](README.md#3rd-party-plugins).
Expand Down
24 changes: 15 additions & 9 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Release process

## Resulting artifacts

Creating a new release produces the following artifacts:

- Binaries (stored in the `release-<TAG>` directory) :
Expand All @@ -9,26 +10,31 @@ Creating a new release produces the following artifacts:
- `sha1`, `sha256` and `sha512` files for the above files.

## Preparing for a release

1. Releases are performed by maintainers and should usually be discussed and planned at a maintainer meeting.
- Choose the version number. It should be prefixed with `v`, e.g. `v1.2.3`
- Take a quick scan through the PRs and issues to make sure there isn't anything crucial that _must_ be in the next release.
- Create a draft of the release note
- Discuss the level of testing that's needed and create a test plan if sensible
- Check what version of `go` is used in the build container, updating it if there's a new stable release.

- Choose the version number. It should be prefixed with `v`, e.g. `v1.2.3`
- Take a quick scan through the PRs and issues to make sure there isn't anything crucial that _must_ be in the next release.
- Create a draft of the release note
- Discuss the level of testing that's needed and create a test plan if sensible
- Check what version of `go` is used in the build container, updating it if there's a new stable release.

## Creating the release artifacts

1. Make sure you are on the master branch and don't have any local uncommitted changes.
1. Create a signed tag for the release `git tag -s $VERSION` (Ensure that GPG keys are created and added to GitHub)
1. Run the release script from the root of the repository
- `scripts/release.sh`
- The script requires Docker and ensures that a consistent environment is used.
- The artifacts will now be present in the `release-<TAG>` directory.

- `scripts/release.sh`
- The script requires Docker and ensures that a consistent environment is used.
- The artifacts will now be present in the `release-<TAG>` directory.

1. Test these binaries according to the test plan.

## Publishing the release

1. Push the tag to git `git push origin <TAG>`
1. Create a release on Github, using the tag which was just pushed.
1. Attach all the artifacts from the release directory.
1. Add the release note to the release.
1. Announce the release on at least the CNI mailing, IRC and Slack.

71 changes: 47 additions & 24 deletions SPEC.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,31 @@
# Container Network Interface Specification

- [Version](#version)
- [Overview](#overview)
- [General considerations](#general-considerations)
- [CNI Plugin](#cni-plugin)
* [Overview](#overview-1)
* [Parameters](#parameters)
* [Result](#result)
* [Network Configuration](#network-configuration)
* [Example configurations](#example-configurations)
* [Network Configuration Lists](#network-configuration-lists)
* [IP Allocation](#ip-allocation)
* [Well-known Structures](#well-known-structures)
- [Well-known Error Codes](#well-known-error-codes)
- [Container Network Interface Specification](#container-network-interface-specification)
- [Version](#version)
- [Released versions](#released-versions)
- [Overview](#overview)
- [General considerations](#general-considerations)
- [CNI Plugin](#cni-plugin)
- [Overview](#overview-1)
- [Parameters](#parameters)
- [Result](#result)
- [Network Configuration](#network-configuration)
- [Example configurations](#example-configurations)
- [Example bridge configuration](#example-bridge-configuration)
- [Example ovs configuration](#example-ovs-configuration)
- [Example macvlan configuration](#example-macvlan-configuration)
- [Network Configuration Lists](#network-configuration-lists)
- [Network Configuration List Error Handling](#network-configuration-list-error-handling)
- [Example network configuration lists](#example-network-configuration-lists)
- [Network configuration list runtime examples](#network-configuration-list-runtime-examples)
- [IP Allocation](#ip-allocation)
- [IP Address Management (IPAM) Interface](#ip-address-management-ipam-interface)
- [Notes](#notes)
- [Well-known Structures](#well-known-structures)
- [IPs](#ips)
- [Routes](#routes)
- [DNS](#dns)
- [Well-known Error Codes](#well-known-error-codes)

## Version

Expand Down Expand Up @@ -146,6 +159,7 @@ Plugins should generally complete a `DEL` action without error even if some reso

Runtimes must use the type of network (see [Network Configuration](#network-configuration) below) as the name of the executable to invoke.
Runtimes should then look for this executable in a list of predefined directories (the list of directories is not prescribed by this specification). Once found, it must invoke the executable using the following environment variables for argument passing:

- `CNI_COMMAND`: indicates the desired operation; `ADD`, `DEL`, `CHECK`, or `VERSION`.
- `CNI_CONTAINERID`: Container ID
- `CNI_NETNS`: Path to network namespace file
Expand Down Expand Up @@ -255,6 +269,8 @@ Plugins may define additional fields that they accept and may generate an error

### Example configurations

#### Example bridge configuration

```jsonc
{
"cniVersion": "0.4.0",
Expand All @@ -274,6 +290,8 @@ Plugins may define additional fields that they accept and may generate an error
}
```

#### Example ovs configuration

```jsonc
{
"cniVersion": "0.4.0",
Expand All @@ -295,6 +313,8 @@ Plugins may define additional fields that they accept and may generate an error
}
```

#### Example macvlan configuration

```jsonc
{
"cniVersion": "0.4.0",
Expand All @@ -317,6 +337,7 @@ Network configuration lists provide a mechanism to run multiple CNI plugins for
The list is composed of well-known fields and list of one or more standard CNI network configurations (see above).

The list is described in JSON form, and can be stored on disk or generated from other sources by the container runtime. The following fields are well-known and have the following meaning:

- `cniVersion` (string): [Semantic Version 2.0](https://semver.org) of CNI specification to which this configuration list and all the individual configurations conform.
- `name` (string): Network name. This should be unique across all containers on the host (or other administrative domain). Must start with a alphanumeric character, optionally followed by any combination of one or more alphanumeric characters, underscore (_), dot (.) or hyphen (-).
- `disableCheck` (string): Either `true` or `false`. If `disableCheck` is `true`, runtimes must not call `CHECK` for this network configuration list. This allows an administrator to prevent `CHECK`ing where a combination of plugins is known to return spurious errors.
Expand Down Expand Up @@ -567,16 +588,16 @@ Note that plugins are executed in reverse order from the `ADD` and `CHECK` actio
"interfaces": [
{
"name": "cni0",
"mac": "00:11:22:33:44:55",
"mac": "00:11:22:33:44:55"
},
{
"name": "veth3243",
"mac": "55:44:33:22:11:11",
"mac": "55:44:33:22:11:11"
},
{
"name": "eth0",
"mac": "99:88:77:66:55:44",
"sandbox": "/var/run/netns/blue",
"sandbox": "/var/run/netns/blue"
}
],
"dns": {
Expand Down Expand Up @@ -768,11 +789,13 @@ The `dns` field contains a dictionary consisting of common DNS information.

Error codes 1-99 must not be used other than as specified here.

- `1` - Incompatible CNI version
- `2` - Unsupported field in network configuration. The error message must contain the key and value of the unsupported field.
- `3` - Container unknown or does not exist. This error implies the runtime does not need to perform any container network cleanup (for example, calling the `DEL` action on the container).
- `4` - Invalid necessary environment variables, like CNI_COMMAND, CNI_CONTAINERID, etc. The error message must contain the names of invalid variables.
- `5` - I/O failure. For example, failed to read network config bytes from stdin.
- `6` - Failed to decode content. For example, failed to unmarshal network config from bytes or failed to decode version info from string.
- `7` - Invalid network config. If some validations on network configs do not pass, this error will be raised.
- `11` - Try again later. If the plugin detects some transient condition that should clear up, it can use this code to notify the runtime it should re-try the operation later.
Error Code|Error Description
---|---
`-1`|Incompatible CNI version
`-2`|Unsupported field in network configuration. The error message must contain the key and value of the unsupported field.
`-3`|Container unknown or does not exist. This error implies the runtime does not need to perform any container network cleanup (for example, calling the `DEL` action on the container).
`-4`|Invalid necessary environment variables, like CNI_COMMAND, CNI_CONTAINERID, etc. The error message must contain the names of invalid variables.
`-5`|I/O failure. For example, failed to read network config bytes from stdin.
`-6`|Failed to decode content. For example, failed to unmarshal network config from bytes or failed to decode version info from string.
`-7`|Invalid network config. If some validations on network configs do not pass, this error will be raised.
`-11`|Try again later. If the plugin detects some transient condition that should clear up, it can use this code to notify the runtime it should re-try the operation later.

0 comments on commit 11db36c

Please sign in to comment.