17529: Return RequestLimitExceeded as a RateLimitError.
[arvados.git] / lib / cloud / interfaces.go
1 // Copyright (C) The Arvados Authors. All rights reserved.
2 //
3 // SPDX-License-Identifier: AGPL-3.0
4
5 package cloud
6
7 import (
8         "encoding/json"
9         "errors"
10         "io"
11         "time"
12
13         "git.arvados.org/arvados.git/sdk/go/arvados"
14         "github.com/sirupsen/logrus"
15         "golang.org/x/crypto/ssh"
16 )
17
18 // A RateLimitError should be returned by an InstanceSet when the
19 // cloud service indicates it is rejecting all API calls for some time
20 // interval.
21 type RateLimitError interface {
22         // Time before which the caller should expect requests to
23         // fail.
24         EarliestRetry() time.Time
25         error
26 }
27
28 // A QuotaError should be returned by an InstanceSet when the cloud
29 // service indicates the account cannot create more VMs than already
30 // exist.
31 type QuotaError interface {
32         // If true, don't create more instances until some existing
33         // instances are destroyed. If false, don't handle the error
34         // as a quota error.
35         IsQuotaError() bool
36         error
37 }
38
39 type SharedResourceTags map[string]string
40 type InstanceSetID string
41 type InstanceTags map[string]string
42 type InstanceID string
43 type ImageID string
44
45 // An Executor executes commands on an ExecutorTarget.
46 type Executor interface {
47         // Update the set of private keys used to authenticate to
48         // targets.
49         SetSigners(...ssh.Signer)
50
51         // Set the target used for subsequent command executions.
52         SetTarget(ExecutorTarget)
53
54         // Return the current target.
55         Target() ExecutorTarget
56
57         // Execute a shell command and return the resulting stdout and
58         // stderr. stdin can be nil.
59         Execute(cmd string, stdin io.Reader) (stdout, stderr []byte, err error)
60 }
61
62 var ErrNotImplemented = errors.New("not implemented")
63
64 // An ExecutorTarget is a remote command execution service.
65 type ExecutorTarget interface {
66         // SSH server hostname or IP address, or empty string if
67         // unknown while instance is booting.
68         Address() string
69
70         // Remote username to send during SSH authentication.
71         RemoteUser() string
72
73         // Return nil if the given public key matches the instance's
74         // SSH server key. If the provided Dialer is not nil,
75         // VerifyHostKey can use it to make outgoing network
76         // connections from the instance -- e.g., to use the cloud's
77         // "this instance's metadata" API.
78         //
79         // Return ErrNotImplemented if no verification mechanism is
80         // available.
81         VerifyHostKey(ssh.PublicKey, *ssh.Client) error
82 }
83
84 // Instance is implemented by the provider-specific instance types.
85 type Instance interface {
86         ExecutorTarget
87
88         // ID returns the provider's instance ID. It must be stable
89         // for the life of the instance.
90         ID() InstanceID
91
92         // String typically returns the cloud-provided instance ID.
93         String() string
94
95         // Cloud provider's "instance type" ID. Matches a ProviderType
96         // in the cluster's InstanceTypes configuration.
97         ProviderType() string
98
99         // Get current tags
100         Tags() InstanceTags
101
102         // Replace tags with the given tags
103         SetTags(InstanceTags) error
104
105         // Shut down the node
106         Destroy() error
107 }
108
109 // An InstanceSet manages a set of VM instances created by an elastic
110 // cloud provider like AWS, GCE, or Azure.
111 //
112 // All public methods of an InstanceSet, and all public methods of the
113 // instances it returns, are goroutine safe.
114 type InstanceSet interface {
115         // Create a new instance with the given type, image, and
116         // initial set of tags. If supported by the driver, add the
117         // provided public key to /root/.ssh/authorized_keys.
118         //
119         // The given InitCommand should be executed on the newly
120         // created instance. This is optional for a driver whose
121         // instances' VerifyHostKey() method never returns
122         // ErrNotImplemented. InitCommand will be under 1 KiB.
123         //
124         // The returned error should implement RateLimitError and
125         // QuotaError where applicable.
126         Create(arvados.InstanceType, ImageID, InstanceTags, InitCommand, ssh.PublicKey) (Instance, error)
127
128         // Return all instances, including ones that are booting or
129         // shutting down. Optionally, filter out nodes that don't have
130         // all of the given InstanceTags (the caller will ignore these
131         // anyway).
132         //
133         // An instance returned by successive calls to Instances() may
134         // -- but does not need to -- be represented by the same
135         // Instance object each time. Thus, the caller is responsible
136         // for de-duplicating the returned instances by comparing the
137         // InstanceIDs returned by the instances' ID() methods.
138         Instances(InstanceTags) ([]Instance, error)
139
140         // Stop any background tasks and release other resources.
141         Stop()
142 }
143
144 type InitCommand string
145
146 // A Driver returns an InstanceSet that uses the given InstanceSetID
147 // and driver-dependent configuration parameters.
148 //
149 // If the driver creates cloud resources that aren't attached to a
150 // single VM instance (like SSH key pairs on AWS) and support tagging,
151 // they should be tagged with the provided SharedResourceTags.
152 //
153 // The supplied id will be of the form "zzzzz-zzzzz-zzzzzzzzzzzzzzz"
154 // where each z can be any alphanum. The returned InstanceSet must use
155 // this id to tag long-lived cloud resources that it creates, and must
156 // assume control of any existing resources that are tagged with the
157 // same id. Tagging can be accomplished by including the ID in
158 // resource names, using the cloud provider's tagging feature, or any
159 // other mechanism. The tags must be visible to another instance of
160 // the same driver running on a different host.
161 //
162 // The returned InstanceSet must not modify or delete cloud resources
163 // unless they are tagged with the given InstanceSetID or the caller
164 // (dispatcher) calls Destroy() on them. It may log a summary of
165 // untagged resources once at startup, though. Thus, two identically
166 // configured InstanceSets running on different hosts with different
167 // ids should log about the existence of each other's resources at
168 // startup, but will not interfere with each other.
169 //
170 // The dispatcher always passes the InstanceSetID as a tag when
171 // calling Create() and Instances(), so the driver does not need to
172 // tag/filter VMs by InstanceSetID itself.
173 //
174 // Example:
175 //
176 //      type exampleInstanceSet struct {
177 //              ownID     string
178 //              AccessKey string
179 //      }
180 //
181 //      type exampleDriver struct {}
182 //
183 //      func (*exampleDriver) InstanceSet(config json.RawMessage, id cloud.InstanceSetID, tags cloud.SharedResourceTags, logger logrus.FieldLogger) (cloud.InstanceSet, error) {
184 //              var is exampleInstanceSet
185 //              if err := json.Unmarshal(config, &is); err != nil {
186 //                      return nil, err
187 //              }
188 //              is.ownID = id
189 //              return &is, nil
190 //      }
191 //
192 //      var _ = registerCloudDriver("example", &exampleDriver{})
193 type Driver interface {
194         InstanceSet(config json.RawMessage, id InstanceSetID, tags SharedResourceTags, logger logrus.FieldLogger) (InstanceSet, error)
195 }
196
197 // DriverFunc makes a Driver using the provided function as its
198 // InstanceSet method. This is similar to http.HandlerFunc.
199 func DriverFunc(fn func(config json.RawMessage, id InstanceSetID, tags SharedResourceTags, logger logrus.FieldLogger) (InstanceSet, error)) Driver {
200         return driverFunc(fn)
201 }
202
203 type driverFunc func(config json.RawMessage, id InstanceSetID, tags SharedResourceTags, logger logrus.FieldLogger) (InstanceSet, error)
204
205 func (df driverFunc) InstanceSet(config json.RawMessage, id InstanceSetID, tags SharedResourceTags, logger logrus.FieldLogger) (InstanceSet, error) {
206         return df(config, id, tags, logger)
207 }