storage

type AttachFilesystemsResult struct {
	FilesystemAttachment *FilesystemAttachment
	Error                error
}

type AttachVolumesResult struct {
	VolumeAttachment *VolumeAttachment
	Error            error
}

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.
	// This is a generic tag as it's also used to hold a unit for caas storage.
	// TODO(caas)-rename to Host
	Machine names.Tag

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

type Attrs map[string]interface{}

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"`

	// WWN is the block device's World Wide Name (WWN) unique identifier.
	// Not all block devices have one, so WWN may be empty. This is used
	// to identify a block device if it is available, in preference to
	// UUID or device name, as the WWN is immutable.
	WWN string `yaml:"wwn,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"`

	// SerialId is the block devices serial id used for matching.
	SerialId string `yaml:"serialid,omitempty"`
}

type ChainedProviderRegistry []ProviderRegistry

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

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
}

type CreateFilesystemsResult struct {
	Filesystem *Filesystem
	Error      error
}

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

type DescribeVolumesResult struct {
	VolumeInfo *VolumeInfo
	Error      error
}

type DeviceType string

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
}

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

	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
}

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
}

type FilesystemImporter interface {
	// ImportFilesystem updates the filesystem with the specified
	// filesystem provider ID with the given resource tags, so that
	// it is seen as being managed by this Juju controller/model.
	// ImportFilesystem returns the filesystem information to store
	// in the model.
	//
	// Implementations of ImportFilesystem should validate that the
	// filesystem is not in use before allowing the import to proceed.
	// Once it is imported, it is assumed to be in a detached state.
	ImportFilesystem(
		ctx context.ProviderCallContext,
		filesystemId string,
		resourceTags map[string]string,
	) (FilesystemInfo, error)
}

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
}

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

	// Attachment identifies the machine that the filesystem should be attached
	// to initially, or nil if the filesystem should not be attached to any
	// machine.
	Attachment *FilesystemAttachmentParams
}

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(ctx context.ProviderCallContext, params []FilesystemParams) ([]CreateFilesystemsResult, error)

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

	// ReleaseFilesystems releases the filesystems with the specified provider
	// filesystem IDs from the model/controller.
	ReleaseFilesystems(ctx context.ProviderCallContext, volIds []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(ctx context.ProviderCallContext, params []FilesystemAttachmentParams) ([]AttachFilesystemsResult, error)

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

type KubernetesFilesystemAttachmentParams struct {
	AttachmentParams

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

type KubernetesFilesystemInfo struct {
	// MountPoint is the path the filesystem is mounted at.
	MountPoint string

	// ReadOnly is true if the filesystem is readonly.
	ReadOnly bool

	// FilesystemId is a unique provider id for the filesystem.
	FilesystemId string

	// Pool is the name of the storage pool used to
	// allocate the filesystem.
	Pool string

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

type KubernetesFilesystemParams struct {
	// StorageName is the name of the storage as specified in the charm.
	StorageName string

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

	// Attachment identifies the mount point the filesystem should be
	// mounted at.
	Attachment *KubernetesFilesystemAttachmentParams
}

type Provider interface {
	// VolumeSource returns a VolumeSource given the specified 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(*Config) (VolumeSource, error)

	// FilesystemSource returns a FilesystemSource given the specified
	// storage provider configurations, or an error if the provider does
	// not support creating filesystems or the configuration is invalid.
	FilesystemSource(*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

	// Releasable reports whether or not the storage provider is capable
	// of releasing dynamic storage, with either ReleaseVolumes or
	// ReleaseFilesystems.
	Releasable() bool

	// DefaultPools returns the default storage pools for this provider,
	// to register in each new model.
	DefaultPools() []*Config

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

	// ValidateForK8s validates if a storage provider can be set for
	// a given K8s configuration.
	ValidateForK8s(map[string]any) error
}

type ProviderRegistry interface {
	// StorageProviderTypes returns the storage provider types
	// contained within this registry.
	//
	// Determining the supported storage providers may be dynamic.
	// Multiple calls for the same registry must return consistent
	// results.
	StorageProviderTypes() ([]ProviderType, error)

	// StorageProvider returns the storage provider with the given
	// provider type. StorageProvider must return an errors satisfying
	// errors.IsNotFound if the registry does not contain the
	// specified provider type.
	StorageProvider(ProviderType) (Provider, error)
}

type ProviderType string

type Scope int

type StaticProviderRegistry struct {
	// Providers contains the storage providers for this registry.
	Providers map[ProviderType]Provider
}

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
}

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
}

type StorageKind int

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

	VolumeInfo
}

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

	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

	// PlanInfo holds information that the machine agent might use to
	// initialize the block device that has been attached to it.
	PlanInfo *VolumeAttachmentPlanInfo
}

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
}

type VolumeAttachmentPlan 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

	VolumeAttachmentPlanInfo
}

type VolumeAttachmentPlanInfo struct {
	// DeviceType describes what type of volume we are dealing with
	// possible options are:
	// * local - a block device that is directly attached to this instance
	// * iscsi - an iSCSI disk. This type of disk will require the machine agent
	// to execute additional steps before the device is available
	DeviceType DeviceType
	// DeviceAttributes is a map that contains DeviceType specific initialization
	// values. For example, in the case of iscsi, it may contain server address:port,
	// target, chap secrets, etc.
	DeviceAttributes map[string]string
}

type VolumeImporter interface {
	// ImportVolume updates the volume with the specified volume
	// provider ID with the given resource tags, so that it is
	// seen as being managed by this Juju controller/model.
	// ImportVolume returns the volume information to store
	// in the model.
	//
	// Implementations of ImportVolume should validate that the
	// volume is not in use before allowing the import to proceed.
	// Once it is imported, it is assumed to be in a detached state.
	ImportVolume(
		ctx context.ProviderCallContext,
		volumeId string,
		resourceTags map[string]string,
	) (VolumeInfo, error)
}

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

	// WWN is the volume's World Wide Name (WWN). Not all volumes
	// have a WWN, so this may be left blank.
	WWN 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
}

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
}

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(ctx context.ProviderCallContext, params []VolumeParams) ([]CreateVolumesResult, error)

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

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

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

	// ReleaseVolumes releases the volumes with the specified provider
	// volume IDs from the model/controller.
	ReleaseVolumes(ctx context.ProviderCallContext, 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(ctx context.ProviderCallContext, 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(ctx context.ProviderCallContext, params []VolumeAttachmentParams) ([]error, error)
}