Package admission implements CIPD deployment admission plugins.



This section is empty.


View Source
var ErrAborted = errors.Reason("the admission plugin is terminating").Err()

ErrAborted is returned by CheckAdmission promise when the plugin terminates.


func RunPlugin

func RunPlugin(ctx context.Context, stdin io.ReadCloser, version string, handler Handler) error

RunPlugin executes the run loop of an admission plugin.

It connects to the host and starts handling admission checks (each in an individual goroutine) by calling the handler.

Blocks until the stdin closes (which indicates the plugin should terminate).


type Handler

type Handler func(ctx context.Context, req *protocol.Admission, info InstanceInfo) error

Handler handles one admission request.

Called in a separate internal goroutine. It should return a grpc status error. To decide it can use the given `info` to fetch additional data about the package instance.

type InstanceInfo

type InstanceInfo interface {
	// VisitMetadata visits metadata entries attached to the package instance.
	// Either visits all metadata or only entries with requested keys. Visits
	// entries in order of their registration time (the most recent first).
	// Fetches them in pages of `pageSize`. If `pageSize` is negative or zero,
	// uses some default size.
	// Calls `cb` for each visited entry until all entries are successfully
	// visited or the callback returns false. Returns an error if the RPC to
	// the CIPD backend fails.
	VisitMetadata(ctx context.Context, keys []string, pageSize int, cb func(md *api.InstanceMetadata) bool) error

InstanceInfo fetches additional information about a package instance being checked for admission by the handler.

type Plugin

type Plugin struct {
	// contains filtered or unexported fields

Plugin launches and communicates with an admission plugin.

It is instantiated by the CIPD client if it detects there's an admission plugin configured.

func NewPlugin

func NewPlugin(ctx context.Context, host *plugin.Host, args []string) *Plugin

NewPlugin returns a host-side representation of an admission plugin.

The returned *Plugin can be used right away to enqueue admission checks. The plugin subprocess will lazily be started on the first CheckAdmission call. All enqueued checks will eventually be processed by the plugin or rejected if the plugin fails to start.

The context is used for logging from the plugin.

func (*Plugin) CheckAdmission

func (p *Plugin) CheckAdmission(pin common.Pin) *Promise

CheckAdmission enqueues an admission check to be performed by the plugin.

The plugin will be asked if it's OK to deploy a package with the given pin hosted on the CIPD service used by the running CIPD client.

Returns a promise which is resolved when the result is available. If such check is already pending (or has been done before), returns an existing (perhaps already resolved) promise.

func (*Plugin) ClearCache

func (p *Plugin) ClearCache()

ClearCache drops all resolved promises to free up some memory.

func (*Plugin) Close

func (p *Plugin) Close(ctx context.Context)

Close terminates the plugin (if it was running) and aborts all pending checks.

Tries to gracefully terminate the plugin, killing it with SIGKILL on the context timeout or after 5 sec.

Note that calling Close is not necessary if the plugin host itself terminates. The plugin subprocess will be terminated by the host in this case.

type Promise

type Promise struct {
	// contains filtered or unexported fields

Promise is a pending or finished result of an admission check.

func (*Promise) Wait

func (p *Promise) Wait(ctx context.Context) error

Wait blocks until the promise is fulfilled or the context expires.

Returns nil if the admission check passed.


Path Synopsis