Merge pull request #178 from chrishenzie/revert-pr-154

Revert "move packages related to v0.1.0 to the plugins/v010-adapter"

Author: samuelkarp

README-v0.1.0.md

@@ -1,2 +1,110 @@
-original v0.1.0 CLI invoke style version of NRI has been moved
-[v0.1.0 docs](/plugins/v010-adapter/0.1.0/README.md)
+# nri - Node Resource Interface
+
+*This version of NRI is supported through the included v010-adapter plugin.*
+
+This project is a WIP for a new, CNI like, interface for managing resources on a node for Pods and Containers.
+
+## Documentation
+
+The basic interface, concepts and plugin design of the Container Network Interface (CNI) is an elegant way to handle multiple implementations of the network stack for containers.
+This concept can be used for additional interfaces to customize a container's runtime environment.
+This proposal covers a new interface for resource management on a node with a structured API and plugin design for containers.
+
+## Lifecycle
+
+The big selling point for CNI is that it has a structured interface for modifying the network namespace for a container.
+This is different from generic hooks as they lack a type safe API injected into the lifecycle of a container.
+The lifecycle point that CNI and NRI plugins will be injected into is the point between `Create` and `Start` of the container's init process.
+
+`Create->NRI->Start`
+
+## Configuration
+
+Configuration is split into two parts.  One is the payload that is specific to a plugin invocation while the second is the host level configuration and options that specify what plugins to run and provide additional configuration to a plugin.
+
+### Filepath and Binaries
+
+Plugin binary paths can be configured via the consumer but will default to `/opt/nri/bin`.
+Binaries are named with their type as the binary name, same as the CNI plugin naming scheme.
+
+### Host Level Config
+
+The config's default location will be `/etc/nri/resource.d/*.conf`.
+
+```json
+{
+  "version": "0.1",
+  "plugins": [
+    {
+      "type": "konfine",
+      "conf": {
+        "systemReserved": [0, 1]
+      }
+    },
+    {
+      "type": "clearcfs"
+    }
+  ]
+}
+```
+
+### Input
+
+Input to a plugin is provided via `STDIN` as a `json` payload.
+
+```json
+{
+  "version": "0.1",
+  "state": "create",
+  "id": "redis",
+  "pid": 1234,
+  "spec": {
+    "resources": {},
+    "cgroupsPath": "default/redis",
+    "namespaces": {
+      "pid": "/proc/44/ns/pid",
+      "mount": "/proc/44/ns/mnt",
+      "net": "/proc/44/ns/net"
+    },
+    "annotations": {
+      "qos.class": "ls"
+    }
+  }
+}
+```
+
+### Output
+
+```json
+{
+  "version": "0.1",
+  "state": "create",
+  "id": "redis",
+  "pid": 1234,
+  "cgroupsPath": "qos-ls/default/redis"
+}
+```
+
+## Commands
+
+*  Invoke - provides invocations into different lifecycle changes of a container
+	- states: `setup|pause|resume|update|delete`
+
+## Packages
+
+A Go based API and client package will be created for both producers of plugins and consumers, commonly being the container runtime (containerd).
+
+### Sample Plugin
+
+* [clearcfs](examples/clearcfs/main.go)
+
+## Project details
+
+nri is a containerd sub-project, licensed under the [Apache 2.0 license](./LICENSE).
+As a containerd sub-project, you will find the:
+
+ * [Project governance](https://github.com/containerd/project/blob/main/GOVERNANCE.md),
+ * [Maintainers](https://github.com/containerd/project/blob/main/MAINTAINERS),
+ * and [Contributing guidelines](https://github.com/containerd/project/blob/main/CONTRIBUTING.md)
+
+information in our [`containerd/project`](https://github.com/containerd/project) repository.

README.md

@@ -23,15 +23,25 @@ The goal is to enable NRI support in the most commonly used OCI runtimes,
 [containerd](https://github.com/containerd/containerd) and
 [CRI-O](https://github.com/cri-o/cri-o).
 
-### Plugins
-Plugins in NRI are daemon-like entities. A single instance of a plugin is
-responsible for handling the full stream of NRI events and requests.
-A unix-domain socket is used as the transport for communication.
+## Background
+
+The revisited API is a major rewrite of NRI. It changes the scope of NRI
+and how it gets integrated into runtimes. It reworks how plugins are
+implemented, how they communicate with the runtime, and what kind of
+changes they can make to containers.
 
-NRI is defined as a formal, protobuf-based 'NRI plugin protocol' which is
-compiled into ttRPC bindings. This should result in improved communication
-efficiency with lower per-message overhead, and enable straightforward
-implementation of stateful NRI plugins.
+[NRI v0.1.0](README-v0.1.0.md) used an OCI hook-like one-shot plugin invocation
+mechanism where a separate instance of a plugin was spawned for every NRI
+event. This instance then used its standard input and output to receive a
+request and provide a response, both as JSON data.
+
+Plugins in NRI are daemon-like entities. A single instance of a plugin is
+now responsible for handling the full stream of NRI events and requests. A
+unix-domain socket is used as the transport for communication. Instead of
+JSON requests and responses NRI is defined as a formal, protobuf-based
+'NRI plugin protocol' which is compiled into ttRPC bindings. This should
+result in improved communication efficiency with lower per-message overhead,
+and enable straightforward implementation of stateful NRI plugins.
 
 ## Components
 

plugins/v010-adapter/0.1.0/client.go renamed to client.go

@@ -25,7 +25,7 @@ import (
 	"os/exec"
 	"sync"
 
-	types "github.com/containerd/nri/plugins/v010-adapter/0.1.0/types/v1"
+	types "github.com/containerd/nri/types/v1"
 
 	oci "github.com/opencontainers/runtime-spec/specs-go"
 )
@@ -42,6 +42,8 @@ const (
 var appendPathOnce sync.Once
 
 // New nri client
+//
+// Deprecated: NRI 0.1.0-style plugins should only be used through the v010-adapter plugin
 func New() (*Client, error) {
 	conf, err := loadConfig(DefaultConfPath)
 	if err != nil {
@@ -60,12 +62,28 @@ func New() (*Client, error) {
 	}, nil
 }
 
+// Plugins returns a slice of the configured plugin names. This can be used by
+// the runtime to detect which plugins are configured.
+//
+// Deprecated: NRI 0.1.0-style plugins should only be used through the v010-adapter plugin
+func (c *Client) Plugins() []string {
+	names := make([]string, 0)
+	for _, p := range c.conf.Plugins {
+		names = append(names, p.Type)
+	}
+	return names
+}
+
 // Client for calling nri plugins
+//
+// Deprecated: NRI 0.1.0-style plugins should only be used through the v010-adapter plugin
 type Client struct {
 	conf *types.ConfigList
 }
 
 // Sandbox information
+//
+// Deprecated: NRI 0.1.0-style plugins should only be used through the v010-adapter plugin
 type Sandbox struct {
 	// ID of the sandbox
 	ID string
@@ -82,6 +100,8 @@ type process interface {
 }
 
 // Task is a subset of containerd's Task interface.
+//
+// Deprecated: NRI 0.1.0-style plugins should only be used through the v010-adapter plugin
 type Task interface {
 	process
 
@@ -90,11 +110,15 @@ type Task interface {
 }
 
 // Invoke the ConfList of nri plugins
+//
+// Deprecated: NRI 0.1.0-style plugins should only be used through the v010-adapter plugin
 func (c *Client) Invoke(ctx context.Context, task Task, state types.State) ([]*types.Result, error) {
 	return c.InvokeWithSandbox(ctx, task, state, nil)
 }
 
 // InvokeWithSandbox invokes the ConfList of nri plugins
+//
+// Deprecated: NRI 0.1.0-style plugins should only be used through the v010-adapter plugin
 func (c *Client) InvokeWithSandbox(ctx context.Context, task Task, state types.State, sandbox *Sandbox) ([]*types.Result, error) {
 	if len(c.conf.Plugins) == 0 {
 		return nil, nil
@@ -129,7 +153,7 @@ func (c *Client) InvokeWithSandbox(ctx context.Context, task Task, state types.S
 	return r.Results, nil
 }
 
-func (c *Client) invokePlugin(ctx context.Context, name string, r *types.Request) (*types.Result, error) {
+func (c *Client) invokePlugin(ctx context.Context, name string, r *types.Request) (*types.Result, error) { //nolint:staticcheck
 	payload, err := json.Marshal(r)
 	if err != nil {
 		return nil, err
@@ -154,28 +178,28 @@ func (c *Client) invokePlugin(ctx context.Context, name string, r *types.Request
 			return nil, err
 		}
 	}
-	var result types.Result
+	var result types.Result //nolint:staticcheck
 	if err := json.Unmarshal(out, &result); err != nil {
 		return nil, fmt.Errorf("failed to unmarshal plugin output %s: %w", msg, err)
 	}
-	if result.Err() != nil {
-		return nil, result.Err()
+	if result.Err() != nil { //nolint:staticcheck
+		return nil, result.Err() //nolint:staticcheck
 	}
 	return &result, nil
 }
 
-func loadConfig(path string) (*types.ConfigList, error) {
+func loadConfig(path string) (*types.ConfigList, error) { //nolint:staticcheck
 	f, err := os.Open(path)
 	if err != nil {
 		// if we don't have a config list on disk, create a new one for use
 		if os.IsNotExist(err) {
-			return &types.ConfigList{
+			return &types.ConfigList{ //nolint:staticcheck
 				Version: Version,
 			}, nil
 		}
 		return nil, err
 	}
-	var c types.ConfigList
+	var c types.ConfigList //nolint:staticcheck
 	err = json.NewDecoder(f).Decode(&c)
 	f.Close()
 	if err != nil {
@@ -184,8 +208,8 @@ func loadConfig(path string) (*types.ConfigList, error) {
 	return &c, nil
 }
 
-func createSpec(spec *oci.Spec) (*types.Spec, error) {
-	s := types.Spec{
+func createSpec(spec *oci.Spec) (*types.Spec, error) { //nolint:staticcheck
+	s := types.Spec{ //nolint:staticcheck
 		Namespaces:  make(map[string]string),
 		Annotations: spec.Annotations,
 	}

examples/clearcfs/main.go

@@ -0,0 +1,70 @@
+/*
+   Copyright The containerd Authors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/containerd/cgroups"
+	"github.com/containerd/nri/skel"
+	types "github.com/containerd/nri/types/v1"
+	"github.com/opencontainers/runtime-spec/specs-go"
+	"github.com/sirupsen/logrus"
+)
+
+// clearCFS clears any cfs quotas for the containers
+type clearCFS struct {
+}
+
+func (c *clearCFS) Type() string {
+	return "clearcfs"
+}
+
+func (c *clearCFS) Invoke(ctx context.Context, r *types.Request) (*types.Result, error) {
+	result := r.NewResult(c.Type())
+
+	if r.State != types.Create {
+		return result, nil
+	}
+
+	switch r.Spec.Annotations["qos.class"] {
+	case "ls":
+		logrus.Debugf("clearing cfs for %s", r.ID)
+		control, err := cgroups.Load(cgroups.V1, cgroups.StaticPath(r.Spec.CgroupsPath))
+		if err != nil {
+			return nil, err
+		}
+
+		quota := int64(-1)
+		return result, control.Update(&specs.LinuxResources{
+			CPU: &specs.LinuxCPU{
+				Quota: &quota,
+			},
+		})
+	}
+	return result, nil
+}
+
+func main() {
+	ctx := context.Background()
+	if err := skel.Run(ctx, &clearCFS{}); err != nil {
+		fmt.Fprintf(os.Stderr, "%s", err)
+		os.Exit(1)
+	}
+}

examples/go.mod

@@ -0,0 +1,20 @@
+module github.com/containerd/nri/examples
+
+go 1.22.0
+
+require (
+	github.com/containerd/cgroups v1.0.3
+	github.com/containerd/nri v0.1.0
+	github.com/opencontainers/runtime-spec v1.1.0
+	github.com/sirupsen/logrus v1.9.3
+)
+
+require (
+	github.com/coreos/go-systemd/v22 v22.3.2 // indirect
+	github.com/docker/go-units v0.4.0 // indirect
+	github.com/godbus/dbus/v5 v5.0.4 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	golang.org/x/sys v0.21.0 // indirect
+)
+
+replace github.com/containerd/nri => ../