JobTemplate¶

A reusable job definition shipped by a provider package.

Schema: jobtemplate.json. Explanations and examples: configuration model.

Field	Type	Required	Description
`apiVersion`	`tapyr/v1alpha1`	yes	Version of the configuration format.
`kind`	`JobTemplate`	yes	Kind of the document.
`metadata`	ObjectMeta	yes	Name and description of the document.
`spec`	JobTemplateSpec	yes	Specification of the document.

ObjectMeta¶

ObjectMeta identifies a document.

Field	Type	Required	Description
`description`	string		Description is free text for humans.
`name`	Name	yes	Name of the document, unique per kind.

JobTemplateSpec¶

JobTemplateSpec is the specification of a JobTemplate.

Field	Type	Required	Description
`defaultInterval`	Duration	yes	`defaultInterval` is the desired interval of jobs using the template.
`defaultPriority`	Priority		`defaultPriority` of jobs using the template.
`estimate`	Estimate		Estimate gives hints to the planner before run history exists.
`extract`	Extract		Extract maps responses to samples and inventory items.
`forEach`	ForEach		`forEach` fans the job out over the inventory items of a parent.
`pagination`	Pagination		Pagination overrides the provider default.
`provider`	Name	yes	Provider the template belongs to.
`request`	Request	yes	Request to send.
`role`	JobRole		Role of the job: inventory items, metrics, or both.

Name¶

Type: string. Pattern ^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$.

Duration¶

Type: string. Pattern ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$. Examples 30s, 5m, 1h30m.

Priority¶

Type: string. One of critical, high, normal, low.

Estimate¶

Estimate gives hints to the planner.

Field	Type	Required	Description
`pagesPerRun`	integer		`pagesPerRun` is the expected number of pages per run. Minimum 1.

Extract¶

Extract maps responses to samples and inventory items.

Field	Type	Description
`filter`	Expr	Filter is a CEL expression on item; false skips the item.
`info`	list of InfoMetric	Info metrics (value 1, descriptive labels) produced per item.
`inventory`	Inventory	Inventory items produced per item (role inventory or both).
`items`	Expr	Items is a CEL expression returning the list of items of a page. Default: response.body when it is a list.
`metrics`	list of Metric	Metrics produced per item.
`partial`	boolean	Partial emits the samples of a run even when a later page fails.
`post`	list of Metric	Post metrics computed once per run over all pages (responses).

ForEach¶

ForEach fans a job out over the inventory items of a parent job.

Field	Type	Description
`filter`	Expr	Filter is a CEL expression on parent selecting a subset of items.
`job`	Name	Job is the parent Job (same account), for inline jobs.
`maxInstances`	integer	`maxInstances` caps the fan-out, against runaway discovery. Default `10000`. Minimum 1.
`template`	Name	Template is the parent JobTemplate, instantiated implicitly for the account when no job references it.
`vars`	map of string to Expr	Vars maps request variables to CEL expressions on parent. Keys match `^[A-Za-z_][A-Za-z0-9_]*$`.

Pagination¶

Pagination configures how successive pages are requested.

Field	Type	Required	Description
`cursor`	CursorPagination		Cursor pagination (type cursor).
`expression`	ExpressionPagination		Expression pagination computed by CEL (type expression).
`linkHeader`	LinkHeaderPagination		`linkHeader` pagination following RFC 8288 Link headers (type link_header).
`maxPages`	integer		`maxPages` is a hard safety cap on pages per run. Default `100`. Minimum 1.
`offset`	OffsetPagination		Offset pagination (type offset).
`page`	PagePagination		Page pagination (type page).
`type`	string	yes	Type of pagination. One of `none`, `offset`, `page`, `link_header`, `cursor`, `expression`.

When type is offset: offset is required.
When type is page: page is required.
When type is cursor: cursor is required.
When type is expression: expression is required.

Request¶

Request describes the HTTP request of a job.

Field	Type	Required	Description
`body`	map of string to Value		Body is a JSON object for POST queries; values are literals, secrets or CEL expressions.
`headers`	map of string to string		Headers merged over the provider defaults (the job wins).
`idempotent`	boolean		Idempotent allows retrying POST requests.
`method`	string		Method of the request. POST is allowed only for read-only queries. Default `GET`. One of `GET`, `HEAD`, `POST`.
`path`	string	yes	Path relative to the base URL, with {var} placeholders resolved from discovery variables, target params and account params. Pattern `^/`.
`query`	map of string to Value		Query parameters; values are literals, secrets or CEL expressions.
`readOnly`	boolean		`readOnly` must be true for POST requests: Tapyr never writes to providers.
`timeout`	Duration		Timeout of a single request. Defaults to the provider default.

JobRole¶

Type: string. Default metrics. One of inventory, metrics, both.

Expr¶

CEL expression.

Type: string. Minimum length 1.

InfoMetric¶

InfoMetric produces an _info metric: value 1 and descriptive labels.

Field	Type	Required	Description
`help`	string		Help text of the metric.
`labels`	map of string to Expr	yes	Labels maps label names to CEL expressions returning strings. Keys match `^[a-zA-Z_][a-zA-Z0-9_]*$`.
`name`	string	yes	Name of the metric, ending with _info. Pattern `^[a-zA-Z_:][a-zA-Z0-9_:]*_info$`.
`skipIf`	Expr		`skipIf` is a CEL expression; true skips the sample.

Inventory¶

Inventory produces inventory items for child jobs.

Field	Type	Required	Description
`fields`	map of string to Expr		Fields maps field names to CEL expressions, available as parent.<field>. Keys match `^[A-Za-z_][A-Za-z0-9_]*$`.
`key`	Expr	yes	Key is a CEL expression returning the unique key of an item.
`ttl`	Duration		`ttl` of cached items. Default: 3x the job's effective interval.

Metric¶

Metric maps items to samples of one metric.

Field	Type	Required	Description
`accumulate`	boolean		Accumulate sums successive window values into a persisted counter (type counter only).
`help`	string		Help text of the metric.
`labels`	map of string to Expr		Labels maps label names to CEL expressions returning strings. Keys match `^[a-zA-Z_][a-zA-Z0-9_]*$`.
`name`	string	yes	Name of the metric (Prometheus naming rules). Pattern `^[a-zA-Z_:][a-zA-Z0-9_:]*$`.
`skipIf`	Expr		`skipIf` is a CEL expression; true skips the sample.
`timestamp`	Expr		Timestamp is a CEL expression returning the source timestamp.
`type`	string		Type of the metric. Default `gauge`. One of `gauge`, `counter`.
`unit`	string		Unit of the metric, preferably a Prometheus base unit.
`value`	Expr	yes	Value is a CEL expression returning a number or a bool.
`windowField`	Expr		`windowField` is a CEL expression identifying the window of a value, used by accumulate to avoid counting a window twice.

CursorPagination¶

CursorPagination passes a cursor extracted from each response.

Field	Type	Required	Description
`cursor`	Expr	yes	Cursor is a CEL expression extracting the next cursor; empty or null stops.
`header`	string		Header carrying the cursor, instead of a query parameter.
`pageSize`	integer		`pageSize` is the number of items per page. Minimum 1.
`pageSizeParam`	string		`pageSizeParam` is the query parameter carrying the page size.
`param`	string		Param is the query parameter carrying the cursor.

ExpressionPagination¶

ExpressionPagination computes the next request with CEL.

Field	Type	Required	Description
`next`	Expr	yes	Next is a CEL expression returning {query: {...}} for the next page, or null.

LinkHeaderPagination¶

LinkHeaderPagination follows RFC 8288 Link headers.

Field	Type	Description
`pageSize`	integer	`pageSize` is the number of items per page. Minimum 1.
`pageSizeParam`	string	`pageSizeParam` is the query parameter carrying the page size.
`rel`	string	Rel is the link relation of the next page. Default `next`.

OffsetPagination¶

OffsetPagination requests pages by item offset.

Field	Type	Required	Description
`limitParam`	string	yes	`limitParam` is the query parameter carrying the page size. Minimum length 1.
`offsetParam`	string	yes	`offsetParam` is the query parameter carrying the offset. Minimum length 1.
`pageSize`	integer	yes	`pageSize` is the number of items per page. Minimum 1.
`start`	integer		Start is the first offset. Default `0`. Minimum 0.
`stop`	Expr		Stop is a CEL expression; pagination stops when it returns true.
`total`	Expr		Total is a CEL expression returning the total number of items.

PagePagination¶

PagePagination requests pages by page number.

Field	Type	Required	Description
`pageParam`	string	yes	`pageParam` is the query parameter carrying the page number. Minimum length 1.
`pageSize`	integer		`pageSize` is the number of items per page. Minimum 1.
`sizeParam`	string		`sizeParam` is the query parameter carrying the page size.
`start`	integer		Start is the first page number. Default `1`. Minimum 0.
`stop`	Expr		Stop is a CEL expression; pagination stops when it returns true.
`total`	Expr		Total is a CEL expression returning the total number of items.

Value¶

A literal string, {secret: name} or {expr: cel}.

Either a string, or an object:

Field	Type	Required	Description
`expr`	string		CEL expression evaluated at runtime. Minimum length 1.
`secret`	string		Name of a secret declared by the provider and supplied by the account. Pattern `^[A-Za-z_][A-Za-z0-9_]*$`.

Exactly one field is set.