plan

Documentation

Overview

Package plan provides an API to interact with a deployment's pending plan. It's mainly structured in two primitives: TrackChanges and Stream.

There are a couple of ways to track a deployment's change, by Deployment ID or by Resource ID and Kind (elasticsearch, kibana, apm, appsearch, etc).

Although the plan package is ready for external consumption, if your goal is track and stream the changes to a device in either Text or JSON, please take a look at github.com/elastic/cloud-sdk-go/pkg/plan/planutil.

 channel, err := plan.TrackChange(plan.TrackChangeParams{
	API:              &api.API{}, // A real API instance needs to be used.
	DeploymentID:     "2e9c997ff4d0bfc273da17f549e45e76",
 // ResourceID:    "6779ce55fc0646309ef812d007bb2526",
 // Kind:          "elasticsearch",
	Config: plan.TrackFrequencyConfig{
		MaxRetries:    2, // # of API failures to accept. 2-4 recommended.
		PollFrequency: time.Second * 5, // 2-10s recommended.
	},
 })
 if err != nil {
	return err
 }

 // Alternatively, plan.StreamJSON(channel, os.Stdout, false) can be used to
 // print JSON formatted updates to an io.Writer.
 if err := plan.Stream(channel, os.Stdout); err != nil {
	 return err
 }

Legacy Documentation

The plan.Track function has been marked as deprecated and will be removed in a future version, please refrain from using it or migrate to a new version before the code is removed. See below.

channel, err := plan.Track(plan.TrackParams{
	API:           params.API,
	ID:            params.ID,
	Kind:          params.Kind,
	PollFrequency: time.Second,
	MaxRetries:    4,
})
if err != nil {
	return err
}

plan.Stream(channel, params.Output)

Index

• Variables
• func GetStepName(log []*models.ClusterPlanStepInfo) (string, error)
• func LookupByResourceIdQuery(resourceID string) *models.SearchRequest
• func NewReverseLookupQuery(resourceID, kind string) *models.SearchRequest
• func StepErrorOrUnknownError(step *models.ClusterPlanStepInfo) error
• func Stream(channel <-chan TrackResponse, device io.Writer) error
• func StreamFunc(channel <-chan TrackResponse, function func(TrackResponse)) error
• func StreamJSON(channel <-chan TrackResponse, device io.Writer, pretty bool) error
• func TrackChange(params TrackChangeParams) (<-chan TrackResponse, error)
• type FailureDetails
• type TrackChangeParams
  • func (params TrackChangeParams) Validate() error
• type TrackFrequencyConfig
  • func (params *TrackFrequencyConfig) Validate() error
• type TrackResponse
  • func (res TrackResponse) Error() string
  • func (res TrackResponse) String() string

Variables

var (
	// ErrPlanFinished is returned when a cluster has no plan PlanStepInfo
	ErrPlanFinished = errors.New("finished all the plan steps")
)

Functions

func GetStepName

func GetStepName(log []*models.ClusterPlanStepInfo) (string, error)

GetStepName analyzes the last step in a plan and returns the step id and: 1. If the ID is plan-completed, and the status == "error", returns the error. 2. If the ID is plan-completed, and the status != "error" returns the ErrPlanFinished. 3. If none of the above, returns no error.

func LookupByResourceIdQuery

func LookupByResourceIdQuery(resourceID string) *models.SearchRequest

LookupByResourceIdQuery can be used to find a deployment by a resource-id (can be any kind e.g. elasticsearch, kibana, etc.) (Builds a query that searches all possible kinds for the resource-id)

func NewReverseLookupQuery

func NewReverseLookupQuery(resourceID, kind string) *models.SearchRequest

NewReverseLookupQuery can be used to look up a deployment's ID by specifying the resource kind and ID (elasticsearch, 6779ce55fc0646309ef812d007bb2526).

func StepErrorOrUnknownError

func StepErrorOrUnknownError(step *models.ClusterPlanStepInfo) error

StepErrorOrUnknownError returns the last step message as an error except when the step InfoLog is empty, in which case it returns errorPlanFailedUnknown.

func Stream

func Stream(channel <-chan TrackResponse, device io.Writer) error

Stream prints a text formatted line on each TrackResponse received by the channel, unless the sender closes the channel when it has finished, calling this function will block execution until the received channel is closed.

func StreamFunc

func StreamFunc(channel <-chan TrackResponse, function func(TrackResponse)) error

StreamFunc is the underlying function used by Stream and StreamJSON. If used directly it allows the user to perform an custom action on each received response. Unless the sender closes the channel when it has finished, calling this function will block execution forever. If the plan failed, it returns the error that made the plan fail.

func StreamJSON

func StreamJSON(channel <-chan TrackResponse, device io.Writer, pretty bool) error

StreamJSON prints a json formatted line for on each TrackResponse received by the channel, if pretty is set to true, the message will be intended with 2 spaces. Unless the sender closes the channel when it has finished, calling this function will block execution forever.

func TrackChange

func TrackChange(params TrackChangeParams) (<-chan TrackResponse, error)

TrackChange iterates over a deployment's resources pending plans, sending updates to the returned channel in the form of TrackResponse every frequency period configured in the parameter's TrackFrequencyConfig. When all of deployment's resources pending plans have finished, the channel is automatically closed by the goroutine that this function launches. It is possible to iterate with a for loop and assume that the loop will exit after all of the updates have been sent and the channel has been closed. If a ResourceID and Kind are set instead of the DeploymentID, a reverse lookup will be performed in order to find the DeploymentID and be able to track the pending plan.

Types

type FailureDetails

type FailureDetails struct {
	// A map with details for the log about what happened during the step execution. Keys and values for are always both strings, representing the name of the detail and its value, respectively.
	Details map[string]string `json:"details"`

	// The failure type, in case the step failed
	FailureType string `json:"failure_type,omitempty"`

	// A json object with sensitive details for the log, visible only to admins. May contain nested json objects.
	Internal map[string]string `json:"internal,omitempty"`
}

FailureDetails contains the details for a failure.

type TrackChangeParams

type TrackChangeParams struct {
	*api.API

	Context context.Context

	// DeploymentID to track its resource changes. Incompatible with ResourceID
	// and Kind.
	DeploymentID string

	// ResourceID to track (Formerly Cluster ID). Incompatible with DeploymentID
	ResourceID string

	// Resource kind to track. Incompatible with DeploymentID
	Kind string

	// IgnoreDownstream if set, will skip sending updates for any workload
	// plan changes other than the specified Kind. Only takes effect when Kind
	// and ResourceID is set.
	IgnoreDownstream bool

	// Tracking settings
	Config TrackFrequencyConfig
}

TrackChangeParams is consumed by TrackChange. It can be used to track a whole deployment's resource changes or a specific resource change. DeploymentID and ResourceID with Kind cannot be used at the same time.

func (TrackChangeParams) Validate

func (params TrackChangeParams) Validate() error

Validate ensures the parameters are usable by the consuming function.

type TrackFrequencyConfig

type TrackFrequencyConfig struct {
	// PollFrequency is the duration to use to poll the API for new changes
	// on the pending plan. The recommended setting is from 2 to 30 seconds.
	PollFrequency time.Duration

	// If set to > 1, allows up to that number of errors coming from the API.
	// It controls how many API errors can be tolerated. Or how many times
	// the polling has to come back with no changes in order to consider the
	// plan change finished.
	MaxRetries int
}

TrackFrequencyConfig controls how the TrackChange function polls the API.

func (*TrackFrequencyConfig) Validate

func (params *TrackFrequencyConfig) Validate() error

Validate ensures the parameters are usable by the consuming function.

type TrackResponse

type TrackResponse struct {
	ID   string `json:"id,omitempty"`
	Kind string `json:"kind,omitempty"`
	Step string `json:"step,omitempty"`
	Err  error  `json:"err,omitempty"`

	// Introduced as part of the Deployment Plan Tracker
	DeploymentID string          `json:"deployment_id,omitempty"`
	RefID        string          `json:"ref_id,omitempty"`
	Duration     strfmt.Duration `json:"duration,omitempty"`

	// Introduced as part of the plan failure categorization
	FailureDetails *FailureDetails `json:"failure_details,omitempty"`

	Finished bool `json:"finished,omitempty"`
	// contains filtered or unexported fields
}

TrackResponse is returned by Track and indicates the progress of a pending plan.

func (TrackResponse) Error

func (res TrackResponse) Error() string

func (TrackResponse) String

func (res TrackResponse) String() string