1. User creates a ResourceClaim which contain a list of resource templates to defines desired resources.

2. The ResourceClaim is matched to a ResourceProvider.

3. The ResourceClaim’s resource templates are updated with defaults as defined by the ResourceProvider.

4. Each resource template in the ResourceClaim is checked for validity against the OpenAPIv3 schema in the ResourceProvider.

5. A ResourceHandle from a ResourcePool is matched to the ResourceClaim or a new ResourceHandle is created to satisfy the claim:

   1. To match an existing ResourceHandle each resource template in the ResourceClaim must match the ResourceHandle, excepting any fields specified in the ResourceProvider’s spec.matchIgnore.

   2. If created automatically, the ResourceHandle resource templates will be copied from the ResourceClaim.

1. User updates an existing ResourceClaim

2. Each resource template in the ResourceClaim is checked for validity against the OpenAPIv3 schema in the ResourceProvider.

3. A JSON Patch for each resource template in the ResourceHandle is generated and then the JSON Patch is filtered according to each ResourceProvider’s spec.updateFilters.

4. Updates are applied to the ResourceHandle.

1. For each resource template in the ResourceHandle a resource definition is generated.

   1. ResourceProvider spec.override is applied to each resource template.

   2. The metadata.name is determined for each templated resource to match the random suffix appended to ResourceHandle.

2. Create or update the resource

   1. If the resource does not exist, it is created.

   2. If the resource exists then it is updated.

   3. The state of the resource is copied into the ResourceClaim status if a ResourceClaim is bound to the ResourceHandle.

Templates are supported for ResourceProviders to supply defaults for ResourceClaims and for overrides for resources. Templates are enable for a ResourceProvider by specifying spec.template.enable on the ResourceProvider. Templates use Jinja2.

For ResourceClaim defaults templates may reference:

• resource_claim - ResourceClaim object

• resource_index - Resource index in the ResourceClaim spec.resources

• resource_provider - ResourceProvider object

For resource overrides templates may reference:

• resource_claim - ResourceClaim object if a ResourceClaim is bound

• resource_handle - ResourceHandle object

• resource_index - Resource index in the ResourceHandle spec.resources

• resource_provider - ResourceProvider object

• resource_template - Resource template from ResourceHandle

• requester_identity - OpenShift identity of requester determined from ResourceClaim namespace’s openshift.io/requester annotation

• requester_user - OpenShift user of requester determined from ResourceClaim namespace’s openshift.io/requester annotation

Normally Poolboy creates resources from ResourcePools as soon as the ResourceHandle is created. If the resource needs to reference resource_claim then the ResourceProvider may specify spec.resourceRequiresClaim to delay resource creation until the ResourceHandle is bound by a ResourceClaim.

Additionally templates may make use of variables timestamp and timedelta for date and time calculations. Examples:

• timestamp("2021-05-01T12:30:00Z") - Parsed timestamp

• timestamp("2021-05-01T12:30:00Z").add("3h") - Interval from parsed timestamp

• timestamp.utcnow - Current UTC timestamp in %Y-%m-%dT%H:%M:%SZ format

• timestamp.utcnow.add("1d") - UTC timestamp for this time tomorrow

• timestamp.utcnow.datetime - Python datetime object for UTC now

• timedelta("10m") - Representation of time delta for ten minutes.

• timedelta("10m").timedelta - Python datetime timedelta

By default no lifespan policy is applied to Poolboy resources.

Lifespan is configured in ResourceHandles by specifying:

• default - Default lifespan to apply to ResourceHandle when it is claimed.

• maximum - Maximum lifespan which may be requested in the ResourceClaim calculated from the ResourceClaim the creation timestamp.

• relativeMaximum - Maximum lifespan which can be requested in the ResourceClaim relative to the present datetime.

If both maximum and relativeMaximum are specified then the effective maximum is whichever is earlier. The calculated lifespan end set in the ResourceHandle lifespan.

The ResourceClaim can specify a lifespan end which will propagate to the ResourceHandle so long as it is within the maximum limits.

ResourcePools can specify lifespan configuration for resource handles they create. In addition to default, maximum, and relativeMaximum the ResourcePool can specify unclaimed to specify the lifespan of unclaimed ResourceHandles in the pool.

ResourceHandles created dynamically for ResourceClaims get their lifespan configuration from the ResourceProviders. If multiple ResourceProviders are used for a ResourceClaim then the minimum of each of the lifespan configuration options is applied to the ResourceHandle.

ResourcePools allow AnarychSubjects to be pre-created. The scale of a ResourcePool can be adjusted to add or reduce capacity based on expected demand. ResourceProvider validation and overrides allow for environments to be created on demand while retaining control on what environments can be requested.

Because the resource status is monitored and synced to the ResourceClaim status, users are able to track the state of their provisioned environments.

Each AnarchySubject has a spec.desiredState. The ResourceProvider spec.updateFilters allow this field to be updated while the spec.validation OpenAPIv3 check enforces that it can only be set to explicitly permitted values.

Install from helm template:

1. Process OpenShift build template to create BuildConfig and ImageStream

   oc process --local -f build-template.yaml | oc apply -n poolboy -f -

2. Build poolboy image

   oc start-build poolboy -n poolboy --from-dir=. --follow

3. Deploy Poolboy from build image

   helm template poolboy helm/ \
   --set=image.tagOverride=- \
   --set=image.repository=$(oc get imagestream poolboy -o jsonpath='{.status.tags[?(@.tag=="latest")].items[0].dockerImageReference}') \
   | oc apply -f -