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
- type TrackFrequencyConfig
- type TrackResponse
Constants ¶
This section is empty.
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
// 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
Source Files
Directories