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 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 BlockIOParameters
  • func NewBlockIOParameters() BlockIOParameters
• type Config
• type DeviceParameters
• type DeviceRate
• type DeviceRates
  • func (r *DeviceRates) Append(maj, min, val int64)
  • func (r *DeviceRates) Update(maj, min, val int64)
• type DeviceWeight
• type DeviceWeights
  • func (w *DeviceWeights) Append(maj, min, val int64)
  • func (w *DeviceWeights) Update(maj, min, val int64)
• 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 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 BlockIOParameters

type BlockIOParameters struct {
	Weight                  int64
	WeightDevice            DeviceWeights
	ThrottleReadBpsDevice   DeviceRates
	ThrottleWriteBpsDevice  DeviceRates
	ThrottleReadIOPSDevice  DeviceRates
	ThrottleWriteIOPSDevice DeviceRates
}

BlockIOParameters contains cgroups blockio controller parameters.

Effects of Weight and Rate values in SetBlkioParameters(): Value | Effect -------+-------------------------------------------------------------------

  -1  |  Do not write to cgroups, value is missing.
   0  |  Write to cgroups, will clear the setting as specified in cgroups blkio interface.
other |  Write to cgroups, sets the value.

func NewBlockIOParameters

func NewBlockIOParameters() BlockIOParameters

NewBlockIOParameters creates new BlockIOParameters instance.

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 DeviceParameters

type DeviceParameters interface {
	Append(maj, min, val int64)
	Update(maj, min, val int64)
}

DeviceParameters interface provides functions common to DeviceWeights and DeviceRates.

type DeviceRate

type DeviceRate struct {
	Major int64
	Minor int64
	Rate  int64
}

DeviceRate contains values for - blkio.throttle.read_bps_device - blkio.throttle.write_bps_device - blkio.throttle.read_iops_device - blkio.throttle.write_iops_device

type DeviceRates

type DeviceRates []DeviceRate

DeviceRates contains throttling rates for devices.

func (*DeviceRates) Append

func (r *DeviceRates) Append(maj, min, val int64)

Append appends (major, minor, value) to DeviceRates slice.

func (*DeviceRates) Update

func (r *DeviceRates) Update(maj, min, val int64)

Update updates device rate in DeviceRates slice, or appends it if not found.

type DeviceWeight

type DeviceWeight struct {
	Major  int64
	Minor  int64
	Weight int64
}

DeviceWeight contains values for - blkio.[io-scheduler].weight

type DeviceWeights

type DeviceWeights []DeviceWeight

DeviceWeights contains weights for devices.

func (*DeviceWeights) Append

func (w *DeviceWeights) Append(maj, min, val int64)

Append appends (major, minor, value) to DeviceWeights slice.

func (*DeviceWeights) Update

func (w *DeviceWeights) Update(maj, min, val int64)

Update updates device weight in DeviceWeights slice, or appends it if not found.

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.