blockio

Documentation

Overview

Package blockio implements class-based cgroup blockio controller management for containers.

Input: configuration of classes with blockio controller parameters (weights, throttling) for sets of block devices.

Outputs: Option 1: Write blockio parameters of a class to a cgroup directory. Option 2: Return blockio parameters of a class in a OCI LinuxBlockIO

structure, that can be passed to OCI-compliant container
runtime.

Notes:

• Using Weight requires bfq or cfq I/O scheduler to be effective for the block devices where Weight is used.

Configuration example:

Classes:

  # Define a blockio class "LowPrioThrottled".
  # Containers in this class will be throttled and handled as
  # low priority in the I/O scheduler.

  LowPrioThrottled:

    # Weight without a Devices list specifies the default
    # I/O scheduler weight for all devices
    # that are not explicitly mentioned in following items.
    # This will be written to cgroups(.bfq).weight.
    # Weights range from 10 to 1000, the default is 100.

    - Weight: 80

    # Set all parameters for all /dev/sd* and /dev/vd* block
    # devices.

    - Devices:
        - /dev/sd[a-z]
        - /dev/vd[a-z]
      ThrottleReadBps: 50M   # max read bytes per second
      ThrottleWriteBps: 10M  # max write bytes per second
      ThrottleReadIOPS: 10k  # max read io operations per second
      ThrottleWriteIOPS: 5k  # max write io operations per second
      Weight: 50             # I/O scheduler (cfq/bfq) weight for
                             # these devices will be written to
                             # cgroups(.bfq).weight_device

    # Set parameters particularly for SSD devices.
    # This configuration overrides above configurations for those
    # /dev/sd* and /dev/vd* devices whose disk id contains "SSD".

    - Devices:
        - /dev/disk/by-id/*SSD*
      ThrottleReadBps: 100M
      ThrottleWriteBps: 40M
      # Not mentioning Throttle*IOPS means no I/O operations
      # throttling on matching devices.
      Weight: 50

  # Define a blockio class "HighPrioFullSpeed".
  # There is no throttling on these containers, and
  # they will be prioritized by the I/O scheduler.

  HighPrioFullSpeed:
    - Weight: 400

Usage example:

blockio.SetLogger(logrus.New())
if err := blockio.SetConfigFromFile("/etc/containers/blockio.yaml", false); err != nil {
    return err
}
// Output option 1: write directly to cgroup "/mytestgroup"
if err := blockio.SetCgroupClass("/mytestgroup", "LowPrioThrottled"); err != nil {
    return err
}
// Output option 2: OCI LinuxBlockIO of a blockio class
if lbio, err := blockio.OciLinuxBlockIO("LowPrioThrottled"); err != nil {
    return err
} else {
    fmt.Printf("OCI LinuxBlockIO for LowPrioThrottled:\n%+v\n", lbio)
}

Index

• Constants
• func ContainerClassFromAnnotations(containerName string, containerAnnotations, podAnnotations map[string]string) (string, error)
• func GetClasses() []string
• func OciLinuxBlockIO(class string) (*oci.LinuxBlockIO, error)
• func SetCgroupClass(group string, class string) error
• func SetConfig(opt *Config, force bool) error
• func SetConfigFromData(data []byte, force bool) error
• func SetConfigFromFile(filename string, force bool) error
• func SetLogger(l grclog.Logger)
• type Config
• type DevicesParameters

Constants

const (
	// BlockioContainerAnnotation is the CRI level container annotation for setting
	// the blockio class of a container
	BlockioContainerAnnotation = "io.kubernetes.cri.blockio-class"

	// BlockioPodAnnotation is a Pod annotation for setting the blockio class of
	// all containers of the pod
	BlockioPodAnnotation = "blockio.resources.beta.kubernetes.io/pod"

	// BlockioPodAnnotationContainerPrefix is prefix for per-container Pod annotation
	// for setting the blockio class of one container of the pod
	BlockioPodAnnotationContainerPrefix = "blockio.resources.beta.kubernetes.io/container."
)

Functions

func ContainerClassFromAnnotations

func ContainerClassFromAnnotations(containerName string, containerAnnotations, podAnnotations map[string]string) (string, error)

ContainerClassFromAnnotations determines the effective blockio class of a container from the Pod annotations and CRI level container annotations of a container. If the class is not specified by any annotation, returns empty class name. Returned error is reserved (nil).

func GetClasses

func GetClasses() []string

GetClasses returns block I/O class names

func OciLinuxBlockIO

func OciLinuxBlockIO(class string) (*oci.LinuxBlockIO, error)

OciLinuxBlockIO returns OCI LinuxBlockIO structure corresponding to the class.

func SetCgroupClass

func SetCgroupClass(group string, class string) error

SetCgroupClass sets cgroup blkio controller parameters to match blockio class. "group" is the cgroup directory of the container without mountpoint and controller (blkio) directories: "/kubepods/burstable/POD_ID/CONTAINER_ID".

func SetConfig

func SetConfig(opt *Config, force bool) error

SetConfig scans available block devices and applies new configuration.

func SetConfigFromData

func SetConfigFromData(data []byte, force bool) error

SetConfigFromData parses and applies configuration from data.

func SetConfigFromFile

func SetConfigFromFile(filename string, force bool) error

SetConfigFromFile reads and applies blockio configuration from the filesystem.

func SetLogger

func SetLogger(l grclog.Logger)

SetLogger sets the logger instance to be used by the package. Examples:

// Log to standard logger:
stdlog := log.New(os.Stderr, "blockio:", 0)
blockio.SetLogger(goresctrllog.NewLoggerWrapper(stdlog))
// Log to logrus:
blockio.SetLogger(logrus.New())

Types

type Config

type Config struct {
	// Classes define weights and throttling parameters for sets of devices.
	Classes map[string][]DevicesParameters `json:",omitempty"`
}

Config contains a blockio configuration.

type DevicesParameters

type DevicesParameters struct {
	Devices           []string `json:",omitempty"`
	ThrottleReadBps   string   `json:",omitempty"`
	ThrottleWriteBps  string   `json:",omitempty"`
	ThrottleReadIOPS  string   `json:",omitempty"`
	ThrottleWriteIOPS string   `json:",omitempty"`
	Weight            string   `json:",omitempty"`
}

DevicesParameters defines Block IO parameters for a set of devices.