Poolboy

Poolboy provides a structure to manage OpenShift resources by allowing users to request resources which are then satisfied by resource providers and from pre-provisioned resource pools. This allows for users to manage resources in a cluster for which they do not have direct access through Kubernetes role-based access controls.

Poolboy Operation

ResourceClaim Creation

User creates a ResourceClaim which contain a list of resource templates to defines desired resources.
The ResourceClaim is matched to a ResourceProvider.
The ResourceClaim’s resource templates are updated with defaults as defined by the ResourceProvider.
Each resource template in the ResourceClaim is checked for validity against the OpenAPIv3 schema in the ResourceProvider.
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.

ResourceClaim Update

User updates an existing ResourceClaim
Each resource template in the ResourceClaim is checked for validity against the OpenAPIv3 schema in the ResourceProvider.
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.
Updates are applied to the ResourceHandle.

ResourceHandle Creation or Update

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.
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.

Templating

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

Lifespan

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.

Use Case - Project Babylon Anarchy Operator

Poolboy was designed to manage custom resource types for the Anarchy operator framework. The Anarchy Operator orchestrates API calls, tracking the state of remote resources in custom resource kinds. As part of Project Babylon, Anarchy is configured to manage cloud resources and environments. Poolboy allows for these cloud environments to be pre-provisioned and then claimed by users.

In Anarchy a cloud environment is represented by the AnarchySubject custom resource kind.

Pre-Provisioned Environments

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.

User Management of Environments

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.

Installation

Poolboy Install

Install from helm template:

helm template poolboy helm/ | oc apply -f -

Build

OpenShift Build

Process OpenShift build template to create BuildConfig and ImageStream
```
oc process --local -f build-template.yaml | oc apply -n poolboy -f -
```

Build poolboy image

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

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 -

Credits

Poolboy logo is original art by Lara Ditkoff

paulbarfuss/poolboy