Job Labeling

This section of the Apcera Platform documentation describes how to use job labeling, including:

Overview

Job labeling lets you add label metadata to jobs. A job label is a user-defined name string and optional value string. You can use APC to add, update, and delete labels from jobs, and to query for jobs with specific labels. And you can use policy to automate job labeling.

Use cases

Job labeling has many potential uses. Consider the following:

Job auditing or billing

You may want to assign an ID to a job for auditing or billing purposes. For example, you can label a job with a billing ID and query for all the jobs assigned to a given billing ID.

Job-project association

You may want to associate a job with a project identifier. For example, since multiple systems may be linked to jobs, you may want to be able to set multiple independent identifiers using a property name of your choosing. You can do this using job labels.

APC commands for job labeling

The following APC command options are avaiable for job labeling.

APC command Job label option Effect
apc job update -l, --label-set LBL[=VAL] Set label name and optional label value on the job. Label name must be unique. Providing a value for an existing label overwrites the existing value. Multiple labels can be added by invoking multiple times. For example: -l X=y -l W=z
apc job update -lu --label-unset LBL Label name to delete from job. Multiple labels can be deleted by invoking multiple times. For example: -lu X -lu W
apc job list -fl, --filter-by-label Query for jobs that match all the label requirements. For example: -fl lbl1, -fl lbl2=val1, --filter-by-label label three=3. Note that -fl lbl1 matches any value, including no value, as long as 1bl1 is present.
apc job show N/A View all labels associated with a job.

Policy-driven job labeling

You can use policy to set job labels on job creation or update. Apcera provides the claim type label with the claim value being a name-value pair in the form of name=[value], where the value portion is optional.

Usage

To use policy for job labeling, keep in mind the following:

  • The label claim type is available for resources in the job::/ realm only. You cannot use labels on resources other than jobs.
  • The label claim value is split into label name and label value using the first unescaped equals sign (=) as the separator.
  • If no equals sign (=) is present, the label value is set to an empty string ("").
  • Whitespace leading and trailing the equals sign (=) is trimmed unless the claim value is expressed as a raw string (using single quotes).
  • Policy will recreate labels deleted (apc job update --label-unset), so both policy and job update must be used to clear an existing label.
  • Policy-set job labels are only applied when a job is created or before a job is updated. Thus, a subsequent job label update using APC or the API supersedes any label values set by policy.

Examples

The following policy example adds a job label with the name ISRM-CTXT-ID and value 2345-1234 to any job created or updated in the job::/production/surveys namespace:

job::/production/surveys {
	{ label "ISRM-CTXT-ID=2345-1234" }
}

The following job label policy example associates two job labels with any job created or updated in the designated namespace. Note that the second label (ONLY_LBL) is an "empty label" with the value being an empty string.

job::/production/surveys {
	{ label "ISRM-CTXT-ID=2345-1234", ONLY_LBL }
}

In the following example the whitespace around the '=' is removed:

job::/production/orders { 
	{ label "ISRM-CTXT-ID = 2345-1234" }
}

The following job label policy example associates labels that have special characters and whitespace with the job named foo:

job::/production/orders::foo { 
	{ 
		label '[likeATmplt]=like->aClaim'
		label "MyKey\=Has=An Equals Sign In It"
		label ' Untrimmed ws in key  = and value(some value here). '
   }
}

You cannot remove a label that has been set by policy unless you first remove the policy. If you remove the label first, APC will do so, but the policy engine will add the label back.