lib/dispatchcloud/provider.go

   1 // Copyright (C) The Arvados Authors. All rights reserved.
   2 //
   3 // SPDX-License-Identifier: AGPL-3.0
   4
   5 package dispatchcloud
   6
   7 import (
   8         "context"
   9         "time"
  10
  11         "git.curoverse.com/arvados.git/sdk/go/arvados"
  12         "golang.org/x/crypto/ssh"
  13 )
  14
  15 // A RateLimitError should be returned by a Provider when the cloud
  16 // service indicates it is rejecting all API calls for some time
  17 // interval.
  18 type RateLimitError interface {
  19         // Time before which the caller should expect requests to
  20         // fail.
  21         EarliestRetry() time.Time
  22         error
  23 }
  24
  25 // A QuotaError should be returned by a Provider when the cloud
  26 // service indicates the account cannot create more VMs than already
  27 // exist.
  28 type QuotaError interface {
  29         // If true, don't create more instances until some existing
  30         // instances are destroyed. If false, don't handle the error
  31         // as a quota error.
  32         IsQuotaError() bool
  33         error
  34 }
  35
  36 type InstanceTags map[string]string
  37 type InstanceID string
  38 type ImageID string
  39
  40 // instance is implemented by the provider-specific instance types.
  41 type Instance interface {
  42         // ID returns the provider's instance ID. It must be stable
  43         // for the life of the instance.
  44         ID() InstanceID
  45
  46         // String typically returns the cloud-provided instance ID.
  47         String() string
  48
  49         // Get tags
  50         Tags(context.Context) (InstanceTags, error)
  51
  52         // Replace tags with the given tags
  53         SetTags(context.Context, InstanceTags) error
  54
  55         // Shut down the node
  56         Destroy(context.Context) error
  57
  58         // SSH server hostname or IP address, or empty string if unknown pending creation.
  59         Address() string
  60 }
  61
  62 type InstanceProvider interface {
  63         // Create a new instance. If supported by the driver, add the
  64         // provided public key to /root/.ssh/authorized_keys.
  65         //
  66         // The returned error should implement RateLimitError and
  67         // QuotaError where applicable.
  68         Create(context.Context, arvados.InstanceType, ImageID, InstanceTags, ssh.PublicKey) (Instance, error)
  69
  70         // Return all instances, including ones that are booting or
  71         // shutting down.
  72         //
  73         // An instance returned by successive calls to Instances() may
  74         // -- but does not need to -- be represented by the same
  75         // Instance object each time. Thus, the caller is responsible
  76         // for de-duplicating the returned instances by comparing the
  77         // InstanceIDs returned by the instances' ID() methods.
  78         Instances(context.Context) ([]Instance, error)
  79
  80         // Stop any background tasks and release other resources.
  81         Stop()
  82 }