github.com/wallyworld/juju@v0.0.0-20161013125918-6cf1bc9d917a/storage/interface.go (about) 1 // Copyright 2015 Canonical Ltd. 2 // Licensed under the AGPLv3, see LICENCE file for details. 3 4 package storage 5 6 import ( 7 "gopkg.in/juju/names.v2" 8 9 "github.com/juju/juju/instance" 10 ) 11 12 // ProviderType uniquely identifies a storage provider, such as "ebs" or "loop". 13 type ProviderType string 14 15 // Scope defines the scope of the storage that a provider manages. 16 // Machine-scoped storage must be managed from within the machine, 17 // whereas environment-level storage must be managed by an environment 18 // storage provisioner. 19 type Scope int 20 21 const ( 22 ScopeEnviron Scope = iota 23 ScopeMachine 24 ) 25 26 // ProviderRegistry is an interface for obtaining storage providers. 27 type ProviderRegistry interface { 28 // StorageProviderTypes returns the storage provider types 29 // contained within this registry. 30 // 31 // Determining the supported storage providers may be dynamic. 32 // Multiple calls for the same registry must return consistent 33 // results. 34 StorageProviderTypes() ([]ProviderType, error) 35 36 // StorageProvider returns the storage provider with the given 37 // provider type. StorageProvider must return an errors satisfying 38 // errors.IsNotFound if the registry does not contain said the 39 // specified provider type. 40 StorageProvider(ProviderType) (Provider, error) 41 } 42 43 // Provider is an interface for obtaining storage sources. 44 type Provider interface { 45 // VolumeSource returns a VolumeSource given the specified storage 46 // provider configurations, or an error if the provider does not 47 // support creating volumes or the configuration is invalid. 48 // 49 // If the storage provider does not support creating volumes as a 50 // first-class primitive, then VolumeSource must return an error 51 // satisfying errors.IsNotSupported. 52 VolumeSource(*Config) (VolumeSource, error) 53 54 // FilesystemSource returns a FilesystemSource given the specified 55 // storage provider configurations, or an error if the provider does 56 // not support creating filesystems or the configuration is invalid. 57 FilesystemSource(*Config) (FilesystemSource, error) 58 59 // Supports reports whether or not the storage provider supports 60 // the specified storage kind. 61 // 62 // A provider that supports volumes but not filesystems can still 63 // be used for creating filesystem storage; Juju will request a 64 // volume from the provider and then manage the filesystem itself. 65 Supports(kind StorageKind) bool 66 67 // Scope returns the scope of storage managed by this provider. 68 Scope() Scope 69 70 // Dynamic reports whether or not the storage provider is capable 71 // of dynamic storage provisioning. Non-dynamic storage must be 72 // created at the time a machine is provisioned. 73 Dynamic() bool 74 75 // DefaultPools returns the default storage pools for this provider, 76 // to register in each new model. 77 DefaultPools() []*Config 78 79 // ValidateConfig validates the provided storage provider config, 80 // returning an error if it is invalid. 81 ValidateConfig(*Config) error 82 } 83 84 // VolumeSource provides an interface for creating, destroying, describing, 85 // attaching and detaching volumes in the environment. A VolumeSource is 86 // configured in a particular way, and corresponds to a storage "pool". 87 type VolumeSource interface { 88 // CreateVolumes creates volumes with the specified parameters. If the 89 // volumes are initially attached, then CreateVolumes returns 90 // information about those attachments too. 91 CreateVolumes(params []VolumeParams) ([]CreateVolumesResult, error) 92 93 // ListVolumes lists the provider volume IDs for every volume 94 // created by this volume source. 95 ListVolumes() ([]string, error) 96 97 // DescribeVolumes returns the properties of the volumes with the 98 // specified provider volume IDs. 99 DescribeVolumes(volIds []string) ([]DescribeVolumesResult, error) 100 101 // DestroyVolumes destroys the volumes with the specified provider 102 // volume IDs. 103 DestroyVolumes(volIds []string) ([]error, error) 104 105 // ValidateVolumeParams validates the provided volume creation 106 // parameters, returning an error if they are invalid. 107 ValidateVolumeParams(params VolumeParams) error 108 109 // AttachVolumes attaches volumes to machines. 110 // 111 // AttachVolumes must be idempotent; it may be called even if the 112 // attachment already exists, to ensure that it exists, e.g. over 113 // machine restarts. 114 // 115 // TODO(axw) we need to validate attachment requests prior to 116 // recording in state. For example, the ec2 provider must reject 117 // an attempt to attach a volume to an instance if they are in 118 // different availability zones. 119 AttachVolumes(params []VolumeAttachmentParams) ([]AttachVolumesResult, error) 120 121 // DetachVolumes detaches the volumes with the specified provider 122 // volume IDs from the instances with the corresponding index. 123 // 124 // TODO(axw) we need to record in state whether or not volumes 125 // are detachable, and reject attempts to attach/detach on 126 // that basis. 127 DetachVolumes(params []VolumeAttachmentParams) ([]error, error) 128 } 129 130 // FilesystemSource provides an interface for creating, destroying and 131 // describing filesystems in the environment. A FilesystemSource is 132 // configured in a particular way, and corresponds to a storage "pool". 133 type FilesystemSource interface { 134 // ValidateFilesystemParams validates the provided filesystem creation 135 // parameters, returning an error if they are invalid. 136 ValidateFilesystemParams(params FilesystemParams) error 137 138 // CreateFilesystems creates filesystems with the specified size, in MiB. 139 CreateFilesystems(params []FilesystemParams) ([]CreateFilesystemsResult, error) 140 141 // DestroyFilesystems destroys the filesystems with the specified 142 // providerd filesystem IDs. 143 DestroyFilesystems(fsIds []string) ([]error, error) 144 145 // AttachFilesystems attaches filesystems to machines. 146 // 147 // AttachFilesystems must be idempotent; it may be called even if 148 // the attachment already exists, to ensure that it exists, e.g. over 149 // machine restarts. 150 // 151 // TODO(axw) we need to validate attachment requests prior to 152 // recording in state. For example, the ec2 provider must reject 153 // an attempt to attach a volume to an instance if they are in 154 // different availability zones. 155 AttachFilesystems(params []FilesystemAttachmentParams) ([]AttachFilesystemsResult, error) 156 157 // DetachFilesystems detaches the filesystems with the specified 158 // provider filesystem IDs from the instances with the corresponding 159 // index. 160 DetachFilesystems(params []FilesystemAttachmentParams) ([]error, error) 161 } 162 163 // VolumeParams is a fully specified set of parameters for volume creation, 164 // derived from one or more of user-specified storage constraints, a 165 // storage pool definition, and charm storage metadata. 166 type VolumeParams struct { 167 // Tag is a unique tag name assigned by Juju for the requested volume. 168 Tag names.VolumeTag 169 170 // Size is the minimum size of the volume in MiB. 171 Size uint64 172 173 // Provider is the name of the storage provider that is to be used to 174 // create the volume. 175 Provider ProviderType 176 177 // Attributes is the set of provider-specific attributes to pass to 178 // the storage provider when creating the volume. Attributes is derived 179 // from the storage pool configuration. 180 Attributes map[string]interface{} 181 182 // ResourceTags is a set of tags to set on the created volume, if the 183 // storage provider supports tags. 184 ResourceTags map[string]string 185 186 // Attachment identifies the machine that the volume should be attached 187 // to initially, or nil if the volume should not be attached to any 188 // machine. Some providers, such as MAAS, do not support dynamic 189 // attachment, and so provisioning time is the only opportunity to 190 // perform attachment. 191 // 192 // When machine instances are created, the instance provider will be 193 // presented with parameters for any due-to-be-attached volumes. If 194 // once the instance is created there are still unprovisioned volumes, 195 // the dynamic storage provisioner will take care of creating them. 196 Attachment *VolumeAttachmentParams 197 } 198 199 // VolumeAttachmentParams is a set of parameters for volume attachment or 200 // detachment. 201 type VolumeAttachmentParams struct { 202 AttachmentParams 203 204 // Volume is a unique tag assigned by Juju for the volume that 205 // should be attached/detached. 206 Volume names.VolumeTag 207 208 // VolumeId is the unique provider-supplied ID for the volume that 209 // should be attached/detached. 210 VolumeId string 211 } 212 213 // AttachmentParams describes the parameters for attaching a volume or 214 // filesystem to a machine. 215 type AttachmentParams struct { 216 // Provider is the name of the storage provider that is to be used to 217 // create the attachment. 218 Provider ProviderType 219 220 // Machine is the tag of the Juju machine that the storage should be 221 // attached to. Storage providers may use this to perform machine- 222 // specific operations, such as configuring access controls for the 223 // machine. 224 Machine names.MachineTag 225 226 // InstanceId is the ID of the cloud instance that the storage should 227 // be attached to. This will only be of interest to storage providers 228 // that interact with the instances, such as EBS/EC2. The InstanceId 229 // field will be empty if the instance is not yet provisioned. 230 InstanceId instance.Id 231 232 // ReadOnly indicates that the storage should be attached as read-only. 233 ReadOnly bool 234 } 235 236 // FilesystemParams is a fully specified set of parameters for filesystem creation, 237 // derived from one or more of user-specified storage constraints, a 238 // storage pool definition, and charm storage metadata. 239 type FilesystemParams struct { 240 // Tag is a unique tag assigned by Juju for the requested filesystem. 241 Tag names.FilesystemTag 242 243 // Volume is the tag of the volume that backs the filesystem, if any. 244 Volume names.VolumeTag 245 246 // Size is the minimum size of the filesystem in MiB. 247 Size uint64 248 249 // The provider type for this filesystem. 250 Provider ProviderType 251 252 // Attributes is a set of provider-specific options for storage creation, 253 // as defined in a storage pool. 254 Attributes map[string]interface{} 255 256 // ResourceTags is a set of tags to set on the created filesystem, if the 257 // storage provider supports tags. 258 ResourceTags map[string]string 259 } 260 261 // FilesystemAttachmentParams is a set of parameters for filesystem attachment 262 // or detachment. 263 type FilesystemAttachmentParams struct { 264 AttachmentParams 265 266 // Filesystem is a unique tag assigned by Juju for the filesystem that 267 // should be attached/detached. 268 Filesystem names.FilesystemTag 269 270 // FilesystemId is the unique provider-supplied ID for the filesystem that 271 // should be attached/detached. 272 FilesystemId string 273 274 // Path is the path at which the filesystem is to be mounted on the machine that 275 // this attachment corresponds to. 276 Path string 277 } 278 279 // CreateVolumesResult contains the result of a VolumeSource.CreateVolumes call 280 // for one volume. Volume and VolumeAttachment should only be used if Error is 281 // nil. 282 type CreateVolumesResult struct { 283 Volume *Volume 284 VolumeAttachment *VolumeAttachment 285 Error error 286 } 287 288 // DescribeVolumesResult contains the result of a VolumeSource.DescribeVolumes call 289 // for one volume. Volume should only be used if Error is nil. 290 type DescribeVolumesResult struct { 291 VolumeInfo *VolumeInfo 292 Error error 293 } 294 295 // AttachVolumesResult contains the result of a VolumeSource.AttachVolumes call 296 // for one volume. VolumeAttachment should only be used if Error is nil. 297 type AttachVolumesResult struct { 298 VolumeAttachment *VolumeAttachment 299 Error error 300 } 301 302 // CreateFilesystemsResult contains the result of a FilesystemSource.CreateFilesystems call 303 // for one filesystem. Filesystem should only be used if Error is nil. 304 type CreateFilesystemsResult struct { 305 Filesystem *Filesystem 306 Error error 307 } 308 309 // DescribeFilesystemsResult contains the result of a FilesystemSource.DescribeFilesystems call 310 // for one filesystem. Filesystem should only be used if Error is nil. 311 type DescribeFilesystemsResult struct { 312 FilesystemInfo *FilesystemInfo 313 Error error 314 } 315 316 // AttachFilesystemsResult contains the result of a FilesystemSource.AttachFilesystems call 317 // for one filesystem. FilesystemAttachment should only be used if Error is nil. 318 type AttachFilesystemsResult struct { 319 FilesystemAttachment *FilesystemAttachment 320 Error error 321 }