package blockio

import "github.com/intel/goresctrl/pkg/blockio"

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.

Source Files ¶

blockio.go cgroups.go config.go kubernetes.go oci.go