package nri.pkg.api.v1alpha1

Get desktop application:
View/edit binary Protocol Buffers messages

go:plugin type=host

• rpc Log (LogRequest, Empty)

  api.proto:117

  Log displays a log message

  message LogRequest

  api.proto:120

  • string msg = 1

  • LogRequest.Level level = 2

Plugin is the API NRI uses to interact with plugins. It is used to - configure a plugin and subscribe it for lifecycle events - synchronize the state of a plugin with that of the runtime - hook a plugin into the lifecycle events of its interest During configuration the plugin tells the runtime which lifecycle events it wishes to get hooked into. Once configured, the plugin is synchronized with the runtime by receiving the list of pods and containers known to the runtime. The plugin can request changes to any of the containers in response. After initial synchronization the plugin starts receiving the events it subscribed for as they occur in the runtime. For container creation, update, and stop events, the plugin can request changes, both to the container that triggered the event or any other existing container in the runtime. For a subset of the container lifecycle events, NRI defines an additional Post-variant of the event. These variants are defined for CreateContainer, StartContainer, and UpdateContainer. For creation and update, these events can be used by plugins to discover the full extent of changes applied to the container, including any changes made by other active plugins. go:plugin type=plugin version=1

• rpc Configure (ConfigureRequest, ConfigureResponse)

  api.proto:79

  Configure the plugin and get its event subscription.

  message ConfigureRequest

  api.proto:133

  • string config = 1

    Any plugin-specific data, if present among the NRI configuration.

  • string runtime_name = 2

    Name of the runtime NRI is running in.

  • string runtime_version = 3

    Version of the runtime NRI is running in.

  • int64 registration_timeout = 4

    Configured registration timeout in milliseconds.

  • int64 request_timeout = 5

    Configured request processing timeout in milliseconds.

  message ConfigureResponse

  api.proto:146

  • int32 events = 2

    Events to subscribe the plugin for. Each bit set corresponds to an enumerated Event.

• rpc Synchronize (SynchronizeRequest, SynchronizeResponse)

  api.proto:82

  Synchronize the plugin with the state of the runtime.

  message SynchronizeRequest

  api.proto:152

  • repeated PodSandbox pods = 1

    Pods known to the runtime.

  • repeated Container containers = 2

    Containers known to the runtime.

  • bool more = 3

    Whether there are more pods and containers to follow.

  message SynchronizeResponse

  api.proto:161

  • repeated ContainerUpdate update = 1

    Updates to containers requested by the plugin.

  • bool more = 2

    Whether the client is able to handle more advertised pods and containers.

• rpc Shutdown (Empty, Empty)

  api.proto:85

  Shutdown a plugin (let it know the runtime is going down).

• rpc CreateContainer (CreateContainerRequest, CreateContainerResponse)

  api.proto:93

  CreateContainer relays the corresponding request to the plugin. In response, the plugin can adjust the container being created, and update other containers in the runtime. Container adjustment can alter labels, annotations, mounts, devices, environment variables, OCI hooks, and assigned container resources. Updates can alter assigned container resources.

  message CreateContainerRequest

  api.proto:168

  • optional PodSandbox pod = 1

    Pod of container being created.

  • optional Container container = 2

    Container being created.

  message CreateContainerResponse

  api.proto:175

  • optional ContainerAdjustment adjust = 1

    Requested adjustments to container being created.

  • repeated ContainerUpdate update = 2

    Requested updates to other existing containers.

  • repeated ContainerEviction evict = 3

    Requested eviction of existing containers.

• rpc UpdateContainer (UpdateContainerRequest, UpdateContainerResponse)

  api.proto:98

  UpdateContainer relays the corresponding request to the plugin. The plugin can alter how the container is updated and request updates to additional containers in the runtime.

  message UpdateContainerRequest

  api.proto:184

  • optional PodSandbox pod = 1

    Pod of container being updated.

  • optional Container container = 2

    Container being updated.

  • optional LinuxResources linux_resources = 3

    Resources to update.

  message UpdateContainerResponse

  api.proto:193

  • repeated ContainerUpdate update = 1

    Requested updates to containers.

  • repeated ContainerEviction evict = 2

    Requested eviction of containers.

• rpc StopContainer (StopContainerRequest, StopContainerResponse)

  api.proto:102

  StopContainer relays the corresponding request to the plugin. The plugin can update any of the remaining containers in the runtime in response.

  message StopContainerRequest

  api.proto:200

  • optional PodSandbox pod = 1

    Pod of container being stopped.

  • optional Container container = 2

    Container being stopped.

  message StopContainerResponse

  api.proto:207

  • repeated ContainerUpdate update = 1

    Requested updates to containers.

• rpc UpdatePodSandbox (UpdatePodSandboxRequest, UpdatePodSandboxResponse)

  api.proto:105

  UpdatePodSandbox relays the corresponding request to the plugin.

  message UpdatePodSandboxRequest

  api.proto:212

  • optional PodSandbox pod = 1

    Pod being updated.

  • optional LinuxResources overhead_linux_resources = 2

    Overhead associated with this pod.

  • optional LinuxResources linux_resources = 3

    Sum of container resources for this pod.

  message UpdatePodSandboxResponse

  api.proto:221

  (message has no fields)

• rpc StateChange (StateChangeEvent, Empty)

  api.proto:111

  StateChange relays any remaining pod or container lifecycle/state change events the plugin has subscribed for. These can be used to trigger any plugin-specific processing which needs to occur in connection with any of these events.

  message StateChangeEvent

  api.proto:223

  • Event event = 1

    Event type of notification.

  • optional PodSandbox pod = 2

    Pod this notification is sent for. If this event is related to a container, pod is set to the pod of the container.

  • optional Container container = 3

    Container this notification is sent for. If the event is related to a pod, container is nil.

Runtime service is the public API runtimes expose for NRI plugins. On this interface RPC requests are initiated by the plugin. This only covers plugin registration and unsolicited container updates. The rest of the API is defined by the Plugin service.

• rpc RegisterPlugin (RegisterPluginRequest, Empty)

  api.proto:29

  RegisterPlugin registers the plugin with the runtime.

  message RegisterPluginRequest

  api.proto:34

  • string plugin_name = 1

    Name of the plugin to register.

  • string plugin_idx = 2

    Plugin invocation index. Plugins are called in ascending index order.

• rpc UpdateContainers (UpdateContainersRequest, UpdateContainersResponse)

  api.proto:31

  UpdateContainers requests unsolicited updates to a set of containers.

  message UpdateContainersRequest

  api.proto:41

  • repeated ContainerUpdate update = 1

    List of containers to update.

  • repeated ContainerEviction evict = 2

    List of containers to evict.

  message UpdateContainersResponse

  api.proto:48

  • repeated ContainerUpdate failed = 1

    Containers that the runtime failed to update.

A CDI device reference.

Used in: ContainerAdjustment

• string name = 1

Container metadata that is considered relevant for a plugin.

Used in: CreateContainerRequest, StateChangeEvent, StopContainerRequest, SynchronizeRequest, UpdateContainerRequest

• string id = 1

• string pod_sandbox_id = 2

• string name = 3

• ContainerState state = 4

• map<string, string> labels = 5

• map<string, string> annotations = 6

• repeated string args = 7

• repeated string env = 8

• repeated Mount mounts = 9

• optional Hooks hooks = 10

• optional LinuxContainer linux = 11

• uint32 pid = 12

  for NRI v1 emulation

• repeated POSIXRlimit rlimits = 13

• int64 created_at = 14

• int64 started_at = 15

• int64 finished_at = 16

• int32 exit_code = 17

• string status_reason = 18

• string status_message = 19

Requested adjustments to a container being created.

Used in: CreateContainerResponse

• map<string, string> annotations = 2

• repeated Mount mounts = 3

• repeated KeyValue env = 4

• optional Hooks hooks = 5

• optional LinuxContainerAdjustment linux = 6

• repeated POSIXRlimit rlimits = 7

• repeated CDIDevice CDI_devices = 8

• repeated string args = 9

Request to evict (IOW unsolicitedly stop) a container.

Used in: CreateContainerResponse, UpdateContainerResponse, UpdateContainersRequest

• string container_id = 1

  Container to evict.

• string reason = 2

  Human-readable reason for eviction.

Possible container states.

Used in: Container

• CONTAINER_UNKNOWN = 0

• CONTAINER_CREATED = 1

• CONTAINER_PAUSED = 2

  is this useful/necessary ?

• CONTAINER_RUNNING = 3

• CONTAINER_STOPPED = 4

Requested update to an already created container.

Used in: CreateContainerResponse, StopContainerResponse, SynchronizeResponse, UpdateContainerResponse, UpdateContainersRequest, UpdateContainersResponse

• string container_id = 1

• optional LinuxContainerUpdate linux = 2

• bool ignore_failure = 3

Empty response for those *Requests that are semantically events.

Used as request type in: Plugin.Shutdown

Used as response type in: HostFunctions.Log, Plugin.Shutdown, Plugin.StateChange, Runtime.RegisterPlugin

(message has no fields)

Events that plugins can subscribe to in ConfigureResponse.

Used in: StateChangeEvent

• UNKNOWN = 0

• RUN_POD_SANDBOX = 1

• STOP_POD_SANDBOX = 2

• REMOVE_POD_SANDBOX = 3

• CREATE_CONTAINER = 4

• POST_CREATE_CONTAINER = 5

• START_CONTAINER = 6

• POST_START_CONTAINER = 7

• UPDATE_CONTAINER = 8

• POST_UPDATE_CONTAINER = 9

• STOP_CONTAINER = 10

• REMOVE_CONTAINER = 11

• UPDATE_POD_SANDBOX = 12

• POST_UPDATE_POD_SANDBOX = 13

• LAST = 14

One OCI hook.

Used in: Hooks

• string path = 1

• repeated string args = 2

• repeated string env = 3

• optional OptionalInt timeout = 4

Container OCI hooks.

Used in: Container, ContainerAdjustment

• repeated Hook prestart = 1

• repeated Hook create_runtime = 2

• repeated Hook create_container = 3

• repeated Hook start_container = 4

• repeated Hook poststart = 5

• repeated Hook poststop = 6

Container huge page limit.

Used in: LinuxResources

• string page_size = 1

• uint64 limit = 2

KeyValue represents an environment variable.

Used in: ContainerAdjustment

• string key = 1

• string value = 2

CPU-related parts of (linux) resources.

Used in: LinuxResources

• optional OptionalUInt64 shares = 1

• optional OptionalInt64 quota = 2

• optional OptionalUInt64 period = 3

• optional OptionalInt64 realtime_runtime = 4

• optional OptionalUInt64 realtime_period = 5

• string cpus = 6

• string mems = 7

Container (linux) metadata.

Used in: Container

• repeated LinuxNamespace namespaces = 1

• repeated LinuxDevice devices = 2

• optional LinuxResources resources = 3

• optional OptionalInt oom_score_adj = 4

• string cgroups_path = 5

Adjustments to (linux) resources.

Used in: ContainerAdjustment

• repeated LinuxDevice devices = 1

• optional LinuxResources resources = 2

• string cgroups_path = 3

• optional OptionalInt oom_score_adj = 4

Updates to (linux) resources.

Used in: ContainerUpdate

• optional LinuxResources resources = 1

A container (linux) device.

Used in: LinuxContainer, LinuxContainerAdjustment

• string path = 1

• string type = 2

• int64 major = 3

• int64 minor = 4

• optional OptionalFileMode file_mode = 5

• optional OptionalUInt32 uid = 6

• optional OptionalUInt32 gid = 7

A linux device cgroup controller rule.

Used in: LinuxResources

• bool allow = 1

• string type = 2

• optional OptionalInt64 major = 3

• optional OptionalInt64 minor = 4

• string access = 5

Memory-related parts of (linux) resources.

Used in: LinuxResources

• optional OptionalInt64 limit = 1

• optional OptionalInt64 reservation = 2

• optional OptionalInt64 swap = 3

• optional OptionalInt64 kernel = 4

• optional OptionalInt64 kernel_tcp = 5

• optional OptionalUInt64 swappiness = 6

• optional OptionalBool disable_oom_killer = 7

• optional OptionalBool use_hierarchy = 8

A linux namespace.

Used in: LinuxContainer, LinuxPodSandbox

• string type = 1

• string path = 2

Pids-related parts of (linux) resources.

Used in: LinuxResources

• int64 limit = 1

PodSandbox linux-specific metadata

Used in: PodSandbox

• optional LinuxResources pod_overhead = 1

• optional LinuxResources pod_resources = 2

• string cgroup_parent = 3

• string cgroups_path = 4

  for NRI v1 emulation

• repeated LinuxNamespace namespaces = 5

  for NRI v1 emulation

• optional LinuxResources resources = 6

  for NRI v1 emulation

Container (linux) resources.

Used in: LinuxContainer, LinuxContainerAdjustment, LinuxContainerUpdate, LinuxPodSandbox, UpdateContainerRequest, UpdatePodSandboxRequest

• optional LinuxMemory memory = 1

• optional LinuxCPU cpu = 2

• repeated HugepageLimit hugepage_limits = 3

• optional OptionalString blockio_class = 4

• optional OptionalString rdt_class = 5

• map<string, string> unified = 6

• repeated LinuxDeviceCgroup devices = 7

  for NRI v1 emulation

• optional LinuxPids pids = 8

Used in: LogRequest

• LEVEL_UNSPECIFIED = 0

• LEVEL_DEBUG = 1

• LEVEL_INFO = 2

• LEVEL_WARN = 3

• LEVEL_ERROR = 4

A container mount.

Used in: Container, ContainerAdjustment

• string destination = 1

• string type = 2

• string source = 3

• repeated string options = 4

An optional boolean value.

Used in: LinuxMemory

• bool value = 1

An optional value of file permissions.

Used in: LinuxDevice

• uint32 value = 1

An optional signed integer value.

Used in: Hook, LinuxContainer, LinuxContainerAdjustment

• int64 value = 1

An optional 32-bit signed integer value.

• int32 value = 1

An optional 64-bit signed integer value.

Used in: LinuxCPU, LinuxDeviceCgroup, LinuxMemory

• int64 value = 1

An optional string value.

Used in: LinuxResources

• string value = 1

An optional 32-bit unsigned integer value.

Used in: LinuxDevice

• uint32 value = 1

An optional 64-bit unsigned integer value.

Used in: LinuxCPU, LinuxMemory

• uint64 value = 1

Container rlimits

Used in: Container, ContainerAdjustment

• string type = 1

• uint64 hard = 2

• uint64 soft = 3

Pod metadata that is considered relevant for a plugin.

Used in: CreateContainerRequest, StateChangeEvent, StopContainerRequest, SynchronizeRequest, UpdateContainerRequest, UpdatePodSandboxRequest

• string id = 1

• string name = 2

• string uid = 3

• string namespace = 4

• map<string, string> labels = 5

• map<string, string> annotations = 6

• string runtime_handler = 7

• optional LinuxPodSandbox linux = 8

• uint32 pid = 9

  for NRI v1 emulation

• repeated string ips = 10