Documentation

Overview

Package storage defines structures and functions relating to charm storage.

Index

Constants

View Source
const (
	// ConfigStorageDir is the path to the directory which a
	// machine-scoped storage source may use to contain storage
	// artifacts. This should not be used for environment-wide
	// storage sources, as the contents are bound to the
	// lifetime of the machine.
	//
	// ConfigStorageDir is set by the storage provisioner, so
	// should not be relied upon until a storage source is
	// constructed.
	ConfigStorageDir = "storage-dir"
)

Variables

This section is empty.

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 based on the hardware ID, if available; the first value in device.DeviceLinks, if non-empty; otherwise the device name.

func IsValidPoolName

func IsValidPoolName(s string) bool

IsValidPoolName checks if given string is a valid pool name.

func ParseConstraintsMap

func ParseConstraintsMap(args []string, mustHaveConstraints bool) (map[string]Constraints, error)

ParseConstraintsMap parses string representation of storage constraints into a map keyed on storage names with constraints as values.

Storage constraints may be specified as

<name>=<constraints>

or as

<name>

where latter is equivalent to <name>=1.

Duplicate storage names cause an error to be returned. Constraints presence can be enforced.

func SortBlockDevices

func SortBlockDevices(devices []BlockDevice)

SortBlockDevices sorts block devices by device name.

Types

type AttachFilesystemsResult

type AttachFilesystemsResult struct {
	FilesystemAttachment *FilesystemAttachment
	Error                error
}

AttachFilesystemsResult contains the result of a FilesystemSource.AttachFilesystems call for one filesystem. FilesystemAttachment should only be used if Error is nil.

type AttachVolumesResult

type AttachVolumesResult struct {
	VolumeAttachment *VolumeAttachment
	Error            error
}

AttachVolumesResult contains the result of a VolumeSource.AttachVolumes call for one volume. VolumeAttachment should only be used if Error is nil.

type AttachmentParams

type AttachmentParams struct {
	// Provider is the name of the storage provider that is to be used to
	// create the attachment.
	Provider ProviderType

	// Machine is the tag of the Juju machine that the storage should be
	// attached to. Storage providers may use this to perform machine-
	// specific operations, such as configuring access controls for the
	// machine.
	Machine names.MachineTag

	// InstanceId is the ID of the cloud instance that the storage should
	// be attached to. This will only be of interest to storage providers
	// that interact with the instances, such as EBS/EC2. The InstanceId
	// field will be empty if the instance is not yet provisioned.
	InstanceId instance.Id

	// ReadOnly indicates that the storage should be attached as read-only.
	ReadOnly bool
}

AttachmentParams describes the parameters for attaching a volume or filesystem to a machine.

type BlockDevice

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

	// DeviceLinks is a collection of symlinks to the block device
	// that the OS maintains (e.g. "/dev/disk/by-id/..."). Storage
	// provisioners can match volume attachments to device links if
	// they know ahead of time how the OS will name them.
	DeviceLinks []string `yaml:"devicelinks,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"`

	// HardwareId is the block device's hardware ID, which is composed of
	// a serial number, vendor and model name. Not all block devices have
	// these properties, so HardwareId may be empty. This is used to identify
	// a block device if it is available, in preference to UUID or device
	// name, as the hardware ID is immutable.
	HardwareId string `yaml:"hardwareid,omitempty"`

	// BusAddress is the bus address: where the block device is attached
	// to the machine. This is currently only populated for disks attached
	// to the SCSI bus.
	//
	// The format for this is <bus>@<bus-specific-address> as according to
	// "lshw -businfo". For example, for a SCSI disk with Host=1, Bus=2,
	// Target=3, Lun=4, we populate this field with "scsi@1:2.3.4".
	BusAddress string `yaml:"busaddress,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"`

	// MountPoint is the path at which the block devices is mounted.
	MountPoint string `yaml:"mountpoint,omitempty"`
}

BlockDevice describes a block device discovered on a machine.

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 CreateFilesystemsResult

type CreateFilesystemsResult struct {
	Filesystem *Filesystem
	Error      error
}

CreateFilesystemsResult contains the result of a FilesystemSource.CreateFilesystems call for one filesystem. Filesystem should only be used if Error is nil.

type CreateVolumesResult

type CreateVolumesResult struct {
	Volume           *Volume
	VolumeAttachment *VolumeAttachment
	Error            error
}

CreateVolumesResult contains the result of a VolumeSource.CreateVolumes call for one volume. Volume and VolumeAttachment should only be used if Error is nil.

type DescribeFilesystemsResult

type DescribeFilesystemsResult struct {
	FilesystemInfo *FilesystemInfo
	Error          error
}

DescribeFilesystemsResult contains the result of a FilesystemSource.DescribeFilesystems call for one filesystem. Filesystem should only be used if Error is nil.

type DescribeVolumesResult

type DescribeVolumesResult struct {
	VolumeInfo *VolumeInfo
	Error      error
}

DescribeVolumesResult contains the result of a VolumeSource.DescribeVolumes call for one volume. Volume should only be used if Error is nil.

type Filesystem

type Filesystem struct {
	// Tag is a unique name assigned by Juju to the filesystem.
	Tag names.FilesystemTag

	// Volume is the tag of the volume that backs the filesystem, if any.
	Volume names.VolumeTag

	FilesystemInfo
}

Filesystem identifies and describes a filesystem, either local or remote (NFS, Ceph etc).

type FilesystemAttachment

type FilesystemAttachment struct {
	// Filesystem is the unique tag assigned by Juju for the filesystem
	// that this attachment corresponds to.
	Filesystem names.FilesystemTag

	// Machine is the unique tag assigned by Juju for the machine that
	// this attachment corresponds to.
	Machine names.MachineTag

	FilesystemAttachmentInfo
}

FilesystemAttachment describes machine-specific filesystem attachment information, including how the filesystem is exposed on the machine.

type FilesystemAttachmentInfo

type FilesystemAttachmentInfo struct {
	// Path is the path at which the filesystem is mounted on the machine
	// that this attachment corresponds to.
	Path string

	// ReadOnly indicates that the filesystem is mounted read-only.
	ReadOnly bool
}

FilesystemAttachmentInfo describes machine-specific filesystem attachment information, including how the filesystem is exposed on the machine.

type FilesystemAttachmentParams

type FilesystemAttachmentParams struct {
	AttachmentParams

	// Filesystem is a unique tag assigned by Juju for the filesystem that
	// should be attached/detached.
	Filesystem names.FilesystemTag

	// FilesystemId is the unique provider-supplied ID for the filesystem that
	// should be attached/detached.
	FilesystemId string

	// Path is the path at which the filesystem is to be mounted on the machine that
	// this attachment corresponds to.
	Path string
}

FilesystemAttachmentParams is a set of parameters for filesystem attachment or detachment.

type FilesystemInfo

type FilesystemInfo struct {
	// FilesystemId is a unique provider-supplied ID for the filesystem.
	// FilesystemId is required to be unique for the lifetime of the
	// filesystem, but may be reused.
	FilesystemId string

	// Size is the size of the filesystem, in MiB.
	Size uint64
}

Filesystem describes a filesystem, either local or remote (NFS, Ceph etc).

type FilesystemParams

type FilesystemParams struct {
	// Tag is a unique tag assigned by Juju for the requested filesystem.
	Tag names.FilesystemTag

	// Volume is the tag of the volume that backs the filesystem, if any.
	Volume names.VolumeTag

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

	// The provider type for this filesystem.
	Provider ProviderType

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

	// ResourceTags is a set of tags to set on the created filesystem, if the
	// storage provider supports tags.
	ResourceTags map[string]string
}

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

type FilesystemSource

type FilesystemSource interface {
	// ValidateFilesystemParams validates the provided filesystem creation
	// parameters, returning an error if they are invalid.
	ValidateFilesystemParams(params FilesystemParams) error

	// CreateFilesystems creates filesystems with the specified size, in MiB.
	CreateFilesystems(params []FilesystemParams) ([]CreateFilesystemsResult, error)

	// DestroyFilesystems destroys the filesystems with the specified
	// providerd filesystem IDs.
	DestroyFilesystems(fsIds []string) ([]error, error)

	// AttachFilesystems attaches filesystems to machines.
	//
	// AttachFilesystems must be idempotent; it may be called even if
	// the attachment already exists, to ensure that it exists, e.g. over
	// machine restarts.
	//
	// 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.
	AttachFilesystems(params []FilesystemAttachmentParams) ([]AttachFilesystemsResult, error)

	// DetachFilesystems detaches the filesystems with the specified
	// provider filesystem IDs from the instances with the corresponding
	// index.
	DetachFilesystems(params []FilesystemAttachmentParams) ([]error, error)
}

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

type Provider

type Provider interface {
	// VolumeSource returns a VolumeSource given the specified cloud
	// and storage provider configurations, or an error if the provider
	// does not support creating volumes or the configuration is invalid.
	//
	// 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)

	// FilesystemSource returns a FilesystemSource given the specified
	// cloud and storage provider configurations, or an error if the
	// provider does not support creating filesystems or the configuration
	// is invalid.
	FilesystemSource(environConfig *config.Config, providerConfig *Config) (FilesystemSource, error)

	// Supports reports whether or not the storage provider supports
	// the specified storage kind.
	//
	// A provider that supports volumes but not filesystems can still
	// be used for creating filesystem storage; Juju will request a
	// volume from the provider and then manage the filesystem itself.
	Supports(kind StorageKind) bool

	// Scope returns the scope of storage managed by this provider.
	Scope() Scope

	// Dynamic reports whether or not the storage provider is capable
	// of dynamic storage provisioning. Non-dynamic storage must be
	// created at the time a machine is provisioned.
	Dynamic() bool

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

type ProviderType

type ProviderType string

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

type Scope

type Scope int

Scope defines the scope of the storage that a provider manages. Machine-scoped storage must be managed from within the machine, whereas environment-level storage must be managed by an environment storage provisioner.

const (
	ScopeEnviron Scope = iota
	ScopeMachine
)

type StorageAttachmentInfo

type StorageAttachmentInfo struct {
	// Kind is the kind of the storage attachment.
	Kind StorageKind

	// Location is the storage attachment's location: the mount point
	// for a filesystem-kind storage attachment, and the device path
	// for a block-kind.
	Location string
}

StorageAttachmentInfo provides unit-specific information about a storage instance. StorageAttachmentInfo is based on either a volume attachment or a filesystem attachment, depending on its kind.

type StorageInstance

type StorageInstance struct {
	// Tag is a unique tag assigned by Juju to the storage instance.
	Tag names.StorageTag

	// Kind is the kind of the datastore (block device, filesystem).
	Kind StorageKind
}

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 Volume

type Volume struct {
	// Name is a unique name assigned by Juju to the volume.
	Tag names.VolumeTag

	VolumeInfo
}

Volume identifies and describes a volume (disk, logical volume, etc.)

type VolumeAttachment

type VolumeAttachment struct {
	// Volume is the unique tag assigned by Juju for the volume
	// that this attachment corresponds to.
	Volume names.VolumeTag

	// Machine is the unique tag assigned by Juju for the machine that
	// this attachment corresponds to.
	Machine names.MachineTag

	VolumeAttachmentInfo
}

VolumeAttachment identifies and describes machine-specific volume attachment information, including how the volume is exposed on the machine.

type VolumeAttachmentInfo

type VolumeAttachmentInfo struct {
	// DeviceName is the volume's OS-specific device name (e.g. "sdb").
	//
	// If the device name may change (e.g. on machine restart), then this
	// field must be left blank.
	DeviceName string

	// DeviceLink is an OS-specific device link that must exactly match
	// one of the block device's links when attached.
	//
	// If no device link is known, or it may change (e.g. on machine
	// restart), then this field must be left blank.
	DeviceLink string

	// BusAddress is the bus address, where the volume is attached to
	// the machine.
	//
	// The format of this field must match the field of the same name
	// in BlockDevice.
	BusAddress string

	// ReadOnly signifies whether the volume is read only or writable.
	ReadOnly bool
}

VolumeAttachmentInfo describes machine-specific volume attachment information, including how the volume is exposed on the machine.

type VolumeAttachmentParams

type VolumeAttachmentParams struct {
	AttachmentParams

	// Volume is a unique tag assigned by Juju for the volume that
	// should be attached/detached.
	Volume names.VolumeTag

	// VolumeId is the unique provider-supplied ID for the volume that
	// should be attached/detached.
	VolumeId string
}

VolumeAttachmentParams is a set of parameters for volume attachment or detachment.

type VolumeInfo

type VolumeInfo struct {
	// VolumeId is a unique provider-supplied ID for the volume.
	// VolumeId is required to be unique for the lifetime of the
	// volume, but may be reused.
	VolumeId string

	// HardwareId is the volume's hardware ID. Not all volumes have
	// a hardware ID, so this may be left blank.
	HardwareId string

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

	// Persistent reflects whether the volume is destroyed with the
	// machine to which it is attached.
	Persistent bool
}

VolumeInfo describes a volume (disk, logical volume etc.)

type VolumeParams

type VolumeParams struct {
	// Tag is a unique tag name assigned by Juju for the requested volume.
	Tag names.VolumeTag

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

	// Provider is the name of the storage provider that is to be used to
	// create the volume.
	Provider ProviderType

	// Attributes is the set of provider-specific attributes to pass to
	// the storage provider when creating the volume. Attributes is derived
	// from the storage pool configuration.
	Attributes map[string]interface{}

	// ResourceTags is a set of tags to set on the created volume, if the
	// storage provider supports tags.
	ResourceTags map[string]string

	// Attachment identifies the machine that the volume should be attached
	// to initially, or nil if the volume should not be attached to any
	// machine. Some providers, such as MAAS, do not support dynamic
	// attachment, and so provisioning time is the only opportunity to
	// perform attachment.
	//
	// When machine instances are created, the instance provider will be
	// presented with parameters for any due-to-be-attached volumes. If
	// once the instance is created there are still unprovisioned volumes,
	// the dynamic storage provisioner will take care of creating them.
	Attachment *VolumeAttachmentParams
}

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 parameters. If the
	// volumes are initially attached, then CreateVolumes returns
	// information about those attachments too.
	CreateVolumes(params []VolumeParams) ([]CreateVolumesResult, error)

	// ListVolumes lists the provider volume IDs for every volume
	// created by this volume source.
	ListVolumes() ([]string, error)

	// DescribeVolumes returns the properties of the volumes with the
	// specified provider volume IDs.
	DescribeVolumes(volIds []string) ([]DescribeVolumesResult, error)

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

	// ValidateVolumeParams validates the provided volume creation
	// parameters, returning an error if they are invalid.
	ValidateVolumeParams(params VolumeParams) error

	// AttachVolumes attaches volumes to machines.
	//
	// AttachVolumes must be idempotent; it may be called even if the
	// attachment already exists, to ensure that it exists, e.g. over
	// machine restarts.
	//
	// 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(params []VolumeAttachmentParams) ([]AttachVolumesResult, 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(params []VolumeAttachmentParams) ([]error, error)
}

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

Directories

Path Synopsis