tcworkermanager

package
v20.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2019 License: MPL-2.0 Imports: 3 Imported by: 0

Documentation

Overview

This service manages workers, including provisioning for dynamic worker pools.

See:

How to use this package

First create a WorkerManager object: 

workerManager := tcworkermanager.New(nil)

and then call one or more of workerManager's methods, e.g.: 

err := workerManager.Ping(.....)

handling any errors... 

if err != nil {
	// handle error...
}

Taskcluster Schema

The source code of this go package was auto-generated from the API definition at <rootUrl>/references/worker-manager/v1/api.json together with the input and output schemas it references,

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AwsProviderType 

type AwsProviderType struct {

	// Instance identity document that is obtained by
	// curl http://169.254.169.254/latest/dynamic/instance-identity/document on the instance
	Document json.RawMessage `json:"document"`

	// The signature for instance identity document. Can be obtained by
	// curl http://169.254.169.254/latest/dynamic/instance-identity/signature on the instance
	Signature string `json:"signature"`
}

Proof that this call is coming from the worker identified by the other fields. The form of this proof varies depending on the provider type.

type Credentials 

type Credentials struct {
	AccessToken string `json:"accessToken"`

	// Note that a certificate may not be provided, if the credentials are not temporary.
	Certificate string `json:"certificate,omitempty"`

	ClientID string `json:"clientId"`
}

The credentials the worker will need to perform its work. Specifically, credentials with scopes * `assume:worker-pool:<workerPoolId>` * `assume:worker-id:<workerGroup>/<workerId>` * `queue:worker-id:<workerGroup>/<workerId>` * `secrets:get:worker-pool:<workerPoolId>` * `queue:claim-work:<workerPoolId>`

type GoogleProviderType 

type GoogleProviderType struct {

	// A JWT token as defined in [this google documentation](https://cloud.google.com/compute/docs/instances/verifying-instance-identity)
	Token string `json:"token"`
}

Proof that this call is coming from the worker identified by the other fields. The form of this proof varies depending on the provider type.

type ProviderList 

type ProviderList struct {

	// Opaque `continuationToken` to be given as query-string option to get the
	// next set of workers in the worker-manager.
	// This property is only present if another request is necessary to fetch all
	// results. In practice the next request with a `continuationToken` may not
	// return additional results, but it can. Thus, you can only be sure to have
	// all the results if you've called `listWorkerPools` with `continuationToken`
	// until you get a result without a `continuationToken`.
	ContinuationToken string `json:"continuationToken,omitempty"`

	// List of all providers
	Providers []Var `json:"providers"`
}

A list of providers

type RegisterWorkerRequest 

type RegisterWorkerRequest struct {

	// The provider that had started the worker and responsible for managing it.
	// Can be different from the provider that's currently in the worker pool config.
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	ProviderID string `json:"providerId"`

	// Worker group to which this worker belongs
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	WorkerGroup string `json:"workerGroup"`

	// Worker ID
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	WorkerID string `json:"workerId"`

	// Proof that this call is coming from the worker identified by the other fields.
	// The form of this proof varies depending on the provider type.
	//
	// One of:
	//   * GoogleProviderType
	//   * StaticProviderType1
	//   * AwsProviderType
	WorkerIdentityProof json.RawMessage `json:"workerIdentityProof"`

	// The ID of this worker pool (of the form `providerId/workerType` for compatibility)
	//
	// Syntax:     ^[a-zA-Z0-9-_]{1,38}/[a-z]([-a-z0-9]{0,36}[a-z0-9])?$
	WorkerPoolID string `json:"workerPoolId"`
}

Request body to `registerWorker`.

type RegisterWorkerResponse 

type RegisterWorkerResponse struct {

	// The credentials the worker
	// will need to perform its work.  Specifically, credentials with scopes
	// * `assume:worker-pool:<workerPoolId>`
	// * `assume:worker-id:<workerGroup>/<workerId>`
	// * `queue:worker-id:<workerGroup>/<workerId>`
	// * `secrets:get:worker-pool:<workerPoolId>`
	// * `queue:claim-work:<workerPoolId>`
	Credentials Credentials `json:"credentials"`

	// Time at which the included credentials will expire.  Workers must either
	// re-register (for static workers) or terminate (for dynamically
	// provisioned workers) before this time.
	Expires tcclient.Time `json:"expires"`
}

Response body to `registerWorker`.

type StaticProviderType 

type StaticProviderType struct {

	// A secret value shared with the worker.  This value must be passed in the `workerIdentityProof` of the `registerWorker` method.
	// The ideal way to generate a secret of this form is `slugid() + slugid()`.
	//
	// Secrets are traded for Taskcluster credentials, and should be treated with similar care.
	// Each worker should have a distinct secret.
	//
	// Syntax:     ^[a-zA-Z0-9_-]{44}$
	StaticSecret string `json:"staticSecret"`
}

Provider-specific information

type StaticProviderType1 

type StaticProviderType1 struct {

	// The secret value that was configured when the worker was created (in `createWorker`).
	//
	// Syntax:     ^[a-zA-Z0-9_-]{44}$
	StaticSecret string `json:"staticSecret"`
}

Proof that this call is coming from the worker identified by the other fields. The form of this proof varies depending on the provider type.

type Var 

type Var struct {

	// The id of this provider
	ProviderID string `json:"providerId"`

	// The provider implementation underlying this provider
	ProviderType string `json:"providerType"`
}

type WorkerCreationRequest 

type WorkerCreationRequest struct {

	// Date and time when this worker will be deleted from the DB
	Expires tcclient.Time `json:"expires"`

	// Provider-specific information
	//
	// One of:
	//   * StaticProviderType
	ProviderInfo json.RawMessage `json:"providerInfo,omitempty"`
}

Request to create a worker

type WorkerErrorReport 

type WorkerErrorReport struct {

	// A longer description of what occured in the error.
	//
	// Max length: 10240
	Description string `json:"description"`

	// Any extra structured information about this error
	//
	// Additional properties allowed
	Extra json.RawMessage `json:"extra"`

	// A general machine-readable way to identify this sort of error.
	//
	// Syntax:     [-a-z0-9]+
	// Max length: 128
	Kind string `json:"kind"`

	// A human-readable version of `kind`.
	//
	// Max length: 128
	Title string `json:"title"`

	// Worker group to which this worker belongs
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	WorkerGroup string `json:"workerGroup"`

	// Worker ID
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	WorkerID string `json:"workerId"`
}

A report of an error from a worker. This will be recorded with kind `worker-error`.

The worker's `workerGroup` and `workerId` will be added to `extra`.

type WorkerFullDefinition 

type WorkerFullDefinition struct {

	// Date and time when this worker was created
	Created tcclient.Time `json:"created"`

	// Date and time when this worker will be deleted from the DB
	Expires tcclient.Time `json:"expires"`

	// The provider that had started the worker and responsible for managing it.
	// Can be different from the provider that's currently in the worker pool config.
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	ProviderID string `json:"providerId"`

	// A string specifying the state this worker is in so far as worker-manager knows.
	//
	// Possible values:
	//   * "requested"
	//   * "running"
	//   * "stopped"
	State string `json:"state"`

	// Worker group to which this worker belongs
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	WorkerGroup string `json:"workerGroup"`

	// Worker ID
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	WorkerID string `json:"workerId"`

	// The ID of this worker pool (of the form `providerId/workerType` for compatibility)
	//
	// Syntax:     ^[a-zA-Z0-9-_]{1,38}/[a-z]([-a-z0-9]{0,36}[a-z0-9])?$
	WorkerPoolID string `json:"workerPoolId"`
}

A complete worker definition.

type WorkerListInAGivenWorkerPool 

type WorkerListInAGivenWorkerPool struct {

	// Opaque `continuationToken` to be given as query-string option to get the
	// next set of workers in the worker-manager.
	// This property is only present if another request is necessary to fetch all
	// results. In practice the next request with a `continuationToken` may not
	// return additional results, but it can. Thus, you can only be sure to have
	// all the results if you've called `listWorkerPools` with `continuationToken`
	// until you get a result without a `continuationToken`.
	ContinuationToken string `json:"continuationToken,omitempty"`

	// List of all workers in a given worker pool
	Workers []WorkerFullDefinition `json:"workers"`
}

A list of workers in a given worker pool

type WorkerManager 

type WorkerManager tcclient.Client

func New 

func New(credentials *tcclient.Credentials, rootURL string) *WorkerManager

New returns a WorkerManager client, configured to run against production. Pass in nil credentials to create a client without authentication. The returned client is mutable, so returned settings can be altered. 

workerManager := tcworkermanager.New(
    nil,                                      // client without authentication
    "http://localhost:1234/my/taskcluster",   // taskcluster hosted at this root URL on local machine
)
err := workerManager.Ping(.....)              // for example, call the Ping(.....) API endpoint (described further down)...
if err != nil {
	// handle errors...
}

func NewFromEnv 

func NewFromEnv() *WorkerManager

NewFromEnv returns a *WorkerManager configured from environment variables.

The root URL is taken from TASKCLUSTER_PROXY_URL if set to a non-empty string, otherwise from TASKCLUSTER_ROOT_URL if set, otherwise the empty string.

The credentials are taken from environment variables: 

TASKCLUSTER_CLIENT_ID
TASKCLUSTER_ACCESS_TOKEN
TASKCLUSTER_CERTIFICATE

If TASKCLUSTER_CLIENT_ID is empty/unset, authentication will be disabled.

func (*WorkerManager) CreateWorker 

func (workerManager *WorkerManager) CreateWorker(workerPoolId, workerGroup, workerId string, payload *WorkerCreationRequest) (*WorkerFullDefinition, error)

Stability: *** EXPERIMENTAL ***

Create a new worker. The precise behavior of this method depends on the provider implementing the given worker pool. Some providers do not support creating workers at all, and will return a 400 error.

Required scopes: 

worker-manager:create-worker:<workerPoolId>/<workerGroup>/<workerId>

See #createWorker

func (*WorkerManager) CreateWorkerPool 

func (workerManager *WorkerManager) CreateWorkerPool(workerPoolId string, payload *WorkerPoolDefinition) (*WorkerPoolFullDefinition, error)

Stability: *** EXPERIMENTAL ***

Create a new worker pool. If the worker pool already exists, this will throw an error.

Required scopes: 

All of:
* worker-manager:manage-worker-pool:<workerPoolId>
* worker-manager:provider:<providerId>

See #createWorkerPool

func (*WorkerManager) DeleteWorkerPool 

func (workerManager *WorkerManager) DeleteWorkerPool(workerPoolId string) (*WorkerPoolFullDefinition, error)

Stability: *** EXPERIMENTAL ***

Mark a worker pool for deletion. This is the same as updating the pool to set its providerId to `"null-provider"`, but does not require scope `worker-manager:provider:null-provider`.

Required scopes: 

worker-manager:manage-worker-pool:<workerPoolId>

See #deleteWorkerPool

func (*WorkerManager) ListProviders 

func (workerManager *WorkerManager) ListProviders(continuationToken, limit string) (*ProviderList, error)

Retrieve a list of providers that are available for worker pools.

See #listProviders

func (*WorkerManager) ListWorkerPoolErrors 

func (workerManager *WorkerManager) ListWorkerPoolErrors(workerPoolId, continuationToken, limit string) (*WorkerPoolErrorList, error)

Stability: *** EXPERIMENTAL ***

Get the list of worker pool errors.

See #listWorkerPoolErrors

func (*WorkerManager) ListWorkerPools 

func (workerManager *WorkerManager) ListWorkerPools(continuationToken, limit string) (*WorkerPoolList, error)

Stability: *** EXPERIMENTAL ***

Get the list of all the existing worker pools.

See #listWorkerPools

func (*WorkerManager) ListWorkersForWorkerGroup 

func (workerManager *WorkerManager) ListWorkersForWorkerGroup(workerPoolId, workerGroup, continuationToken, limit string) (*WorkerListInAGivenWorkerPool, error)

Stability: *** EXPERIMENTAL ***

Get the list of all the existing workers in a given group in a given worker pool.

See #listWorkersForWorkerGroup

func (*WorkerManager) ListWorkersForWorkerPool 

func (workerManager *WorkerManager) ListWorkersForWorkerPool(workerPoolId, continuationToken, limit string) (*WorkerListInAGivenWorkerPool, error)

Stability: *** EXPERIMENTAL ***

Get the list of all the existing workers in a given worker pool.

See #listWorkersForWorkerPool

func (*WorkerManager) Ping 

func (workerManager *WorkerManager) Ping() error

Respond without doing anything. This endpoint is used to check that the service is up.

See #ping

func (*WorkerManager) RegisterWorker 

func (workerManager *WorkerManager) RegisterWorker(payload *RegisterWorkerRequest) (*RegisterWorkerResponse, error)

Stability: *** EXPERIMENTAL ***

Register a running worker. Workers call this method on worker start-up.

This call both marks the worker as running and returns the credentials the worker will require to perform its work. The worker must provide some proof of its identity, and that proof varies by provider type.

See #registerWorker

func (*WorkerManager) RemoveWorker 

func (workerManager *WorkerManager) RemoveWorker(workerPoolId, workerGroup, workerId string) error

Stability: *** EXPERIMENTAL ***

Remove an existing worker. The precise behavior of this method depends on the provider implementing the given worker. Some providers do not support removing workers at all, and will return a 400 error. Others may begin removing the worker, but it may remain available via the API (perhaps even in state RUNNING) afterward.

Required scopes: 

worker-manager:remove-worker:<workerPoolId>/<workerGroup>/<workerId>

See #removeWorker

func (*WorkerManager) ReportWorkerError 

func (workerManager *WorkerManager) ReportWorkerError(workerPoolId string, payload *WorkerErrorReport) (*WorkerPoolError, error)

Stability: *** EXPERIMENTAL ***

Report an error that occurred on a worker. This error will be included with the other errors in `listWorkerPoolErrors(workerPoolId)`.

Workers can use this endpoint to report startup or configuration errors that might be associated with the worker pool configuration and thus of interest to a worker-pool administrator.

NOTE: errors are publicly visible. Ensure that none of the content contains secrets or other sensitive information.

Required scopes: 

All of:
* assume:worker-pool:<workerPoolId>
* assume:worker-id:<workerGroup>/<workerId>

See #reportWorkerError

func (*WorkerManager) UpdateWorkerPool 

func (workerManager *WorkerManager) UpdateWorkerPool(workerPoolId string, payload *WorkerPoolDefinition1) (*WorkerPoolFullDefinition, error)

Stability: *** EXPERIMENTAL ***

Given an existing worker pool definition, this will modify it and return the new definition.

To delete a worker pool, set its `providerId` to `"null-provider"`. After any existing workers have exited, a cleanup job will remove the worker pool. During that time, the worker pool can be updated again, such as to set its `providerId` to a real provider.

Required scopes: 

All of:
* worker-manager:manage-worker-pool:<workerPoolId>
* worker-manager:provider:<providerId>

See #updateWorkerPool

func (*WorkerManager) Worker 

func (workerManager *WorkerManager) Worker(workerPoolId, workerGroup, workerId string) (*WorkerFullDefinition, error)

Stability: *** EXPERIMENTAL ***

Get a single worker.

See #worker

func (*WorkerManager) WorkerPool 

func (workerManager *WorkerManager) WorkerPool(workerPoolId string) (*WorkerPoolFullDefinition, error)

Stability: *** EXPERIMENTAL ***

Fetch an existing worker pool defition.

See #workerPool

type WorkerPoolDefinition 

type WorkerPoolDefinition struct {

	// Additional properties allowed
	Config json.RawMessage `json:"config"`

	// A description of this worker pool.
	//
	// Max length: 10240
	Description string `json:"description"`

	// If true, the owner should be emailed on provisioning errors
	EmailOnError bool `json:"emailOnError"`

	// An email address to notify when there are provisioning errors for this
	// worker pool.
	Owner string `json:"owner"`

	// The provider responsible for managing this worker pool.
	//
	// If this value is `"null-provider"`, then the worker pool is pending deletion
	// once all existing workers have terminated.
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	ProviderID string `json:"providerId"`
}

Fields that are defined by a user for a worker pool. Used to create worker-pool definitions. There is a larger set of fields for viewing since some parts are generated by the service.

type WorkerPoolDefinition1 

type WorkerPoolDefinition1 struct {

	// Additional properties allowed
	Config json.RawMessage `json:"config"`

	// Ignored on update
	Created tcclient.Time `json:"created,omitempty"`

	// A description of this worker pool.
	//
	// Max length: 10240
	Description string `json:"description"`

	// If true, the owner should be emailed on provisioning errors
	EmailOnError bool `json:"emailOnError"`

	// Ignored on update
	LastModified tcclient.Time `json:"lastModified,omitempty"`

	// An email address to notify when there are provisioning errors for this
	// worker pool.
	Owner string `json:"owner"`

	// The provider responsible for managing this worker pool.
	//
	// If this value is `"null-provider"`, then the worker pool is pending deletion
	// once all existing workers have terminated.
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	ProviderID string `json:"providerId"`

	// Syntax:     ^[a-zA-Z0-9-_]{1,38}/[a-z]([-a-z0-9]{0,36}[a-z0-9])?$
	WorkerPoolID string `json:"workerPoolId,omitempty"`
}

Fields that are defined by a user for a worker pool. Used to modify worker-pool definitions.

The `workerPoolId`, `created`, and `lastModified` fields are optional and allowed only to ease the common practice of getting a worker pool definition with `workerPool(..)`, modifying it, and writing it back with `updateWorkerPool(..). `workerPoolId` must be correct if supplied, and the values of `created` and `lastModified` are ignored.

type WorkerPoolError 

type WorkerPoolError struct {

	// A longer description of what occured in the error.
	//
	// Max length: 10240
	Description string `json:"description"`

	// An arbitary unique identifier for this error
	//
	// Syntax:     ^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
	ErrorID string `json:"errorId"`

	// Any extra structured information about this error
	//
	// Additional properties allowed
	Extra json.RawMessage `json:"extra"`

	// A general machine-readable way to identify this sort of error.
	//
	// Syntax:     [-a-z0-9]+
	// Max length: 128
	Kind string `json:"kind"`

	// Date and time when this error was reported
	Reported tcclient.Time `json:"reported"`

	// A human-readable version of `kind`.
	//
	// Max length: 128
	Title string `json:"title"`

	// The ID of this worker pool (of the form `providerId/workerType` for compatibility)
	//
	// Syntax:     ^[a-zA-Z0-9-_]{1,38}/[a-z]([-a-z0-9]{0,36}[a-z0-9])?$
	WorkerPoolID string `json:"workerPoolId"`
}

A complete worker pool error definition.

type WorkerPoolErrorList 

type WorkerPoolErrorList struct {

	// Opaque `continuationToken` to be given as query-string option to get the
	// next set of worker-types in the worker-manager.
	// This property is only present if another request is necessary to fetch all
	// results. In practice the next request with a `continuationToken` may not
	// return additional results, but it can. Thus, you can only be sure to have
	// all the results if you've called `listWorkerPools` with `continuationToken`
	// until you get a result without a `continuationToken`.
	ContinuationToken string `json:"continuationToken,omitempty"`

	// List of worker pool errors
	WorkerPoolErrors []WorkerPoolError `json:"workerPoolErrors"`
}

A list of worker pool errors

type WorkerPoolFullDefinition 

type WorkerPoolFullDefinition struct {

	// Additional properties allowed
	Config json.RawMessage `json:"config"`

	// Date and time when this worker pool was created
	Created tcclient.Time `json:"created"`

	// A description of this worker pool.
	//
	// Max length: 10240
	Description string `json:"description"`

	// If true, the owner should be emailed on provisioning errors
	EmailOnError bool `json:"emailOnError"`

	// Date and time when this worker pool was last updated
	LastModified tcclient.Time `json:"lastModified"`

	// An email address to notify when there are provisioning errors for this
	// worker pool.
	Owner string `json:"owner"`

	// The provider responsible for managing this worker pool.
	//
	// If this value is `"null-provider"`, then the worker pool is pending deletion
	// once all existing workers have terminated.
	//
	// Syntax:     ^([a-zA-Z0-9-_]*)$
	// Min length: 1
	// Max length: 38
	ProviderID string `json:"providerId"`

	// The ID of this worker pool (of the form `providerId/workerType` for compatibility)
	//
	// Syntax:     ^[a-zA-Z0-9-_]{1,38}/[a-z]([-a-z0-9]{0,36}[a-z0-9])?$
	WorkerPoolID string `json:"workerPoolId,omitempty"`
}

A complete worker pool definition.

type WorkerPoolList 

type WorkerPoolList struct {

	// Opaque `continuationToken` to be given as query-string option to get the
	// next set of worker-types in the worker-manager.
	// This property is only present if another request is necessary to fetch all
	// results. In practice the next request with a `continuationToken` may not
	// return additional results, but it can. Thus, you can only be sure to have
	// all the results if you've called `listWorkerPools` with `continuationToken`
	// until you get a result without a `continuationToken`.
	ContinuationToken string `json:"continuationToken,omitempty"`

	// List of all worker pools
	WorkerPools []WorkerPoolFullDefinition `json:"workerPools"`
}

A list of worker pools

Source Files

View all Source files

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.