Skip to content

CoderWorkspacePool

API identity

  • Group/version: coder.com/v1alpha1
  • Kind: CoderWorkspacePool
  • Resource: coderworkspacepools
  • Scope: namespaced

Spec

Field Type Description
controlPlaneRef CoderControlPlaneReference ControlPlaneRef names the CoderControlPlane in the same namespace. The controller calls Coder with that control plane's operator token.
strategy string Strategy is how the pool keeps its workspaces. Managed is the only strategy: the operator creates the workspaces itself.
ownerUserID string OwnerUserID is the UUID of the Coder user who owns every workspace of the pool. The control plane's admin must allow this owner and the template. Every start build gives the owner's API token to the template's Terraform, so use a dedicated low-privilege user. Write the UUID in lower case with hyphens, as in the control plane's owners list.
template string Template is the Coder template as <organization>.<template>, the same format as aggregated CoderTemplate names. Each name has at most 32 characters and is not one of Coder's reserved names new or create.
version CoderWorkspacePoolVersion Version selects the template version of new members. A change replaces the unclaimed members, new before old.
presetName string PresetName is the name of a preset of the selected version. The start builds use its parameter values.
parameters CoderWorkspacePoolParameter array Parameters are rich parameter values for the start builds.
replicas integer Replicas is the number of unclaimed ready workspaces to keep. Waiting claims get a workspace built on demand on top of this number. The scale subresource writes this field, so kubectl scale, HPA, and KEDA can resize the pool within the same bounds.
maxInFlight integer MaxInFlight is the number of members of this pool that build at the same time.
readyTimeoutSeconds integer ReadyTimeoutSeconds bounds the time from a member's creation until its workspace is ready. A member that is not ready in time fails, and the controller replaces it.
maxUnclaimedAgeSeconds integer MaxUnclaimedAgeSeconds replaces an unclaimed workspace that has been ready this long, new before old: the old workspace stays claimable until its replacement is ready. Leave it out to keep unclaimed workspaces until a claim, a scale-down, or an input change.
claims CoderWorkspacePoolClaims Claims configures how the pool hands out workspaces.

Status

Field Type Description
observedGeneration integer ObservedGeneration is the generation the controller last processed. Every scale change bumps metadata.generation.
replicas integer Replicas is the number of unclaimed members that count toward spec.replicas: current and outdated, not failed, not used, not being deleted. The scale subresource reads this field.
readyReplicas integer ReadyReplicas is the number of those members whose workspace is ready.
updatedReplicas integer UpdatedReplicas is the number of those members that use the resolved inputs.
boundReplicas integer BoundReplicas is the number of members that claims hold.
usedReplicas integer UsedReplicas is the number of members that someone may have used without a claim. They no longer count toward the pool, and the pool never deletes them.
pendingClaims integer PendingClaims is the number of claims that wait for a workspace.
selector string Selector is the label selector of the scale subresource, in string form: the label coder.com/workspace-pool-uid equal to the pool's UID. It matches no pods unless a template sets that label, so autoscalers must use External or Object metrics with target type AverageValue.
resolved CoderWorkspacePoolResolved Resolved holds the inputs that the controller resolved in Coder.
consecutiveFailures integer ConsecutiveFailures is the number of member failures in a row: the length of RunFailures. A ready member and a change of status.resolved (template, version, preset, parameters, owner, or readyTimeoutSeconds) reset it. A change of replicas or maxInFlight does not.
lastFailure CoderWorkspacePoolFailure LastFailure is the newest member failure.
failureRunStart Time FailureRunStart is the start of the current run of failures: the latest of the last change of status.resolved and the newest ready time of a member. Failures at or before it do not count.
runFailures CoderWorkspacePoolFailure array RunFailures are the member failures of the current run, oldest first, at most 5. The controller stores each one before it deletes the failed member, so it counts every failure once.
reason string Reason is the current wait reason.
message string Message explains Reason. It never holds Coder error details, build logs, parameter values, or tokens.
conditions Condition array Conditions are Ready, Reconciling, and Stalled.

Referenced types

CoderControlPlaneReference

CoderControlPlaneReference names a CoderControlPlane in the same namespace.

Field Type Description
name string Name is the CoderControlPlane name.

CoderWorkspacePoolClaims

CoderWorkspacePoolClaims configures how the pool hands out workspaces.

Field Type Description
mode string Mode is how a claim gets its workspace. Reserve binds a ready workspace to the claim, and the workspace stays with the pool owner. Share also gives the claim's spec.share.user the Coder use role on the workspace (open apps, SSH, start, stop; never delete), where the organization's sharing setting and the owner's shareGroupIDs allow it.
idleTimeoutSeconds integer IdleTimeoutSeconds deletes a claimed workspace, with its data, once both the bind and the workspace's last use in Coder (last_used_at) are this long ago. The claim then becomes Lost with reason IdleTimeout. Leave it out to keep claimed workspaces until their claims are deleted. Unclaimed workspaces are idle by design and never count.

CoderWorkspacePoolFailure

CoderWorkspacePoolFailure is the newest member failure of a pool.

Field Type Description
member string Member is the name of the failed CoderWorkspacePoolMember.
reason string Reason is the member's failure reason.
message string Message explains Reason. It never holds Coder error details, build logs, parameter values, or tokens.
time Time Time is when the controller recorded the failure.

CoderWorkspacePoolParameter

CoderWorkspacePoolParameter is one rich parameter value for the start builds. Values are stored in plain text, so never put secrets here.

Field Type Description
name string Name is the parameter name.
value string Value is the parameter value.

CoderWorkspacePoolResolved

CoderWorkspacePoolResolved holds the inputs that the controller resolved in Coder. New members pin these values.

Field Type Description
organizationID string OrganizationID is the UUID of the template's organization.
templateID string TemplateID is the UUID of the template.
templateVersionID string TemplateVersionID is the UUID of the selected version.
templateVersionName string TemplateVersionName is the name of the selected version.
presetID string PresetID is the UUID of the preset named by spec.presetName.
ownerID string OwnerID is the UUID of the owner the controller checked.
parametersHash string ParametersHash identifies spec.parameters, so the controller can tell current members from outdated ones without storing values twice.
readyTimeoutSeconds integer ReadyTimeoutSeconds is spec.readyTimeoutSeconds. A change of any of these values starts a new run of failures, because it can fix one.
resolvedTime Time ResolvedTime is when the controller last changed these values.

CoderWorkspacePoolVersion

CoderWorkspacePoolVersion selects the template version of new members. Set exactly one field. +kubebuilder:validation:XValidation:rule="(has(self.name) ? 1 : 0) + (has(self.id) ? 1 : 0) + (has(self.active) ? 1 : 0) == 1",message="set exactly one of name, id, or active" +kubebuilder:validation:XValidation:rule="!has(self.active) || self.active",message="active must be true when set"

Field Type Description
name string Name is the name of a version of the template. It follows Coder's template version name rules.
id string ID is the UUID of a version of the template.
active boolean Active follows the template's active version. After a promotion, the controller replaces unclaimed members, new before old.

Source

  • Go type: api/v1alpha1/coderworkspacepool_types.go
  • Generated CRD: config/crd/bases/coder.com_coderworkspacepools.yaml