← Back to branch summary

~nskaggs/+junk/xenial-test

« back to all changes in this revision

Viewing changes to src/github.com/juju/gomaasapi/interfaces.go

  • Committer: Nicholas Skaggs
  • Date: 2016-10-24 20:56:05 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161024205605-z8lta0uvuhtxwzwl
Initi with beta15

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/github.com/juju/gomaasapi/interfaces.go
 
1
// Copyright 2016 Canonical Ltd.
 
2
// Licensed under the LGPLv3, see LICENCE file for details.
 
3
 
 
4
package gomaasapi
 
5
 
 
6
import "github.com/juju/utils/set"
 
7
 
 
8
const (
 
9
        // Capability constants.
 
10
        NetworksManagement      = "networks-management"
 
11
        StaticIPAddresses       = "static-ipaddresses"
 
12
        IPv6DeploymentUbuntu    = "ipv6-deployment-ubuntu"
 
13
        DevicesManagement       = "devices-management"
 
14
        StorageDeploymentUbuntu = "storage-deployment-ubuntu"
 
15
        NetworkDeploymentUbuntu = "network-deployment-ubuntu"
 
16
)
 
17
 
 
18
// Controller represents an API connection to a MAAS Controller. Since the API
 
19
// is restful, there is no long held connection to the API server, but instead
 
20
// HTTP calls are made and JSON response structures parsed.
 
21
type Controller interface {
 
22
 
 
23
        // Capabilities returns a set of capabilities as defined by the string
 
24
        // constants.
 
25
        Capabilities() set.Strings
 
26
 
 
27
        BootResources() ([]BootResource, error)
 
28
 
 
29
        // Fabrics returns the list of Fabrics defined in the MAAS controller.
 
30
        Fabrics() ([]Fabric, error)
 
31
 
 
32
        // Spaces returns the list of Spaces defined in the MAAS controller.
 
33
        Spaces() ([]Space, error)
 
34
 
 
35
        // Zones lists all the zones known to the MAAS controller.
 
36
        Zones() ([]Zone, error)
 
37
 
 
38
        // Machines returns a list of machines that match the params.
 
39
        Machines(MachinesArgs) ([]Machine, error)
 
40
 
 
41
        // AllocateMachine will attempt to allocate a machine to the user.
 
42
        // If successful, the allocated machine is returned.
 
43
        AllocateMachine(AllocateMachineArgs) (Machine, ConstraintMatches, error)
 
44
 
 
45
        // ReleaseMachines will stop the specified machines, and release them
 
46
        // from the user making them available to be allocated again.
 
47
        ReleaseMachines(ReleaseMachinesArgs) error
 
48
 
 
49
        // Devices returns a list of devices that match the params.
 
50
        Devices(DevicesArgs) ([]Device, error)
 
51
 
 
52
        // CreateDevice creates and returns a new Device.
 
53
        CreateDevice(CreateDeviceArgs) (Device, error)
 
54
 
 
55
        // Files returns all the files that match the specified prefix.
 
56
        Files(prefix string) ([]File, error)
 
57
 
 
58
        // Return a single file by its filename.
 
59
        GetFile(filename string) (File, error)
 
60
 
 
61
        // AddFile adds or replaces the content of the specified filename.
 
62
        // If or when the MAAS api is able to return metadata about a single
 
63
        // file without sending the content of the file, we can return a File
 
64
        // instance here too.
 
65
        AddFile(AddFileArgs) error
 
66
}
 
67
 
 
68
// File represents a file stored in the MAAS controller.
 
69
type File interface {
 
70
        // Filename is the name of the file. No path, just the filename.
 
71
        Filename() string
 
72
 
 
73
        // AnonymousURL is a URL that can be used to retrieve the conents of the
 
74
        // file without credentials.
 
75
        AnonymousURL() string
 
76
 
 
77
        // Delete removes the file from the MAAS controller.
 
78
        Delete() error
 
79
 
 
80
        // ReadAll returns the content of the file.
 
81
        ReadAll() ([]byte, error)
 
82
}
 
83
 
 
84
// Fabric represents a set of interconnected VLANs that are capable of mutual
 
85
// communication. A fabric can be thought of as a logical grouping in which
 
86
// VLANs can be considered unique.
 
87
//
 
88
// For example, a distributed network may have a fabric in London containing
 
89
// VLAN 100, while a separate fabric in San Francisco may contain a VLAN 100,
 
90
// whose attached subnets are completely different and unrelated.
 
91
type Fabric interface {
 
92
        ID() int
 
93
        Name() string
 
94
        ClassType() string
 
95
 
 
96
        VLANs() []VLAN
 
97
}
 
98
 
 
99
// VLAN represents an instance of a Virtual LAN. VLANs are a common way to
 
100
// create logically separate networks using the same physical infrastructure.
 
101
//
 
102
// Managed switches can assign VLANs to each port in either a “tagged” or an
 
103
// “untagged” manner. A VLAN is said to be “untagged” on a particular port when
 
104
// it is the default VLAN for that port, and requires no special configuration
 
105
// in order to access.
 
106
//
 
107
// “Tagged” VLANs (traditionally used by network administrators in order to
 
108
// aggregate multiple networks over inter-switch “trunk” lines) can also be used
 
109
// with nodes in MAAS. That is, if a switch port is configured such that
 
110
// “tagged” VLAN frames can be sent and received by a MAAS node, that MAAS node
 
111
// can be configured to automatically bring up VLAN interfaces, so that the
 
112
// deployed node can make use of them.
 
113
//
 
114
// A “Default VLAN” is created for every Fabric, to which every new VLAN-aware
 
115
// object in the fabric will be associated to by default (unless otherwise
 
116
// specified).
 
117
type VLAN interface {
 
118
        ID() int
 
119
        Name() string
 
120
        Fabric() string
 
121
 
 
122
        // VID is the VLAN ID. eth0.10 -> VID = 10.
 
123
        VID() int
 
124
        // MTU (maximum transmission unit) is the largest size packet or frame,
 
125
        // specified in octets (eight-bit bytes), that can be sent.
 
126
        MTU() int
 
127
        DHCP() bool
 
128
 
 
129
        PrimaryRack() string
 
130
        SecondaryRack() string
 
131
}
 
132
 
 
133
// Zone represents a physical zone that a Machine is in. The meaning of a
 
134
// physical zone is up to you: it could identify e.g. a server rack, a network,
 
135
// or a data centre. Users can then allocate nodes from specific physical zones,
 
136
// to suit their redundancy or performance requirements.
 
137
type Zone interface {
 
138
        Name() string
 
139
        Description() string
 
140
}
 
141
 
 
142
// BootResource is the bomb... find something to say here.
 
143
type BootResource interface {
 
144
        ID() int
 
145
        Name() string
 
146
        Type() string
 
147
        Architecture() string
 
148
        SubArchitectures() set.Strings
 
149
        KernelFlavor() string
 
150
}
 
151
 
 
152
// Device represents some form of device in MAAS.
 
153
type Device interface {
 
154
        // TODO: add domain
 
155
        SystemID() string
 
156
        Hostname() string
 
157
        FQDN() string
 
158
        IPAddresses() []string
 
159
        Zone() Zone
 
160
 
 
161
        // Parent returns the SystemID of the Parent. Most often this will be a
 
162
        // Machine.
 
163
        Parent() string
 
164
 
 
165
        // Owner is the username of the user that created the device.
 
166
        Owner() string
 
167
 
 
168
        // InterfaceSet returns all the interfaces for the Device.
 
169
        InterfaceSet() []Interface
 
170
 
 
171
        // CreateInterface will create a physical interface for this machine.
 
172
        CreateInterface(CreateInterfaceArgs) (Interface, error)
 
173
 
 
174
        // Delete will remove this Device.
 
175
        Delete() error
 
176
}
 
177
 
 
178
// Machine represents a physical machine.
 
179
type Machine interface {
 
180
        SystemID() string
 
181
        Hostname() string
 
182
        FQDN() string
 
183
        Tags() []string
 
184
 
 
185
        OperatingSystem() string
 
186
        DistroSeries() string
 
187
        Architecture() string
 
188
        Memory() int
 
189
        CPUCount() int
 
190
 
 
191
        IPAddresses() []string
 
192
        PowerState() string
 
193
 
 
194
        // Devices returns a list of devices that match the params and have
 
195
        // this Machine as the parent.
 
196
        Devices(DevicesArgs) ([]Device, error)
 
197
 
 
198
        // Consider bundling the status values into a single struct.
 
199
        // but need to check for consistent representation if exposed on other
 
200
        // entities.
 
201
 
 
202
        StatusName() string
 
203
        StatusMessage() string
 
204
 
 
205
        // BootInterface returns the interface that was used to boot the Machine.
 
206
        BootInterface() Interface
 
207
        // InterfaceSet returns all the interfaces for the Machine.
 
208
        InterfaceSet() []Interface
 
209
        // Interface returns the interface for the machine that matches the id
 
210
        // specified. If there is no match, nil is returned.
 
211
        Interface(id int) Interface
 
212
 
 
213
        // PhysicalBlockDevices returns all the physical block devices on the machine.
 
214
        PhysicalBlockDevices() []BlockDevice
 
215
        // PhysicalBlockDevice returns the physical block device for the machine
 
216
        // that matches the id specified. If there is no match, nil is returned.
 
217
        PhysicalBlockDevice(id int) BlockDevice
 
218
 
 
219
        // BlockDevices returns all the physical and virtual block devices on the machine.
 
220
        BlockDevices() []BlockDevice
 
221
 
 
222
        Zone() Zone
 
223
 
 
224
        // Start the machine and install the operating system specified in the args.
 
225
        Start(StartArgs) error
 
226
 
 
227
        // CreateDevice creates a new Device with this Machine as the parent.
 
228
        // The device will have one interface that is linked to the specified subnet.
 
229
        CreateDevice(CreateMachineDeviceArgs) (Device, error)
 
230
}
 
231
 
 
232
// Space is a name for a collection of Subnets.
 
233
type Space interface {
 
234
        ID() int
 
235
        Name() string
 
236
        Subnets() []Subnet
 
237
}
 
238
 
 
239
// Subnet refers to an IP range on a VLAN.
 
240
type Subnet interface {
 
241
        ID() int
 
242
        Name() string
 
243
        Space() string
 
244
        VLAN() VLAN
 
245
 
 
246
        Gateway() string
 
247
        CIDR() string
 
248
        // dns_mode
 
249
 
 
250
        // DNSServers is a list of ip addresses of the DNS servers for the subnet.
 
251
        // This list may be empty.
 
252
        DNSServers() []string
 
253
}
 
254
 
 
255
// Interface represents a physical or virtual network interface on a Machine.
 
256
type Interface interface {
 
257
        ID() int
 
258
        Name() string
 
259
        // The parents of an interface are the names of interfaces that must exist
 
260
        // for this interface  to exist. For example a parent of "eth0.100" would be
 
261
        // "eth0". Parents may be empty.
 
262
        Parents() []string
 
263
        // The children interfaces are the names of those that are dependent on this
 
264
        // interface existing. Children may be empty.
 
265
        Children() []string
 
266
        Type() string
 
267
        Enabled() bool
 
268
        Tags() []string
 
269
 
 
270
        VLAN() VLAN
 
271
        Links() []Link
 
272
 
 
273
        MACAddress() string
 
274
        EffectiveMTU() int
 
275
 
 
276
        // Params is a JSON field, and defaults to an empty string, but is almost
 
277
        // always a JSON object in practice. Gleefully ignoring it until we need it.
 
278
 
 
279
        // Update the name, mac address or VLAN.
 
280
        Update(UpdateInterfaceArgs) error
 
281
 
 
282
        // Delete this interface.
 
283
        Delete() error
 
284
 
 
285
        // LinkSubnet will attempt to make this interface available on the specified
 
286
        // Subnet.
 
287
        LinkSubnet(LinkSubnetArgs) error
 
288
 
 
289
        // UnlinkSubnet will remove the Link to the subnet, and release the IP
 
290
        // address associated if there is one.
 
291
        UnlinkSubnet(Subnet) error
 
292
}
 
293
 
 
294
// Link represents a network link between an Interface and a Subnet.
 
295
type Link interface {
 
296
        ID() int
 
297
        Mode() string
 
298
        Subnet() Subnet
 
299
        // IPAddress returns the address if one has been assigned.
 
300
        // If unavailble, the address will be empty.
 
301
        IPAddress() string
 
302
}
 
303
 
 
304
// FileSystem represents a formatted filesystem mounted at a location.
 
305
type FileSystem interface {
 
306
        // Type is the format type, e.g. "ext4".
 
307
        Type() string
 
308
 
 
309
        MountPoint() string
 
310
        Label() string
 
311
        UUID() string
 
312
}
 
313
 
 
314
// Partition represents a partition of a block device. It may be mounted
 
315
// as a filesystem.
 
316
type Partition interface {
 
317
        ID() int
 
318
        Path() string
 
319
        // FileSystem may be nil if not mounted.
 
320
        FileSystem() FileSystem
 
321
        UUID() string
 
322
        // UsedFor is a human readable string.
 
323
        UsedFor() string
 
324
        // Size is the number of bytes in the partition.
 
325
        Size() uint64
 
326
}
 
327
 
 
328
// BlockDevice represents an entire block device on the machine.
 
329
type BlockDevice interface {
 
330
        ID() int
 
331
        Name() string
 
332
        Model() string
 
333
        Path() string
 
334
        UsedFor() string
 
335
        Tags() []string
 
336
 
 
337
        BlockSize() uint64
 
338
        UsedSize() uint64
 
339
        Size() uint64
 
340
 
 
341
        Partitions() []Partition
 
342
 
 
343
        // There are some other attributes for block devices, but we can
 
344
        // expose them on an as needed basis.
 
345
}