github.com/juju/juju@v0.0.0-20240430160146-1752b71fcf00/rpc/params/deploy.go (about)

     1  // Copyright 2021 Canonical Ltd.
     2  // Licensed under the AGPLv3, see LICENCE file for details.
     3  
     4  package params
     5  
     6  import "encoding/json"
     7  
     8  // DeployRequest describes a request to transactionally deploy a base bundle
     9  // which may be optionally accompanied by one or more overlay documents.
    10  type DeployRequest struct {
    11  	Options DeployOptions `json:"options"`
    12  
    13  	// A set of bundles to be deployed.
    14  	//
    15  	// The first entry in the bundle list must always point to the base
    16  	// bundle; all subsequent target attachments will be interpreted as
    17  	// overlays. The first entry may still contain a multi-doc bundle
    18  	// but the same rules apply (i.e. the first doc will be treated as
    19  	// the base bundle).
    20  	//
    21  	// Clients may optionally generate and append an additional overlay to
    22  	// model any overrides that the user specified when invoking the deploy
    23  	// command (e.g. specify trust, endpoint bindings, deployment targets,
    24  	// number of units etc.).
    25  	Bundles []DeployAttachment `json:"targets"`
    26  
    27  	// A list of additional information attachments provided by the client
    28  	// when retrying a deploy request after the controller responds with
    29  	// an ErrAdditionalInformationRequired error.
    30  	Attachments []DeployAttachment `json:"attachments,omitempty"`
    31  }
    32  
    33  // DeployMode specifies the deploy mode that the controller should use.
    34  type DeployMode string
    35  
    36  const (
    37  	// DeployModeAdditive instructs the controller to perform a diff against
    38  	// the current model and only create entities that are not currently
    39  	// part of the model.
    40  	DeployModeAdditive DeployMode = "additive"
    41  )
    42  
    43  // DeployOptions encapsulates the set of options that clients may provide to
    44  // control a server-side deployment.
    45  type DeployOptions struct {
    46  	// Specifies the deploy mode that the controller should use.
    47  	Mode DeployMode `json:"mode"`
    48  
    49  	// An optional deployment ID to associate with the entities that will
    50  	// be created as part of this deployment. If omitted, the controller
    51  	// will allocate (and return) a unique deployment ID.
    52  	DeploymentID string `json:"deployment-id,omitempty"`
    53  
    54  	// If set to true, the controller will not perform any changes but
    55  	// simply return back the list of operations that would normally
    56  	// perform.
    57  	DryRun bool `json:"dry-run"`
    58  
    59  	// Force allows clients to effectively bypass the safety checks
    60  	// performed by the controller and force the deployment to proceed.
    61  	// Warning: using force may cause things to break.
    62  	Force bool `json:"force"`
    63  }
    64  
    65  // DeployAttachment describes a generic payload which the client provides as
    66  // part of a deploy request.
    67  type DeployAttachment struct {
    68  	// A URI describing the attachment. The URI schema dicates the
    69  	// attachment type.
    70  	URI string `json:"uri"`
    71  
    72  	// When the attachment points to a resource that is local to the client
    73  	// (e.g. a bundle, include file, controller details etc.), Data will
    74  	// contain a serialized version of the attachment contents.
    75  	Data json.RawMessage `json:"data,omitempty"`
    76  }
    77  
    78  // DeployResult describes the outcome of a deploy request.
    79  type DeployResult struct {
    80  	// DeploymentID is the ID that the controller associated with this
    81  	// deployment. It is only populated when the deploy request was
    82  	// successful.
    83  	DeploymentID string `json:"deployment-id,omitempty"`
    84  
    85  	// DeploymentLog contains the list of changes performed by the controller
    86  	// as part of the deployment. It is only populated when the deploy request
    87  	// was successful.
    88  	DeploymentLog []string `json:"deployment-log,omitempty"`
    89  
    90  	// Error is populated when the deploy request failed. Clients should
    91  	// always check if the controller responded with an
    92  	// ErrAdditionalInformationRequired code and retry the original request
    93  	// with the required information attached.
    94  	Error *Error `json:"error,omitempty"`
    95  }