sdk

package module
v0.0.0-...-75f6e86 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2025 License: Apache-2.0 Imports: 31 Imported by: 0

README

Piped Plugin SDK for Go

This repository contains the SDK for developing piped plugins.

Note on Creating Issues and Pull Requests

Issues for this repository are managed in pipe-cd/pipecd. Please create issues there if you have any questions or feature requests.

This repository is automatically synced from the pkg/plugin/sdk directory in the pipe-cd/pipecd repository. To contribute, please submit pull requests to the pipe-cd/pipecd repository.

Documentation

Index

Examples

Constants

View Source 
const (
	// MetadataKeyStageDisplay is the key of the stage metadata to be displayed on the deployment detail UI.
	MetadataKeyStageDisplay = model.MetadataKeyStageDisplay
	// MetadataKeyStageApprovedUsers is the key of the metadata of who approved the stage.
	// It will be displayed in the DEPLOYMENT_APPROVED notification.
	// e.g. user-1,user-2
	MetadataKeyStageApprovedUsers = model.MetadataKeyStageApprovedUsers
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ApplicationConfig 

type ApplicationConfig[Spec any] struct {

	// Spec is the plugin spec of the application.
	Spec *Spec
	// contains filtered or unexported fields
}

ApplicationConfig is the configuration of the application.

func LoadApplicationConfigForTest 

func LoadApplicationConfigForTest[Spec any](t *testing.T, filename string, pluginName string) *ApplicationConfig[Spec]

LoadApplicationConfigForTest loads the application config from the given filename. When the error occurs, it will call t.Fatal/t.Fatalf and stop the test. This function is only used in the tests.

NOTE: we want to put this function under package for testing like sdktest, but we can't do that because we don't want to make public parsePluginConfig in the ApplicationConfig struct.

func (*ApplicationConfig[Spec]) HasStage 

func (c *ApplicationConfig[Spec]) HasStage(name string) bool

HasStage returns true if the application config has a stage with the given name.

func (*ApplicationConfig[Spec]) UnmarshalJSON 

func (c *ApplicationConfig[Spec]) UnmarshalJSON(data []byte) error

func (*ApplicationConfig[Spec]) Validate 

func (c *ApplicationConfig[Spec]) Validate() error

type ApplicationHealthStatus 

type ApplicationHealthStatus int

ApplicationHealthStatus represents the health status of an application. 

const (
	// ApplicationHealthStateUnknown represents the unknown health status of an application.
	ApplicationHealthStateUnknown ApplicationHealthStatus = iota
	// ApplicationHealthStateHealthy represents the healthy health status of an application.
	ApplicationHealthStateHealthy
	// ApplicationHealthStateOther represents the other health status of an application.
	ApplicationHealthStateOther
)

type ApplicationLiveState 

type ApplicationLiveState struct {
	Resources []ResourceState
}

ApplicationLiveState represents the live state of an application.

type ApplicationSyncState 

type ApplicationSyncState struct {
	// Status is the sync status of the application.
	Status ApplicationSyncStatus
	// ShortReason is the short reason of the sync status.
	// for example, "The service manifest doesn't be synced"
	ShortReason string
	// Reason is the reason of the sync status.
	// actually, it's the difference between the desired state and the live state.
	Reason string
}

ApplicationSyncState represents the sync state of an application.

type ApplicationSyncStatus 

type ApplicationSyncStatus int

ApplicationSyncStatus represents the sync status of an application. 

const (
	// ApplicationSyncStateUnknown represents the unknown sync status of an application.
	ApplicationSyncStateUnknown ApplicationSyncStatus = iota
	// ApplicationSyncStateSynced represents the synced sync status of an application.
	ApplicationSyncStateSynced
	// ApplicationSyncStateOutOfSync represents the out-of-sync sync status of an application.
	ApplicationSyncStateOutOfSync
	// ApplicationSyncStateInvalidConfig represents the invalid-config sync status of an application.
	ApplicationSyncStateInvalidConfig
)

type ArtifactVersion 

type ArtifactVersion struct {
	// Version is the version of the artifact.
	Version string
	// Name is the name of the artifact.
	Name string
	// URL is the URL of the artifact.
	URL string
}

ArtifactVersion represents the version of an artifact.

type BuildPipelineSyncStagesInput 

type BuildPipelineSyncStagesInput struct {
	// Request is the request to build pipeline sync stages.
	Request BuildPipelineSyncStagesRequest
	// Client is the client to interact with the piped.
	Client *Client
	// Logger is the logger to log the events.
	Logger *zap.Logger
}

BuildPipelineSyncStagesInput is the input for the BuildPipelineSyncStages method.

type BuildPipelineSyncStagesRequest 

type BuildPipelineSyncStagesRequest struct {
	// Rollback indicates whether the stages for rollback are requested.
	Rollback bool
	// Stages contains the stage names and their configurations.
	Stages []StageConfig
}

BuildPipelineSyncStagesRequest is the request to build pipeline sync stages. Rollback indicates whether the stages for rollback are requested.

type BuildPipelineSyncStagesResponse 

type BuildPipelineSyncStagesResponse struct {
	Stages []PipelineStage
}

BuildPipelineSyncStagesResponse is the response of the request to build pipeline sync stages.

type BuildQuickSyncStagesInput 

type BuildQuickSyncStagesInput struct {
	// Request is the request to build pipeline sync stages.
	Request BuildQuickSyncStagesRequest
	// Client is the client to interact with the piped.
	Client *Client
	// Logger is the logger to log the events.
	Logger *zap.Logger
}

BuildQuickSyncStagesInput is the input for the BuildQuickSyncStages method.

type BuildQuickSyncStagesRequest 

type BuildQuickSyncStagesRequest struct {
	// Rollback indicates whether the stages for rollback are requested.
	Rollback bool
}

BuildQuickSyncStagesRequest is the request to build quick sync stages. Rollback indicates whether the stages for rollback are requested.

type BuildQuickSyncStagesResponse 

type BuildQuickSyncStagesResponse struct {
	Stages []QuickSyncStage
}

BuildQuickSyncStagesResponse is the response of the request to build quick sync stages.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a toolkit for interacting with the piped service. It provides methods to call the piped service APIs. It's a wrapper around the raw piped service client.

func NewClient 

func NewClient(base *pluginServiceClient, pluginName, applicationID, stageID string, lp StageLogPersister, tr *toolregistry.ToolRegistry) *Client

NewClient creates a new client. DO NOT USE this function except in tests. FIXME: Remove this function and make a better way for tests.

func (*Client) GetApplicationSharedObject 

func (c *Client) GetApplicationSharedObject(ctx context.Context, key string) ([]byte, error)

GetApplicationSharedObject gets the application object which is shared across deployments.

func (*Client) GetDeploymentPluginMetadata 

func (c *Client) GetDeploymentPluginMetadata(ctx context.Context, key string) (string, error)

GetDeploymentPluginMetadata gets the metadata of the current deployment and plugin.

func (*Client) GetDeploymentSharedMetadata 

func (c *Client) GetDeploymentSharedMetadata(ctx context.Context, key string) (string, error)

GetDeploymentSharedMetadata gets the metadata of the current deployment which is shared among piped and plugins.

func (*Client) GetStageMetadata 

func (c *Client) GetStageMetadata(ctx context.Context, key string) (string, error)

GetStageMetadata gets the metadata of the current stage.

func (Client) ListStageCommands 

func (c Client) ListStageCommands(ctx context.Context, commandTypes ...model.Command_Type) iter.Seq2[*StageCommand, error]

ListStageCommands returns the list of stage commands of the given command types.

func (*Client) LogPersister 

func (c *Client) LogPersister() StageLogPersister

LogPersister returns the stage log persister. Use this to persist the stage logs and make it viewable on the UI. This method should be called only when the client is working with a specific stage, for example, when this client is passed as the ExecuteStage method's argument. Otherwise, it will return nil. TODO: we should consider returning an error instead of nil, or return logger which prints to stdout.

func (*Client) PutApplicationSharedObject 

func (c *Client) PutApplicationSharedObject(ctx context.Context, key string, object []byte) error

PutApplicationSharedObject stores the application object which is shared across deployments.

func (*Client) PutDeploymentPluginMetadata 

func (c *Client) PutDeploymentPluginMetadata(ctx context.Context, key, value string) error

PutDeploymentPluginMetadata stores the metadata of the current deployment and plugin.

func (*Client) PutDeploymentPluginMetadataMulti 

func (c *Client) PutDeploymentPluginMetadataMulti(ctx context.Context, metadata map[string]string) error

PutDeploymentPluginMetadataMulti stores the multiple metadata of the current deployment and plugin.

func (*Client) PutStageMetadata 

func (c *Client) PutStageMetadata(ctx context.Context, key, value string) error

PutStageMetadata stores the metadata of the current stage.

func (*Client) PutStageMetadataMulti 

func (c *Client) PutStageMetadataMulti(ctx context.Context, metadata map[string]string) error

PutStageMetadataMulti stores the multiple metadata of the current stage.

func (*Client) ToolRegistry 

func (c *Client) ToolRegistry() *toolregistry.ToolRegistry

ToolRegistry returns the tool registry. Use this to install and get the path of the tools used in the plugin.

type CommandType 

type CommandType int32

CommandType represents the type of the command. 

const (
	CommandTypeApproveStage CommandType = iota
	CommandTypeSkipStage
)

type ConfigNone 

type ConfigNone = *struct{}

ConfigNone is a type alias for a pointer to a struct with an empty struct as the generic type parameter. This utility is defined for plugins which has no config handling in ExecuteStage.

type DeployTarget 

type DeployTarget[Config any] struct {
	// The name of the deploy target.
	Name string `json:"name"`
	// The labes of the deploy target.
	Labels map[string]string `json:"labels,omitempty"`
	// The configuration of the deploy target.
	Config Config `json:"config"`
}

DeployTarget defines the deploy target configuration for the piped.

type DeployTargetsNone 

type DeployTargetsNone = []*DeployTarget[struct{}]

DeployTargetsNone is a type alias for a slice of pointers to DeployTarget with an empty struct as the generic type parameter. It represents a case where there are no deployment targets. This utility is defined for plugins which has no deploy targets handling in ExecuteStage.

type Deployment 

type Deployment struct {
	// ID is the unique identifier of the deployment.
	ID string
	// ApplicationID is the unique identifier of the application.
	ApplicationID string
	// ApplicationName is the name of the application.
	ApplicationName string
	// PipedID is the unique identifier of the piped that is running the deployment.
	PipedID string
	// ProjectID is the unique identifier of the project that the application belongs to.
	ProjectID string
	// TriggeredBy is the name of the entity that triggered the deployment.
	TriggeredBy string
	// CreatedAt is the time when the deployment was created.
	CreatedAt int64
	// RepositoryURL is the repo remote path
	RepositoryURL string
	// Summary is the simple description about what this deployment does
	Summary string
	// Labels are custom attributes to identify applications
	Labels map[string]string
}

Deployment represents the deployment that the stage is running. This is read-only.

type DeploymentPlugin 

type DeploymentPlugin[Config, DeployTargetConfig, ApplicationConfigSpec any] interface {
	StagePlugin[Config, DeployTargetConfig, ApplicationConfigSpec]

	// DetermineVersions determines the versions of the resources that will be deployed.
	DetermineVersions(context.Context, *Config, *DetermineVersionsInput[ApplicationConfigSpec]) (*DetermineVersionsResponse, error)
	// DetermineStrategy determines the strategy to deploy the resources.
	// This is called when the strategy was not determined by common logic, including judging by the pipeline length, whether it is the first deployment, and so on.
	// It should return (nil, nil) if the plugin does not have specific logic for DetermineStrategy.
	DetermineStrategy(context.Context, *Config, *DetermineStrategyInput[ApplicationConfigSpec]) (*DetermineStrategyResponse, error)
	// BuildQuickSyncStages builds the stages that will be executed during the quick sync process.
	BuildQuickSyncStages(context.Context, *Config, *BuildQuickSyncStagesInput) (*BuildQuickSyncStagesResponse, error)
}

DeploymentPlugin is the interface that be implemented by a full-spec deployment plugin. This kind of plugin should implement all methods to manage resources and execute stages. The Config and DeployTargetConfig are the plugin's config defined in piped's config.

type DeploymentPluginServiceServer 

type DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec any] struct {
	deployment.UnimplementedDeploymentServiceServer
	// contains filtered or unexported fields
}

DeploymentPluginServiceServer is the gRPC server that handles requests from the piped.

func (*DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) BuildPipelineSyncStages 

func (s *DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) BuildPipelineSyncStages(ctx context.Context, request *deployment.BuildPipelineSyncStagesRequest) (*deployment.BuildPipelineSyncStagesResponse, error)

func (*DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) BuildQuickSyncStages 

func (s *DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) BuildQuickSyncStages(ctx context.Context, request *deployment.BuildQuickSyncStagesRequest) (*deployment.BuildQuickSyncStagesResponse, error)

func (*DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) DetermineStrategy 

func (s *DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) DetermineStrategy(ctx context.Context, request *deployment.DetermineStrategyRequest) (*deployment.DetermineStrategyResponse, error)

func (*DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) DetermineVersions 

func (s *DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) DetermineVersions(ctx context.Context, request *deployment.DetermineVersionsRequest) (*deployment.DetermineVersionsResponse, error)

func (*DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) ExecuteStage 

func (s *DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) ExecuteStage(ctx context.Context, request *deployment.ExecuteStageRequest) (response *deployment.ExecuteStageResponse, _ error)

func (*DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) FetchDefinedStages 

func (s *DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) FetchDefinedStages(context.Context, *deployment.FetchDefinedStagesRequest) (*deployment.FetchDefinedStagesResponse, error)

func (*DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) Register 

func (s *DeploymentPluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) Register(server *grpc.Server)

Register registers the server to the given gRPC server.

type DeploymentSource 

type DeploymentSource[Spec any] struct {
	// ApplicationDirectory is the directory where the source code is located.
	ApplicationDirectory string
	// CommitHash is the git commit hash of the source code.
	CommitHash string
	// ApplicationConfig is the configuration of the application.
	ApplicationConfig *ApplicationConfig[Spec]
	// ApplicationConfigFilename is the name of the file that contains the application configuration.
	// The plugins can use this to avoid mistakenly reading this file as a manifest to deploy.
	ApplicationConfigFilename string
	// SharedConfigDirectory is the directory where the shared configuration in the repository is located.
	SharedConfigDirectory string
}

DeploymentSource represents the source of the deployment.

func (*DeploymentSource[Spec]) AppConfig 

func (d *DeploymentSource[Spec]) AppConfig() (*ApplicationConfig[Spec], error)

AppConfig returns the application config.

type DetermineStrategyInput 

type DetermineStrategyInput[ApplicationConfigSpec any] struct {
	// Request is the request to determine the strategy.
	Request DetermineStrategyRequest[ApplicationConfigSpec]
	// Client is the client to interact with the piped.
	Client *Client
	// Logger is the logger to log the events.
	Logger *zap.Logger
}

DetermineStrategyInput is the input for the DetermineStrategy method.

type DetermineStrategyRequest 

type DetermineStrategyRequest[ApplicationConfigSpec any] struct {
	// Deployment is the deployment that the strategy will be determined.
	Deployment Deployment
	// RunningDeploymentSource is the source of the running deployment.
	RunningDeploymentSource DeploymentSource[ApplicationConfigSpec]
	// TargetDeploymentSource is the source of the target deployment.
	TargetDeploymentSource DeploymentSource[ApplicationConfigSpec]
}

DetermineStrategyRequest is the request to determine the strategy.

type DetermineStrategyResponse 

type DetermineStrategyResponse struct {
	// Strategy is the strategy to deploy the resources.
	Strategy SyncStrategy
	// Summary is the summary of the strategy.
	Summary string
}

DetermineStrategyResponse is the response of the request to determine the strategy.

type DetermineVersionsInput 

type DetermineVersionsInput[ApplicationConfigSpec any] struct {
	// Request is the request to determine versions.
	Request DetermineVersionsRequest[ApplicationConfigSpec]
	// Client is the client to interact with the piped.
	Client *Client
	// Logger is the logger to log the events.
	Logger *zap.Logger
}

DetermineVersionsInput is the input for the DetermineVersions method.

type DetermineVersionsRequest 

type DetermineVersionsRequest[ApplicationConfigSpec any] struct {
	// Deloyment is the deployment that the versions will be determined.
	Deployment Deployment
	// DeploymentSource is the source of the deployment.
	DeploymentSource DeploymentSource[ApplicationConfigSpec]
}

DetermineVersionsRequest is the request to determine versions.

type DetermineVersionsResponse 

type DetermineVersionsResponse struct {
	// Versions contains the versions of the resources.
	Versions []ArtifactVersion
}

DetermineVersionsResponse is the response of the request to determine versions.

type ExecuteStageInput 

type ExecuteStageInput[ApplicationConfigSpec any] struct {
	// Request is the request to execute a stage.
	Request ExecuteStageRequest[ApplicationConfigSpec]
	// Client is the client to interact with the piped.
	Client *Client
	// Logger is the logger to log the events.
	Logger *zap.Logger
}

ExecuteStageInput is the input for the ExecuteStage method.

type ExecuteStageRequest 

type ExecuteStageRequest[ApplicationConfigSpec any] struct {
	// The name of the stage to execute.
	StageName string
	// Json encoded configuration of the stage.
	StageConfig []byte

	// RunningDeploymentSource is the source of the running deployment.
	RunningDeploymentSource DeploymentSource[ApplicationConfigSpec]

	// TargetDeploymentSource is the source of the target deployment.
	TargetDeploymentSource DeploymentSource[ApplicationConfigSpec]

	// The deployment that the stage is running.
	Deployment Deployment
}

ExecuteStageRequest is the request to execute a stage.

type ExecuteStageResponse 

type ExecuteStageResponse struct {
	Status StageStatus
}

ExecuteStageResponse is the response of the request to execute a stage.

type GetLivestateInput 

type GetLivestateInput[ApplicationConfigSpec any] struct {
	// Request is the request for getting the live state.
	Request GetLivestateRequest[ApplicationConfigSpec]
	// Client is the client for accessing the piped API.
	Client *Client
	// Logger is the logger for logging.
	Logger *zap.Logger
}

GetLivestateInput is the input for the GetLivestate method.

type GetLivestateRequest 

type GetLivestateRequest[ApplicationConfigSpec any] struct {
	// PipedID is the ID of the piped.
	PipedID string
	// ApplicationID is the ID of the application.
	ApplicationID string
	// ApplicationName is the name of the application.
	ApplicationName string
	// DeploymentSource is the source of the deployment.
	DeploymentSource DeploymentSource[ApplicationConfigSpec]
}

GetLivestateRequest is the request for the GetLivestate method.

type GetLivestateResponse 

type GetLivestateResponse struct {
	// LiveState is the live state of the application.
	LiveState ApplicationLiveState
	// SyncState is the sync state of the application.
	SyncState ApplicationSyncState
}

GetLivestateResponse is the response for the GetLivestate method.

type GetPlanPreviewInput 

type GetPlanPreviewInput[ApplicationConfigSpec any] struct {
	// Request is the request for getting the plan preview.
	Request GetPlanPreviewRequest[ApplicationConfigSpec]
	// Client is the client for accessing the piped API.
	Client *Client
	// Logger is the logger for logging.
	Logger *zap.Logger
}

GetPlanPreviewInput is the input for the GetPlanPreview method.

type GetPlanPreviewRequest 

type GetPlanPreviewRequest[ApplicationConfigSpec any] struct {
	// ApplicationID is the ID of the application.
	ApplicationID string
	// TargetDeploymentSource is the target source of the deployment.
	TargetDeploymentSource DeploymentSource[ApplicationConfigSpec]
}

GetPlanPreviewRequest is the request for the GetPlanPreview method.

type GetPlanPreviewResponse 

type GetPlanPreviewResponse struct {
	// Summary is a human-readable summary of the plan preview.
	Summary string
	// NoChange indicates whether any changes were detected.
	NoChange bool
	// Details contains the detailed plan preview information.
	Details []byte
}

GetPlanPreviewResponse is the response for the GetPlanPreview method.

type InitializeInput 

type InitializeInput[Config, DeployTargetConfig any] struct {
	// Config is the configuration of the plugin.
	Config *Config
	// DeployTargets is the deploy targets of the plugin.
	DeployTargets map[string]*DeployTarget[DeployTargetConfig]
	// Logger is the logger for the plugin.
	Logger *zap.Logger
}

InitializeInput is the input for the Initializer interface.

type Initializer 

type Initializer[Config, DeployTargetConfig any] interface {
	// Initialize initializes the plugin with the given context and input.
	// It is called multiple times when the plugin is registered multiple times, such as deployment, livestate, and plan-preview plugins.
	// It is recommended to use sync.Once to ensure that the plugin is initialized only once.
	Initialize(context.Context, *InitializeInput[Config, DeployTargetConfig]) error
}

Initializer is an interface that defines the Initialize method.

type LivestatePlugin 

type LivestatePlugin[Config, DeployTargetConfig, ApplicationConfigSpec any] interface {
	// GetLivestate returns the live state of the resources in the given application.
	// It returns the resources' live state and the difference between the desired state and the live state.
	// It's allowed to return only the resources' live state if the difference is not available, or only the difference if the live state is not available.
	GetLivestate(context.Context, *Config, []*DeployTarget[DeployTargetConfig], *GetLivestateInput[ApplicationConfigSpec]) (*GetLivestateResponse, error)
}

LivestatePlugin is the interface that must be implemented by a Livestate plugin. In addition to the Plugin interface, it provides a method to get the live state of the resources. The Config and DeployTargetConfig are the plugin's config defined in piped's config.

type LivestatePluginServer 

type LivestatePluginServer[Config, DeployTargetConfig, ApplicationConfigSpec any] struct {
	livestate.UnimplementedLivestateServiceServer
	// contains filtered or unexported fields
}

LivestatePluginServer is a wrapper for LivestatePlugin to satisfy the LivestateServiceServer interface. It is used to register the plugin to the gRPC server.

func (*LivestatePluginServer[Config, DeployTargetConfig, ApplicationConfigSpec]) GetLivestate 

func (s *LivestatePluginServer[Config, DeployTargetConfig, ApplicationConfigSpec]) GetLivestate(ctx context.Context, request *livestate.GetLivestateRequest) (*livestate.GetLivestateResponse, error)

GetLivestate returns the live state of the resources in the given application.

func (*LivestatePluginServer[Config, DeployTargetConfig, ApplicationConfigSpec]) Register 

func (s *LivestatePluginServer[Config, DeployTargetConfig, ApplicationConfigSpec]) Register(server *grpc.Server)

Register registers the plugin to the gRPC server.

type ManualOperation 

type ManualOperation int

ManualOperation represents the manual operation that the user can perform. 

const (
	// ManualOperationNone indicates that there is no manual operation.
	ManualOperationNone ManualOperation = iota
	// ManualOperationSkip indicates that the manual operation is to skip the stage.
	ManualOperationSkip
	// ManualOperationApprove indicates that the manual operation is to approve the stage.
	ManualOperationApprove
)

type PipelineStage 

type PipelineStage struct {
	// Index is the order of the stage in the pipeline.
	// The value must be one of the index of the stage in the request.
	// The rollback stage should have the same index as the original stage.
	Index int
	// Name is the name of the stage.
	// It must be one of the stages returned by FetchDefinedStages.
	Name string
	// Rollback indicates whether the stage is for rollback.
	Rollback bool
	// Metadata contains the metadata of the stage.
	Metadata map[string]string
	// AvailableOperation indicates the manual operation that the user can perform.
	AvailableOperation ManualOperation
	// AuthorizedOperators is the list of usernames who can execute the AvailableOperation.
	AuthorizedOperators []string
}

PipelineStage represents a stage in the pipeline.

type PlanPreviewPlugin 

type PlanPreviewPlugin[Config, DeployTargetConfig, ApplicationConfigSpec any] interface {
	// GetPlanPreview returns the plan preview result of the given application.
	GetPlanPreview(context.Context, *Config, []*DeployTarget[DeployTargetConfig], *GetPlanPreviewInput[ApplicationConfigSpec]) (*GetPlanPreviewResponse, error)
}

PlanPreviewPlugin is the interface that must be implemented by a PlanPreview plugin. In addition to the Plugin interface, it provides a method to get the plan preview result. The Config and DeployTargetConfig are the plugin's config defined in piped's config.

type PlanPreviewPluginServer 

type PlanPreviewPluginServer[Config, DeployTargetConfig, ApplicationConfigSpec any] struct {
	planpreview.UnimplementedPlanPreviewServiceServer
	// contains filtered or unexported fields
}

PlanPreviewPluginServer is a wrapper for PlanPreviewPlugin to satisfy the PlanPreviewServiceServer interface. It is used to register the plugin to the gRPC server.

func (*PlanPreviewPluginServer[Config, DeployTargetConfig, ApplicationConfigSpec]) GetPlanPreview 

func (s *PlanPreviewPluginServer[Config, DeployTargetConfig, ApplicationConfigSpec]) GetPlanPreview(ctx context.Context, request *planpreview.GetPlanPreviewRequest) (*planpreview.GetPlanPreviewResponse, error)

GetPlanPreview returns the plan preview of the resources in the given application.

func (*PlanPreviewPluginServer[Config, DeployTargetConfig, ApplicationConfigSpec]) Register 

func (s *PlanPreviewPluginServer[Config, DeployTargetConfig, ApplicationConfigSpec]) Register(server *grpc.Server)

Register registers the plugin to the gRPC server.

type Plugin 

type Plugin[Config, DeployTargetConfig, ApplicationConfigSpec any] struct {
	// contains filtered or unexported fields
}

Plugin is a wrapper for the plugin. It provides a way to run the plugin with the given config and deploy target config.

func NewPlugin 

func NewPlugin[Config, DeployTargetConfig, ApplicationConfigSpec any](version string, options ...PluginOption[Config, DeployTargetConfig, ApplicationConfigSpec]) (*Plugin[Config, DeployTargetConfig, ApplicationConfigSpec], error)

NewPlugin creates a new plugin.

Example 
plugin, err := NewPlugin("1.0.0",
	WithDeploymentPlugin(ExampleDeploymentPlugin{}),
	WithLivestatePlugin(ExampleLivestatePlugin{}),
)
if err != nil {
	log.Fatal(err)
}

// Run runs the plugin and blocks until the signal is received.
// So you can use it like this:
/*
	if err := plugin.Run(); err != nil {
		log.Fatal(err)
	}
*/

_ = plugin

func (*Plugin[Config, DeployTargetConfig, ApplicationConfigSpec]) Run 

func (p *Plugin[Config, DeployTargetConfig, ApplicationConfigSpec]) Run() error

Run runs the plugin.

type PluginOption 

type PluginOption[Config, DeployTargetConfig, ApplicationConfigSpec any] func(*Plugin[Config, DeployTargetConfig, ApplicationConfigSpec])

PluginOption is a function that configures the plugin.

func WithDeploymentPlugin 

func WithDeploymentPlugin[Config, DeployTargetConfig, ApplicationConfigSpec any](deploymentPlugin DeploymentPlugin[Config, DeployTargetConfig, ApplicationConfigSpec]) PluginOption[Config, DeployTargetConfig, ApplicationConfigSpec]

WithDeploymentPlugin is a function that sets the deployment plugin. This is mutually exclusive with WithStagePlugin.

Example 
plugin, err := NewPlugin("1.0.0",
	WithDeploymentPlugin(ExampleDeploymentPlugin{}),
)
if err != nil {
	log.Fatal(err)
}

// plugin.Run()
_ = plugin

func WithLivestatePlugin 

func WithLivestatePlugin[Config, DeployTargetConfig, ApplicationConfigSpec any](livestatePlugin LivestatePlugin[Config, DeployTargetConfig, ApplicationConfigSpec]) PluginOption[Config, DeployTargetConfig, ApplicationConfigSpec]

WithLivestatePlugin is a function that sets the livestate plugin.

Example 
plugin, err := NewPlugin("1.0.0",
	WithLivestatePlugin(ExampleLivestatePlugin{}),
)
if err != nil {
	log.Fatal(err)
}

// plugin.Run()
_ = plugin

func WithPlanPreviewPlugin 

func WithPlanPreviewPlugin[Config, DeployTargetConfig, ApplicationConfigSpec any](planPreviewPlugin PlanPreviewPlugin[Config, DeployTargetConfig, ApplicationConfigSpec]) PluginOption[Config, DeployTargetConfig, ApplicationConfigSpec]

WithPlanPreviewPlugin is a function that sets the plan preview plugin.

Example 
plugin, err := NewPlugin("1.0.0",
	WithPlanPreviewPlugin(ExamplePlanPreviewPlugin{}),
)
if err != nil {
	log.Fatal(err)
}

// plugin.Run()
_ = plugin

func WithStagePlugin 

func WithStagePlugin[Config, DeployTargetConfig, ApplicationConfigSpec any](stagePlugin StagePlugin[Config, DeployTargetConfig, ApplicationConfigSpec]) PluginOption[Config, DeployTargetConfig, ApplicationConfigSpec]

WithStagePlugin is a function that sets the stage plugin. This is mutually exclusive with WithDeploymentPlugin.

Example 
plugin, err := NewPlugin("1.0.0",
	WithStagePlugin(ExampleStagePlugin{}),
)
if err != nil {
	log.Fatal(err)
}

// plugin.Run()
_ = plugin

type QuickSyncStage 

type QuickSyncStage struct {
	// Name is the name of the stage.
	// It must be one of the stages returned by FetchDefinedStages.
	Name string
	// Description is the description of the stage.
	Description string
	// Rollback indicates whether the stage is for rollback.
	Rollback bool
	// Metadata contains the metadata of the stage.
	Metadata map[string]string
	// AvailableOperation indicates the manual operation that the user can perform.
	AvailableOperation ManualOperation
}

QuickSyncStage represents a stage in the pipeline.

type ResourceHealthStatus 

type ResourceHealthStatus int

ResourceHealthStatus represents the health status of a resource. 

const (
	// ResourceHealthStateUnknown represents the unknown health status of a resource.
	ResourceHealthStateUnknown ResourceHealthStatus = iota
	// ResourceHealthStateHealthy represents the healthy health status of a resource.
	ResourceHealthStateHealthy
	// ResourceHealthStateUnhealthy represents the unhealthy health status of a resource.
	ResourceHealthStateUnhealthy
)

type ResourceState 

type ResourceState struct {
	// ID is the unique identifier of the resource.
	ID string
	// ParentIDs is the list of the parent resource's IDs.
	ParentIDs []string
	// Name is the name of the resource.
	Name string
	// ResourceType is the type of the resource.
	ResourceType string
	// ResourceMetadata is the metadata of the resource.
	ResourceMetadata map[string]string
	// HealthStatus is the health status of the resource.
	HealthStatus ResourceHealthStatus
	// HealthDescription is the description of the health status.
	HealthDescription string
	// DeployTarget is the target where the resource is deployed.
	DeployTarget string
	// CreatedAt is the time when the resource was created.
	CreatedAt time.Time
}

ResourceState represents the live state of a resource.

type StageCommand 

type StageCommand struct {
	Commander string
	Type      CommandType
}

StageCommand represents a command for a stage.

type StageConfig 

type StageConfig struct {
	// Index is the order of the stage in the pipeline.
	Index int
	// Name is the name of the stage.
	// It must be one of the stages returned by FetchDefinedStages.
	Name string
	// Config is the configuration of the stage.
	// It should be marshaled to JSON bytes.
	// The plugin should unmarshal it to the appropriate struct.
	Config []byte
}

StageConfig represents the configuration of a stage.

type StageLogPersister 

type StageLogPersister interface {
	Write(log []byte) (int, error)
	Info(log string)
	Infof(format string, a ...interface{})
	Success(log string)
	Successf(format string, a ...interface{})
	Error(log string)
	Errorf(format string, a ...interface{})
}

StageLogPersister is a interface for persisting the stage logs. Use this to persist the stage logs and make it viewable on the UI.

type StagePlugin 

type StagePlugin[Config, DeployTargetConfig, ApplicationConfigSpec any] interface {
	// FetchDefinedStages returns the list of stages that the plugin can execute.
	FetchDefinedStages() []string
	// BuildPipelineSyncStages builds the stages that will be executed by the plugin.
	// The built pipeline includes non-rollback (defined in the application config) and rollback stages.
	// The request contains only non-rollback stages whose names are listed in FetchDefinedStages() of this plugin.
	//
	// Note about the response indexes:
	//  - For a non-rollback stage, use the index given by the request remaining the execution order.
	//  - For a rollback stage, use one of the indexes given by the request.
	//  - The indexes of the response stages must not be duplicated across non-rollback stages and rollback stages.
	//    A non-rollback stage and a rollback stage can have the same index.
	// For example, given request indexes are {2,4,5}, then
	//  - Non-rollback stages indexes must be {2,4,5}
	//  - Rollback stages indexes must be selected from {2,4,5}.  For a deploymentPlugin, using only {2} is recommended.
	BuildPipelineSyncStages(context.Context, *Config, *BuildPipelineSyncStagesInput) (*BuildPipelineSyncStagesResponse, error)
	// ExecuteStage executes the given stage.
	ExecuteStage(context.Context, *Config, []*DeployTarget[DeployTargetConfig], *ExecuteStageInput[ApplicationConfigSpec]) (*ExecuteStageResponse, error)
}

StagePlugin is the interface implemented by a plugin that focuses on executing generic stages. This kind of plugin may not implement quick sync stages. The Config and DeployTargetConfig are the plugin's config defined in piped's config.

type StagePluginServiceServer 

type StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec any] struct {
	deployment.UnimplementedDeploymentServiceServer
	// contains filtered or unexported fields
}

StagePluginServiceServer is the gRPC server that handles requests from the piped.

func (*StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) BuildPipelineSyncStages 

func (s *StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) BuildPipelineSyncStages(ctx context.Context, request *deployment.BuildPipelineSyncStagesRequest) (*deployment.BuildPipelineSyncStagesResponse, error)

func (*StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) BuildQuickSyncStages 

func (s *StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) BuildQuickSyncStages(context.Context, *deployment.BuildQuickSyncStagesRequest) (*deployment.BuildQuickSyncStagesResponse, error)

func (*StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) DetermineStrategy 

func (s *StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) DetermineStrategy(context.Context, *deployment.DetermineStrategyRequest) (*deployment.DetermineStrategyResponse, error)

func (*StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) DetermineVersions 

func (s *StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) DetermineVersions(context.Context, *deployment.DetermineVersionsRequest) (*deployment.DetermineVersionsResponse, error)

func (*StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) ExecuteStage 

func (s *StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) ExecuteStage(ctx context.Context, request *deployment.ExecuteStageRequest) (response *deployment.ExecuteStageResponse, _ error)

func (*StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) FetchDefinedStages 

func (s *StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) FetchDefinedStages(context.Context, *deployment.FetchDefinedStagesRequest) (*deployment.FetchDefinedStagesResponse, error)

func (*StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) Register 

func (s *StagePluginServiceServer[Config, DeployTargetConfig, ApplicationConfigSpec]) Register(server *grpc.Server)

Register registers the server to the given gRPC server.

type StageStatus 

type StageStatus int

StageStatus represents the current status of a stage of a deployment. 

const (

	// StageStatusSuccess indicates that the stage succeeded.
	StageStatusSuccess StageStatus
	// StageStatusFailure indicates that the stage failed.
	StageStatusFailure
	// StageStatusExited can be used when the stage succeeded and exit the pipeline without executing the following stages.
	StageStatusExited
)

func (StageStatus) String 

func (o StageStatus) String() string

type SyncStrategy 

type SyncStrategy int

SyncStrategy represents the strategy to deploy the resources. 

const (

	// SyncStrategyQuickSync indicates that the resources will be deployed using the quick sync strategy.
	SyncStrategyQuickSync SyncStrategy
	// SyncStrategyPipelineSync indicates that the resources will be deployed using the pipeline sync strategy.
	SyncStrategyPipelineSync
)

Source Files

View all Source files

Directories

Path Synopsis
Package logpersister provides a piped component that enqueues all log blocks from running stages and then periodically sends to the control plane.
 Package logpersister provides a piped component that enqueues all log blocks from running stages and then periodically sends to the control plane.
logpersistertest
toolregistrytest

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.