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 }