package nri.pkg.api.v1alpha1

Get desktop application:
View/edit binary Protocol Buffers messages

go:plugin type=host

• rpc Log (LogRequest, Empty)

  api.proto:121

  Log displays a log message

  message LogRequest

  api.proto:124

  • 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:137

  • 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:150

  • int32 events = 2

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

• 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:172

  • optional PodSandbox pod = 1

    Pod of container being created.

  • optional Container container = 2

    Container being created.

  message CreateContainerResponse

  api.proto:179

  • 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 Shutdown (Empty, Empty)

  api.proto:85

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

• 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:227

  • 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.

• 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:204

  • optional PodSandbox pod = 1

    Pod of container being stopped.

  • optional Container container = 2

    Container being stopped.

  message StopContainerResponse

  api.proto:211

  • repeated ContainerUpdate update = 1

    Requested updates to containers.

• rpc Synchronize (SynchronizeRequest, SynchronizeResponse)

  api.proto:82

  Synchronize the plugin with the state of the runtime.

  message SynchronizeRequest

  api.proto:156

  • 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:165

  • 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 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:188

  • 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:197

  • repeated ContainerUpdate update = 1

    Requested updates to containers.

  • repeated ContainerEviction evict = 2

    Requested eviction of containers.

• rpc UpdatePodSandbox (UpdatePodSandboxRequest, UpdatePodSandboxResponse)

  api.proto:105

  UpdatePodSandbox relays the corresponding request to the plugin.

  message UpdatePodSandboxRequest

  api.proto:216

  • 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:225

  (message has no fields)

• rpc ValidateContainerAdjustment (ValidateContainerAdjustmentRequest, ValidateContainerAdjustmentResponse)

  api.proto:115

  ValidateContainerAdjustment relays a container adjustment validation request to the plugin. Container creation will fail the plugin rejects the adjustments.

  message ValidateContainerAdjustmentRequest

  api.proto:238

  • optional PodSandbox pod = 1

    Pod of container being adjusted.

  • optional Container container = 2

    Container being adjusted in its pristine state.

  • optional ContainerAdjustment adjust = 3

    Pending container adjustments.

  • repeated ContainerUpdate update = 4

    Pending updates to other containers.

  • optional OwningPlugins owners = 5

    Plugins that made the adjustments and updates.

  • repeated PluginInstance plugins = 6

    Plugins consulted for adjustments and updates.

  message ValidateContainerAdjustmentResponse

  api.proto:258

  • bool reject = 1

  • string reason = 2

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: Container, ContainerAdjustment

• string name = 1

CompoundFieldOwners tracks 'plugin ownership' of compound fields which can be adjusted entry by entry, typically maps or slices. It is used to track ownership for annotations, mounts, devices, environment variables, hugepage limits, etc. The key identifies the owned entry (annotation key, mount destination, device path, environment variable name, etc.). The value is the owning plugin.

Used in: FieldOwners

• map<string, string> owners = 1

Container metadata that is considered relevant for a plugin.

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

• 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

• repeated CDIDevice CDI_devices = 20

• optional User user = 21

Requested adjustments to a container being created.

Used in: CreateContainerResponse, ValidateContainerAdjustmentRequest

• 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, ValidateContainerAdjustmentRequest

• 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

• VALIDATE_CONTAINER_ADJUSTMENT = 14

• LAST = 15

Field enumerates all fields that can be adjusted by plugins.

• None = 0

• Annotations = 1

• Mounts = 2

• OciHooks = 3

• Devices = 4

• CdiDevices = 5

• Env = 6

• Args = 7

• MemLimit = 8

• MemReservation = 9

• MemSwapLimit = 10

• MemKernelLimit = 11

• MemTCPLimit = 12

• MemSwappiness = 13

• MemDisableOomKiller = 14

• MemUseHierarchy = 15

• CPUShares = 16

• CPUQuota = 17

• CPUPeriod = 18

• CPURealtimeRuntime = 19

• CPURealtimePeriod = 20

• CPUSetCPUs = 21

• CPUSetMems = 22

• PidsLimit = 23

• HugepageLimits = 24

• BlockioClass = 25

• RdtClass = 26

• CgroupsUnified = 27

• CgroupsPath = 28

• OomScoreAdj = 29

• Rlimits = 30

• IoPriority = 31

• SeccompPolicy = 32

• Namespace = 33

FieldOwners tracks field 'plugin ownership' for a single container. Keys represent adjustable fields of a container. For simple fields, the value is the plugin that last modified the field. For compound fields, the value is a CompoundFieldOwners which provides tracking 'plugin ownership' per field for compound data, typically maps and slices. Field enum values are used to index both maps, using Key() to get the int32 for the Field.

Used in: OwningPlugins

• map<int32, string> simple = 1

• map<int32, CompoundFieldOwners> compound = 2

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

Used in: LinuxIOPriority

• IOPRIO_CLASS_NONE = 0

• IOPRIO_CLASS_RT = 1

• IOPRIO_CLASS_BE = 2

• IOPRIO_CLASS_IDLE = 3

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

• optional LinuxIOPriority io_priority = 6

• optional SecurityProfile seccomp_profile = 7

• optional LinuxSeccomp seccomp_policy = 8

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

• optional LinuxIOPriority io_priority = 5

• optional LinuxSeccomp seccomp_policy = 6

• repeated LinuxNamespace namespaces = 7

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

Used in: LinuxContainer, LinuxContainerAdjustment

• IOPrioClass class = 1

  Scheduling class of the IO priority.

• int32 priority = 2

  The value of the IO priority.

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, LinuxContainerAdjustment, 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: LinuxContainer, LinuxContainerAdjustment

• string default_action = 1

• optional OptionalUInt32 default_errno = 2

• repeated string architectures = 3

• repeated string flags = 4

• string listener_path = 5

• string listener_metadata = 6

• repeated LinuxSyscall syscalls = 7

Used in: LinuxSyscall

• uint32 index = 1

• uint64 value = 2

• uint64 value_two = 3

• string op = 4

Used in: LinuxSeccomp

• repeated string names = 1

• string action = 2

• optional OptionalUInt32 errno_ret = 3

• repeated LinuxSeccompArg args = 4

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, LinuxSeccomp, LinuxSyscall

• uint32 value = 1

An optional 64-bit unsigned integer value.

Used in: LinuxCPU, LinuxMemory

• uint64 value = 1

OwningPlugins tracks field 'plugin ownership' for multiple containers. The string keys are container IDs. The values are FieldOwners which track 'plugin ownership' per adjustable field for the container.

Used in: ValidateContainerAdjustmentRequest

• map<string, FieldOwners> owners = 1

Container rlimits

Used in: Container, ContainerAdjustment

• string type = 1

• uint64 hard = 2

• uint64 soft = 3

Used in: ValidateContainerAdjustmentRequest

• string name = 1

• string index = 2

Pod metadata that is considered relevant for a plugin.

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

• 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

SecurityProfile for container.

Used in: LinuxContainer

• SecurityProfile.ProfileType profile_type = 1

• string localhost_ref = 2

Used in: SecurityProfile

• RUNTIME_DEFAULT = 0

• UNCONFINED = 1

• LOCALHOST = 2

User and group IDs for the container.

Used in: Container

• uint32 uid = 1

• uint32 gid = 2

• repeated uint32 additional_gids = 3