storage

Documentation

Overview

Package storage defines structures and functions relating to charm storage.

Index

• Constants
• func BlockDevicePath(device BlockDevice) (string, error)
• func IsProviderSupported(envType string, providerType ProviderType) bool
• func RegisterEnvironStorageProviders(envType string, providers ...ProviderType)
• func RegisterProvider(providerType ProviderType, p Provider)
• func SortBlockDevices(devices []BlockDevice)
• type BlockDevice
• type Config
  • func NewConfig(name string, provider ProviderType, attrs map[string]interface{}) (*Config, error)
  • func (c *Config) Attrs() map[string]interface{}
  • func (c *Config) Name() string
  • func (c *Config) Provider() ProviderType
  • func (c *Config) ValueString(name string) (string, bool)
• type Constraints
  • func ParseConstraints(s string) (Constraints, error)
• type Provider
  • func StorageProvider(providerType ProviderType) (Provider, error)
• type ProviderType
• type StorageInstance
• type StorageKind
  • func (k StorageKind) String() string
• type VolumeParams
• type VolumeSource

Constants

const FeatureFlag = "storage"

FeatureFlag is the name of the feature for the JUJU_DEV_FEATURE_FLAGS envar. Add this string to the envar to enable support for storage.

Functions

func BlockDevicePath

func BlockDevicePath(device BlockDevice) (string, error)

BlockDevicePath returns the path to a block device, or an error if a path cannot be determined.

The path is only guaranteed to be persistent until the machine reboots or the device is modified (e.g. filesystem destroyed or created).

func IsProviderSupported

func IsProviderSupported(envType string, providerType ProviderType) bool

Returns true is provider is supported for the environment.

func RegisterEnvironStorageProviders

func RegisterEnvironStorageProviders(envType string, providers ...ProviderType)

RegisterEnvironStorageProviders records which storage provider types are valid for an environment. If this is called more than once, the new providers are appended to the current slice.

func RegisterProvider

func RegisterProvider(providerType ProviderType, p Provider)

RegisterProvider registers a new storage provider of the given type.

func SortBlockDevices

func SortBlockDevices(devices []BlockDevice)

SortBlockDevices sorts block devices by device name.

Types

type BlockDevice

type BlockDevice struct {
	// Name is a unique name assigned by Juju to the block device.
	Name string `yaml:"name"`

	// ProviderId is a unique provider-supplied ID for the block device.
	// ProviderId is required to be unique for the lifetime of the block-
	// device, but may be reused.
	ProviderId string `yaml:"providerid"`

	// DeviceName is the block device's OS-specific name (e.g. "sdb").
	DeviceName string `yaml:"devicename,omitempty"`

	// Label is the label for the filesystem on the block device.
	//
	// This will be empty if the block device does not have a filesystem,
	// or if the filesystem is not yet known to Juju.
	Label string `yaml:"label,omitempty"`

	// UUID is a unique identifier for the filesystem on the block device.
	//
	// This will be empty if the block device does not have a filesystem,
	// or if the filesystem is not yet known to Juju.
	//
	// The UUID format is not necessarily uniform; for example, LVM UUIDs
	// differ in format to the standard v4 UUIDs.
	UUID string `yaml:"uuid,omitempty"`

	// Serial is the block device's serial number. Not all block devices
	// have a serial number. This is used to identify a block device if
	// it is available, in preference to UUID or device name, as the serial
	// is immutable.
	Serial string `yaml:"serial,omitempty"`

	// Size is the size of the block device, in MiB.
	Size uint64 `yaml:"size"`

	// FilesystemType is the type of the filesystem present on the block
	// device, if any.
	FilesystemType string `yaml:"fstype,omitempty"`

	// InUse indicates that the block device is in use (e.g. mounted).
	InUse bool `yaml:"inuse"`
}

BlockDevice describes a block device (disk, logical volume, etc.)

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config defines the configuration for a storage source.

func NewConfig

func NewConfig(name string, provider ProviderType, attrs map[string]interface{}) (*Config, error)

NewConfig creates a new Config for instantiating a storage source.

func (*Config) Attrs

func (c *Config) Attrs() map[string]interface{}

Attrs returns the configuration attributes for a storage source.

func (*Config) Name

func (c *Config) Name() string

Name returns the name of a storage source. This is not necessarily unique, and should only be used for informational purposes.

func (*Config) Provider

func (c *Config) Provider() ProviderType

Provider returns the name of a storage provider.

func (*Config) ValueString

func (c *Config) ValueString(name string) (string, bool)

ValueString returns the named config attribute as a string.

type Constraints

type Constraints struct {
	// Pool is the name of the storage pool (ebs, ceph, custompool, ...)
	// that must provide the storage, or "" if the default pool should be
	// used.
	Pool string

	// Size is the minimum size of the storage in MiB.
	Size uint64

	// Count is the number of instances of the storage to create.
	Count uint64
}

Constraints describes a set of storage constraints.

func ParseConstraints

func ParseConstraints(s string) (Constraints, error)

ParseConstraints parses the specified string and creates a Constraints structure.

The acceptable format for storage constraints is a comma separated sequence of: POOL, COUNT, and SIZE, where

POOL identifies the storage pool. POOL can be a string
starting with a letter, followed by zero or more digits
or letters optionally separated by hyphens.

COUNT is a positive integer indicating how many instances
of the storage to create. If unspecified, and SIZE is
specified, COUNT defaults to 1.

SIZE describes the minimum size of the storage instances to
create. SIZE is a floating point number and multiplier from
the set (M, G, T, P, E, Z, Y), which are all treated as
powers of 1024.

type Provider

type Provider interface {
	// VolumeSource returns a VolumeSource given the
	// specified cloud and storage provider configurations.
	//
	// If the storage provider does not support creating volumes as a
	// first-class primitive, then VolumeSource must return an error
	// satisfying errors.IsNotSupported.
	VolumeSource(environConfig *config.Config, providerConfig *Config) (VolumeSource, error)

	// ValidateConfig validates the provided storage provider config,
	// returning an error if it is invalid.
	ValidateConfig(*Config) error
}

Provider is an interface for obtaining storage sources.

func StorageProvider

func StorageProvider(providerType ProviderType) (Provider, error)

StorageProvider returns the previously registered provider with the given type.

type ProviderType

type ProviderType string

ProviderType uniquely identifies a storage provider, such as "ebs" or "loop".

type StorageInstance

type StorageInstance struct {
	// Id is a unique name assigned by Juju to the storage instance.
	Id string `yaml:"id" json:"id"`

	// Kind is the kind of the datastore (block device, filesystem).
	Kind StorageKind `yaml:"kind" json:"kind"`

	// Location is the location relevant to the datastore (block device, filesystem).
	Location string `yaml:"location" json:"location"`
}

StorageInstance describes a storage instance, assigned to a service or unit.

type StorageKind

type StorageKind int

StorageKind defines the type of the datastore: whether it is a raw block device, or a filesystem.

const (
	StorageKindUnknown StorageKind = iota
	StorageKindBlock
	StorageKindFilesystem
)

func (StorageKind) String

func (k StorageKind) String() string

type VolumeParams

type VolumeParams struct {
	// Name is a unique name assigned by Juju for the requested volume.
	Name string

	// Size is the minimum size of the volume in MiB.
	Size uint64

	// Options is a set of provider-specific options for storage creation,
	// as defined in a storage pool.
	Options map[string]interface{}

	// Instance is the ID of the instance that the volume should be attached
	// to initially. This will only be empty if the instance is not yet
	// provisioned, in which case the parameters refer to a volume that is
	// being created in conjunction with the instance.
	Instance instance.Id
}

VolumeParams is a fully specified set of parameters for volume creation, derived from one or more of user-specified storage constraints, a storage pool definition, and charm storage metadata.

type VolumeSource

type VolumeSource interface {
	// CreateVolumes creates volumes with the specified size, in MiB.
	//
	// TODO(axw) CreateVolumes should return something other than
	// []BlockDevice, so we can communicate additional information
	// about the volumes that are not relevant at the attachment
	// level.
	CreateVolumes(params []VolumeParams) ([]BlockDevice, error)

	// DescribeVolumes returns the properties of the volumes with the
	// specified provider volume IDs.
	//
	// TODO(axw) as in CreateVolumes, we should return something other
	// than []BlockDevice here.
	DescribeVolumes(volIds []string) ([]BlockDevice, error)

	// DestroyVolumes destroys the volumes with the specified provider
	// volume IDs.
	DestroyVolumes(volIds []string) error

	// ValidateVolumeParams validates the provided volume creation
	// parameters, returning an error if they are invalid.
	//
	// If the provider is incapable of provisioning volumes separately
	// from machine instances (e.g. MAAS), then ValidateVolumeParams
	// must return an error if params.Instance is non-empty.
	ValidateVolumeParams(params VolumeParams) error

	// AttachVolumes attaches the volumes with the specified provider
	// volume IDs to the instances with the corresponding index.
	//
	// TODO(axw) we need to validate attachment requests prior to
	// recording in state. For example, the ec2 provider must reject
	// an attempt to attach a volume to an instance if they are in
	// different availability zones.
	AttachVolumes(volIds []string, instId []instance.Id) error

	// DetachVolumes detaches the volumes with the specified provider
	// volume IDs from the instances with the corresponding index.
	//
	// TODO(axw) we need to record in state whether or not volumes
	// are detachable, and reject attempts to attach/detach on
	// that basis.
	DetachVolumes(volIds []string, instId []instance.Id) error
}

VolumeSource provides an interface for creating, destroying and describing volumes in the environment. A VolumeSource is configured in a particular way, and corresponds to a storage "pool".