diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 4d48d883c..10be1074b 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -1,3 +1,5 @@ +# + --- name: Bug Report about: Report a bug encountered @@ -5,7 +7,6 @@ about: Report a bug encountered --- - **What happend**: **What you expected to happen**: @@ -16,7 +17,7 @@ about: Report a bug encountered **Environment**: -- Multus version +- Multus version image path and image ID (from 'docker images') - Kubernetes version (use `kubectl version`): - Primary CNI for Kubernetes cluster: diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md index e41646d03..5c1b62d46 100644 --- a/.github/ISSUE_TEMPLATE/enhancement.md +++ b/.github/ISSUE_TEMPLATE/enhancement.md @@ -1,3 +1,5 @@ +# + --- name: Enhancement Request about: Suggest an enhancement to multus diff --git a/.github/ISSUE_TEMPLATE/support.md b/.github/ISSUE_TEMPLATE/support.md index a907050bc..9afb8bc0b 100644 --- a/.github/ISSUE_TEMPLATE/support.md +++ b/.github/ISSUE_TEMPLATE/support.md @@ -1,3 +1,5 @@ +# + --- name: Support Request about: Support request or question relating to multus-cni diff --git a/.github/workflows/md-lint.yaml b/.github/workflows/md-lint.yaml new file mode 100644 index 000000000..137d06b58 --- /dev/null +++ b/.github/workflows/md-lint.yaml @@ -0,0 +1,19 @@ +name: markdown-lint +on: + pull_request: + +jobs: + markdown-lint: + name: lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + - name: lint + run: | + npm install -g markdownlint-cli + npm install -g markdownlint-rule-search-replace@1.0.9 + pwd + markdownlint "**/*.md" --disable MD013 MD033 MD045 MD024 MD041 MD029 MD051 -r markdownlint-rule-search-replace + markdownlint -V diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 0bf387603..e0288dbeb 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -62,7 +62,7 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [The Multus Slack Page](https://intel-corp.herokuapp.com/). All complaints will be reviewed and investigated promptly and fairly. Or you -may specifically contact Doug Smith (dosmith@redhat.com) via email. +may specifically contact Doug Smith () via email. All community leaders are obligated to respect the privacy and security of the reporter of any incident. @@ -117,7 +117,7 @@ the community. This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). @@ -125,6 +125,5 @@ enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. - +. Translations are available at +. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fbe100253..9ab8f4bec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ used by the Linux kernel project. Beside the signed-off-by footer, we expect each patch to comply with the following format: -``` +```bash Change summary More detailed explanation of your changes: Why and how. @@ -35,15 +35,15 @@ Signed-off-by: For example: -``` +```bash Fix poorly named identifiers - + One identifier, fnname, in func.go was poorly named. It has been renamed to fnName. Another identifier retval was not needed and has been removed entirely. Fixes #1 - + Signed-off-by: Abc Xyz ``` @@ -54,4 +54,5 @@ We accept github pull requests. ## Email and Chat The project uses the Slack chat: + - Slack: #[Intel-Corp](https://intel-corp.herokuapp.com/) channel on slack diff --git a/README.md b/README.md index 58db4c603..153d13396 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ The quickstart installation method for Multus requires that you have first insta To use latest features try command below which applies a daemonset and installs thick Multus using `kubectl`: -``` +```bash kubectl apply -f https://raw.githubusercontent.com/k8snetworkplumbingwg/multus-cni/master/deployments/multus-daemonset-thick.yml ``` @@ -38,7 +38,7 @@ With the multus 4.0 release, we introduce a new client/server-style plugin deplo We recommend using the thick plugin in most environments, but if you wish to run the thin plugin, or are in a resource-constrained environment, you may do so with: -``` +```bash kubectl apply -f https://raw.githubusercontent.com/k8snetworkplumbingwg/multus-cni/master/deployments/multus-daemonset.yml ``` diff --git a/docs/configuration.md b/docs/configuration.md index 4bfb4f0a5..d1e205db9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -12,7 +12,7 @@ Following is the example of multus config file, in `/etc/cni/net.d/`. Example configuration using `clusterNetwork` (see also [using delegates](#using-delegates)) -``` +```json { "cniVersion": "0.3.1", "name": "node-cni-network", @@ -31,7 +31,7 @@ Example configuration using `clusterNetwork` (see also [using delegates](#using- }, "capabilities": { "portMappings": true - }, + }, "namespaceIsolation": false, "clusterNetwork": "/etc/cni/net.d/99-flannel.conf", "defaultNetworks": ["sidecarCRD", "exampleNetwork"], @@ -51,22 +51,22 @@ This is a general index of options, however note that you must set either the `c * `cniDir` (string, optional): Multus CNI data directory, default `/var/lib/cni/multus` * `binDir` (string, optional): additional directory for CNI plugins which multus calls, in addition to the default (the default is typically set to `/opt/cni/bin`) * `kubeconfig` (string, optional): kubeconfig file for the out of cluster communication with kube-apiserver. See the example [kubeconfig](https://github.com/k8snetworkplumbingwg/multus-cni/blob/master/docs/node-kubeconfig.yaml). If you would like to use CRD (i.e. network attachment definition), this is required -* [`logToStderr`](#Logging-via-STDERR) (bool, optional): Enable or disable logging to `STDERR`. Defaults to true. -* [`logFile`](#Writing-to-a-Log-File) (string, optional): file path for log file. multus puts log in given file -* [`logLevel`](#Logging-Level) (string, optional): logging level (values in decreasing order of verbosity: "debug", "error", "verbose", or "panic") -* [`logOptions`](#Logging-Options) (object, optional): logging option, More detailed log configuration -* [`namespaceIsolation`](#Namespace-Isolation) (boolean, optional): Enables a security feature where pods are only allowed to access `NetworkAttachmentDefinitions` in the namespace where the pod resides. Defaults to false. -* [`globalNamespaces`](#Allow-specific-namespaces-to-be-used-across-namespaces-when-using-namespace-isolation): (string, optional): Used only when `namespaceIsolation` is true, allows specification of comma-delimited list of namespaces which may be referred to outside of namespace isolation. +* [`logToStderr`](#logging-via-stderr) (bool, optional): Enable or disable logging to `STDERR`. Defaults to true. +* [`logFile`](#writing-to-a-log-file) (string, optional): file path for log file. multus puts log in given file +* [`logLevel`](#logging-level) (string, optional): logging level (values in decreasing order of verbosity: "debug", "error", "verbose", or "panic") +* [`logOptions`](#logging-options) (object, optional): logging option, More detailed log configuration +* [`namespaceIsolation`](#namespace-isolation) (boolean, optional): Enables a security feature where pods are only allowed to access `NetworkAttachmentDefinitions` in the namespace where the pod resides. Defaults to false. +* [`globalNamespaces`](#allow-specific-namespaces-to-be-used-across-namespaces-when-using-namespace-isolation): (string, optional): Used only when `namespaceIsolation` is true, allows specification of comma-delimited list of namespaces which may be referred to outside of namespace isolation. * `capabilities` ({}list, optional): [capabilities](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#dynamic-plugin-specific-fields-capabilities--runtime-configuration) supported by at least one of the delegates. (NOTE: Multus only supports portMappings/Bandwidth capability for cluster networks). -* [`readinessindicatorfile`](#Default-Network-Readiness-Indicator): The path to a file whose existence denotes that the default network is ready +* [`readinessindicatorfile`](#default-network-readiness-indicator): The path to a file whose existence denotes that the default network is ready message to next when some missing error. Defaults to false. * `systemNamespaces` ([]string, optional): list of namespaces for Kubernetes system (namespaces listed here will not have `defaultNetworks` added) * `multusNamespace` (string, optional): namespace for `clusterNetwork`/`defaultNetworks` (the default value is `kube-system`) -* `retryDeleteOnError` (bool, optional): Enable or disable delegate DEL +* `retryDeleteOnError` (bool, optional): Enable or disable delegate DEL ### Using `clusterNetwork` -Using the `clusterNetwork` option and the `delegates` are **mutually exclusive**. If `clusterNetwork` is set, the `delegates` field is *ignored*. +Using the `clusterNetwork` option and the `delegates` are **mutually exclusive**. If `clusterNetwork` is set, the `delegates` field is *ignored*. You **must** set one or the other. @@ -78,12 +78,12 @@ Therefore: Options: * `clusterNetwork` (string, required if not using `delegates`): the default CNI plugin to be executed. -* `defaultNetworks` ([]string, optional): Additional / secondary network attachment that is always attached to each pod. +* `defaultNetworks` ([]string, optional): Additional / secondary network attachment that is always attached to each pod. The following values are valid for both `clusterNetwork` and `defaultNetworks` and are processed in the following order: * The name of a `NetworkAttachmentDefinition` custom resource in the namespace specified by the `multusNamespace` configuration option -* The `"name"` value in the contents of a CNI JSON configuration file in the CNI configuration directory, +* The `"name"` value in the contents of a CNI JSON configuration file in the CNI configuration directory, * The given name for `clusterNetwork` should match the value for `name` key in the contents of the CNI JSON file (e.g. `"name": "test"` in `my.conf` when `"clusterNetwork": "test"`) * A path to a directory containing CNI json configuration files. The alphabetically first file will be used. * Absolute file path for CNI config file @@ -91,7 +91,7 @@ The following values are valid for both `clusterNetwork` and `defaultNetworks` a If for example you have `defaultNetworks` set as: -``` +```bash "defaultNetworks": ["sidecarNetwork", "exampleNetwork"], ``` @@ -107,7 +107,7 @@ If `clusterNetwork` is not set, you **must** use `delegates`. Example configuration using `delegates`: -``` +```bash { "cniVersion": "0.3.1", "name": "node-cni-network", @@ -142,7 +142,6 @@ Only one option is necessary to configure this functionality: *NOTE*: If `readinessindicatorfile` is unset, or is an empty string, this functionality will be disabled, and is disabled by default. - ### Logging You may wish to enable some enhanced logging for Multus, especially during the process where you're configuring Multus and need to understand what is or isn't working with your particular configuration. @@ -153,7 +152,7 @@ By default, Multus will log via `STDERR`, which is the standard method by which Optionally, you may disable this method by setting the `logToStderr` option in your CNI configuration: -``` +```json "logToStderr": false, ``` @@ -163,7 +162,7 @@ Optionally, you may have Multus log to a file on the filesystem. This file will For example in your CNI configuration, you may set: -``` +```json "logFile": "/var/log/multus.log", ``` @@ -180,7 +179,7 @@ The available logging level values, in decreasing order of verbosity are: You may configure the logging level by using the `LogLevel` option in your CNI configuration. For example: -``` +```json "logLevel": "debug", ``` @@ -195,7 +194,7 @@ If you want a more detailed configuration of the logging, This includes the foll For example in your CNI configuration, you may set: -``` +```json "logOptions": { "maxAge": 5, "maxSize": 100, @@ -206,7 +205,7 @@ For example in your CNI configuration, you may set: ### Namespace Isolation -The functionality provided by the `namespaceIsolation` configuration option enables a mode where Multus only allows pods to access custom resources (the `NetworkAttachmentDefinitions`) within the namespace where that pod resides. In other words, the `NetworkAttachmentDefinitions` are isolated to usage within the namespace in which they're created. +The functionality provided by the `namespaceIsolation` configuration option enables a mode where Multus only allows pods to access custom resources (the `NetworkAttachmentDefinitions`) within the namespace where that pod resides. In other words, the `NetworkAttachmentDefinitions` are isolated to usage within the namespace in which they're created. **NOTE**: The default namespace is special in this scenario. Even with namespace isolation enabled, any pod, in any namespace is allowed to refer to `NetworkAttachmentDefinitions` in the default namespace. This allows you to create commonly used unprivileged `NetworkAttachmentDefinitions` without having to put them in all namespaces. For example, if you had a `NetworkAttachmentDefinition` named `foo` the default namespace, you may reference it in an annotation with: `default/foo`. @@ -220,7 +219,7 @@ Namespace Isolation is disabled by default. #### Configuration example -``` +```json "namespaceIsolation": true, ``` @@ -235,7 +234,7 @@ Given the above scenario with a Junior & Senior Administrator. You may assume th Firstly, we show that we have a number of namespaces available: -``` +```bash # List the available namespaces [user@kube-master ~]$ kubectl get namespaces NAME STATUS AGE @@ -248,7 +247,7 @@ privileged Active 4s We'll create a `NetworkAttachmentDefinition` in the `privileged` namespace. -``` +```bash # Show the network attachment definition we're creating. [user@kube-master ~]$ cat cr.yml apiVersion: "k8s.cni.cncf.io/v1" @@ -285,7 +284,7 @@ macvlan-conf 11s Next, we'll create a pod with an annotation that references the privileged namespace. Pay particular attention to the annotation that reads `k8s.v1.cni.cncf.io/networks: privileged/macvlan-conf` -- where it contains a reference to a `namespace/configuration-name` formatted network attachment name. In this case referring to the `macvlan-conf` in the namespace called `privileged`. -``` +```yaml # Show the yaml for a pod. [user@kube-master ~]$ cat example.pod.yml apiVersion: v1 @@ -307,7 +306,7 @@ pod/samplepod created You'll note that pod fails to spawn successfully. If you check the Multus logs, you'll see an entry such as: -``` +```bash 2018-12-18T21:41:32Z [error] GetNetworkDelegates: namespace isolation enabled, annotation violates permission, pod is in namespace development but refers to target namespace privileged ``` @@ -317,7 +316,7 @@ In a positive example, you'd instead create the `NetworkAttachmentDefinition` in A positive example may be: -``` +```bash # Create the same NetworkAttachmentDefinition as above, however in the development namespace [user@kube-master ~]$ kubectl create -f cr.yml -n development networkattachmentdefinition.k8s.cni.cncf.io/macvlan-conf created @@ -350,7 +349,7 @@ samplepod 1/1 Running 0 31s The `globalNamespaces` configuration option is only used when `namespaceIsolation` is set to true. `globalNamespaces` specifies a comma-delimited list of namespaces which can be referred to from outside of any given namespace in which a pod resides. -``` +```json "globalNamespaces": "default,namespace-a,namespace-b", ``` diff --git a/docs/development.md b/docs/development.md index c688bd719..1ac2b79ec 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,3 +1,5 @@ +# + ## Development/Support Information ## Which Kubernetes version is supported in multus? @@ -15,7 +17,7 @@ hence there is no shell command. If you want to execute shell in multus pod, ple Multus now uses [gopkg.in](http://gopkg.in/) to expose its code as library. You can use following command to import our code into your go code. -``` +```bash go get gopkg.in/k8snetworkplumbingwg/multus-cni.v4 ``` @@ -33,7 +35,7 @@ If an issue is closed that you don't feel is sufficiently resolved, please feel You can use the built in `./hack/build-go.sh` script! -``` +```bash git clone https://github.com/k8snetworkplumbingwg/multus-cni.git cd multus-cni ./hack/build-go.sh @@ -43,7 +45,7 @@ cd multus-cni Multus has go unit tests (based on ginkgo framework).The following commands drive CI tests manually in your environment: -``` +```bash sudo ./hack/test-go.sh ``` @@ -55,7 +57,6 @@ The following are the best practices for multus logging: * In case of error handling, use `logging.Errorf()` with given error info * `logging.Panicf()` only be used for critical errors (it should NOT normally be used) - ## Multus release schedule On the first maintainer's meeting, twice yearly, after January 1st and July 1st, if a new version has not been tagged, a new version will tagged. diff --git a/docs/how-to-use.md b/docs/how-to-use.md index b4cdfc426..299c720f1 100644 --- a/docs/how-to-use.md +++ b/docs/how-to-use.md @@ -1,3 +1,5 @@ +# + ## Multus CNI usage guide ### Prerequisites @@ -11,33 +13,39 @@ Your Kubelet(s) must be configured to run with the CNI network plugin. Please se Generally we recommend two options: Manually place a Multus binary in your `/opt/cni/bin`, or use our [quick-start method](quickstart.md) -- which creates a daemonset that has an opinionated way of how to install & configure Multus CNI (recommended). -*Copy Multus Binary into place* +#### Copy Multus Binary into place You may acquire the Multus binary via compilation (see the [developer guide](development.md)) or download the a binary from the [GitHub releases](https://github.com/k8snetworkplumbingwg/multus-cni/releases) page. Copy multus binary into CNI binary directory, usually `/opt/cni/bin`. Perform this on all nodes in your cluster (master and nodes). +```bash cp multus /opt/cni/bin +``` -*Via Daemonset method* +#### Via Daemonset method As a [quickstart](quickstart.md), you may apply these YAML files. Run this command (typically you would run this on the master, or wherever you have access to the `kubectl` command to manage your cluster). +```bash kubectl apply -f https://raw.githubusercontent.com/k8snetworkplumbingwg/multus-cni/master/deployments/multus-daemonset.yml # thin deployment +``` or +```bash kubectl apply -f https://raw.githubusercontent.com/k8snetworkplumbingwg/multus-cni/master/deployments/multus-daemonset-thick.yml # thick (client/server) deployment +``` -If you need more comprehensive detail, continue along with this guide, otherwise, you may wish to either [follow the quickstart guide]() or skip to the ['Create network attachment definition'](#create-network-attachment-definition) section. +If you need more comprehensive detail, continue along with this guide, otherwise, you may wish to either [follow the quickstart guide](quickstart.md) or skip to the ['Create network attachment definition'](#create-network-attachment-definition) section. ### Set up conf file in /etc/cni/net.d/ (Installed automatically by Daemonset) -**If you use daemonset to install multus, skip this section and go to "Create network attachment"** +#### If you use daemonset to install multus, skip this section and go to "Create network attachment You put CNI config file in `/etc/cni/net.d`. Kubernetes CNI runtime uses the alphabetically first file in the directory. (`"NOTE1"`, `"NOTE2"` are just comments, you can remove them at your configuration) Execute following commands at all Kubernetes nodes (i.e. master and minions) -``` +```bash mkdir -p /etc/cni/net.d cat >/etc/cni/net.d/00-multus.conf < /etc/cni/multus/net.d/macvlan2.conf { @@ -271,7 +279,7 @@ EOF #### Launch pod with text annotation -``` +```bash # Execute following command at Kubernetes master cat </` -``` +```bash # Execute following command at Kubernetes master cat <`. -``` +```bash # Execute following command at Kubernetes master cat <"`. -``` +```bash # Execute following command at Kubernetes master cat <"`. -``` +```bash # Execute following command at Kubernetes master cat <For further information on how to configure SRIOV Device Plugin and SRIOV-CNI please refer to the links given above. diff --git a/images/README.md b/images/README.md index fc31762b8..ec9ee4f96 100644 --- a/images/README.md +++ b/images/README.md @@ -1,11 +1,13 @@ +# + ## Dockerfile build This is used for distribution of Multus in a Docker image. Typically you'd build this from the root of your Multus clone, as such: -``` -$ docker build -t dougbtv/multus -f images/Dockerfile . +```bash +docker build -t dougbtv/multus -f images/Dockerfile . ``` --- @@ -14,8 +16,8 @@ $ docker build -t dougbtv/multus -f images/Dockerfile . You may wish to deploy Multus as a daemonset, you can do so by starting with the example Daemonset shown here: -``` -$ kubectl create -f ./deployments/multus-daemonset.yml +```bash +kubectl create -f ./deployments/multus-daemonset.yml ``` Note: The likely best practice here is to build your own image given the Dockerfile, and then push it to your preferred registry, and change the `image` fields in the Daemonset YAML to reference that image. @@ -28,7 +30,7 @@ The entrypoint takes named parameters for the configuration You can get get help with the `--help` flag. -``` +```bash $ ./entrypoint.sh --help This is an entrypoint script for Multus CNI to overlay its binary and @@ -47,7 +49,7 @@ in lexicographical order in cni-conf-dir). You must use an `=` to delimit the parameter name and the value. For example you may set a custom `cni-conf-dir` like so: -``` +```bash ./entrypoint.sh --cni-conf-dir=/special/path/to/cni/configs/ ``` @@ -59,8 +61,8 @@ Note: You'll noticed that there's a `/host/...` directory from the root for the Example docker run command: -``` -$ docker run -it -v /opt/cni/bin/:/host/opt/cni/bin/ -v /etc/cni/net.d/:/host/etc/cni/net.d/ --entrypoint=/bin/bash dougbtv/multus +```bash +docker run -it -v /opt/cni/bin/:/host/opt/cni/bin/ -v /etc/cni/net.d/:/host/etc/cni/net.d/ --entrypoint=/bin/bash dougbtv/multus ``` Originally inspired by and is a portmanteau of the [Flannel daemonset](https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml), the [Calico Daemonset](https://docs.projectcalico.org/manifests/calico.yaml), and the [Calico CNI install bash script](https://github.com/projectcalico/cni-plugin/blob/be4df4db2e47aa7378b1bdf6933724bac1f348d0/k8s-install/scripts/install-cni.sh#L104-L153).