Skip to content
Vesper
These docs follow the main branch. The latest release is v0.1.0.

API Reference

Packages

Section titled “Packages”

vesper.eventide.dev/v1alpha1

Section titled “vesper.eventide.dev/v1alpha1”

Package v1alpha1 contains API Schema definitions for the vesper v1alpha1 API group.

Resource Types

Section titled “Resource Types”

EnvVar

Section titled “EnvVar”

EnvVar is an environment variable set in the preview’s container.

Appears in:

Field Description Default Validation
name string name of the variable, for example LOG_LEVEL. MaxLength: 256
MinLength: 1
Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
Required: {}
value string value of the variable. Empty by default. MaxLength: 4096
Optional: {}

ForkPolicy

Section titled “ForkPolicy”

Underlying type: string

ForkPolicy chooses whether pull requests from forks get a preview.

Validation:

  • Enum: [Deny RequireLabel]

Appears in:

Field Description
Deny ForkDeny gives no preview to pull requests from forks.
RequireLabel ForkRequireLabel gives one once someone with write access to the
repository adds the label preview.

Phase

Section titled “Phase”

Underlying type: string

Phase summarizes the state of a preview in one word. The conditions hold the details.

Validation:

  • Enum: [Pending Ready Failed Expired]

Appears in:

Field Description
Pending PhasePending means the preview is being set up.
Ready PhaseReady means the application of the preview is running.
Failed PhaseFailed means a problem blocks the preview. The conditions say which.
Expired PhaseExpired means the TTL has passed and the preview is being deleted.

PreviewDefaults

Section titled “PreviewDefaults”

PreviewDefaults are the settings of the previews of a source, with the bounds of a PreviewEnvironment.

Appears in:

Field Description Default Validation
port integer port is the port the application listens on, inside its container. 8080 Maximum: 65535
Minimum: 1
Optional: {}
replicas integer replicas is the number of pods of each preview. 1 Maximum: 5
Minimum: 1
Optional: {}
ttl Duration ttl is how long a preview lives after the last commit of its pull
request, from 1m to 168h.		 24h Type: string
Optional: {}
env EnvVar array env are environment variables given to each preview. Their values are
readable by anyone who can read this source: no secrets.		 MaxItems: 64
Optional: {}

PreviewEnvironment

Section titled “PreviewEnvironment”

PreviewEnvironment is a temporary environment that runs one container image, for example the build of a pull request, until its TTL expires.

Field Description Default Validation
apiVersion string vesper.eventide.dev/v1alpha1
kind string PreviewEnvironment
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec PreviewEnvironmentSpec spec defines the desired state of PreviewEnvironment Required: {}
status PreviewEnvironmentStatus status defines the observed state of PreviewEnvironment Optional: {}

PreviewEnvironmentSpec

Section titled “PreviewEnvironmentSpec”

PreviewEnvironmentSpec is the preview a user asks for: which image to run, how, and for how long.

Appears in:

Field Description Default Validation
image string image is the container image to run, pinned with a tag other than
“latest” or with a digest, for example ghcr.io/acme/app:pr-42 or
ghcr.io/acme/app@sha256:<64 hex characters>. A preview must show exactly
the code it was created for, and a moving tag would not.		 MaxLength: 512
MinLength: 1
Required: {}
port integer port is the port the container listens on. Defaults to 8080. 8080 Maximum: 65535
Minimum: 1
Optional: {}
replicas integer replicas is the number of pods to run. Defaults to 1, at most 5. 1 Maximum: 5
Minimum: 1
Optional: {}
ttl Duration ttl is how long the preview lives after its creation, as a duration such
as “24h” or “90m”, between 1m and 168h (7 days). Defaults to 24h. When it
has passed, the preview is deleted. Raise it to extend the preview: the
total lifetime stays within 168h.		 24h Type: string
Optional: {}
env EnvVar array env sets environment variables in the container. Names are unique.
Values are stored in plain text in the object: do not put secrets here.		 MaxItems: 64
Optional: {}

PreviewEnvironmentStatus

Section titled “PreviewEnvironmentStatus”

PreviewEnvironmentStatus is the state of a preview as observed by the operator. Only the operator writes it, through the status subresource.

Appears in:

Field Description Default Validation
phase Phase phase summarizes the state of the preview: Pending, Ready, Failed or
Expired.		 Enum: [Pending Ready Failed Expired]
Optional: {}
namespace string namespace is the namespace the operator created for the preview, where
its application runs, for example vesper-team-a-pr-42-3f9c2a1b. It is
set once the namespace exists; look there for the pods, logs and events
of the preview.		 MaxLength: 63
Optional: {}
url string url is the address where the preview can be reached. MaxLength: 2048
Optional: {}
internalURL string internalURL is the address of the preview inside the cluster: its
Service, for example http://app.vesper-team-a-pr-42-3f9c2a1b.svc.cluster.local.
It is not reachable from outside the cluster.		 MaxLength: 2048
Optional: {}
expiresAt Time expiresAt is when the preview will be deleted: its creation time plus
its ttl.		 Optional: {}
observedGeneration integer observedGeneration is the metadata.generation of the spec this status
reflects. When it is lower than metadata.generation, the operator has
not processed the latest change yet.		 Minimum: 0
Optional: {}
conditions Condition array conditions describe the state of the preview in detail: “Ready” sums
it up, “Available” says whether its application runs, and “Expired”
whether its ttl has passed. Each condition has a status (True, False or
Unknown), a machine-readable reason and a human-readable message.		 Optional: {}

PreviewSource

Section titled “PreviewSource”

PreviewSource allows a GitHub repository to have previews of its pull requests. It is cluster-scoped: an administrator of the cluster creates it, not the teams, since it lets a repository run code on the cluster.

Field Description Default Validation
apiVersion string vesper.eventide.dev/v1alpha1
kind string PreviewSource
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec PreviewSourceSpec spec is the repository and the settings of its previews Required: {}

PreviewSourceSpec

Section titled “PreviewSourceSpec”

PreviewSourceSpec allows a GitHub repository to have previews of its pull requests, and says how to build them (ADR-0007).

Appears in:

Field Description Default Validation
repository string repository is the GitHub repository, as /, for example
acme/app. GitHub compares it without case.		 MaxLength: 140
Pattern: ^[A-Za-z0-9](https://github.com/eventide-oss/vesper/blob/main/docs/[A-Za-z0-9-]\{0,37\}[A-Za-z0-9])?/[A-Za-z0-9._-]\{1,100\}$
Required: {}
image string image is the image of a pull request, as a template: {{number}} is
replaced by the number of the pull request, and {{sha}} by its head
commit, for example ghcr.io/acme/app:pr-{{number}}-{{sha}}. It must
contain {{sha}}, so that each commit has an image of its own, and give
a valid image reference pinned with a tag other than latest.		 MaxLength: 512
MinLength: 1
Required: {}
buildWorkflow string buildWorkflow is the file name of the GitHub Actions workflow that
builds the image, for example preview.yml: a preview switches to the
image of a commit once a run of this workflow succeeds on it. Empty
when the image is pushed before the pull request event.		 MaxLength: 100
Pattern: ^[A-Za-z0-9._-]+[.]ya?ml$
Optional: {}
namespace string namespace is where the PreviewEnvironment objects of this source are
created. Each of them still runs in a namespace of its own.		 MaxLength: 63
Pattern: ^[a-z0-9](https://github.com/eventide-oss/vesper/blob/main/docs/[-a-z0-9]*[a-z0-9])?$
Required: {}
trigger Trigger trigger chooses which pull requests get a preview: All, every pull
request, and the label no-preview stops one; Label, only the pull
requests with the label preview.		 All Enum: [All Label]
Optional: {}
forkPullRequests ForkPolicy forkPullRequests chooses whether pull requests from forks get a
preview: Deny, never; RequireLabel, once someone with write access to
the repository adds the label preview. Their code is not reviewed.		 Deny Enum: [Deny RequireLabel]
Optional: {}
defaults PreviewDefaults defaults are the settings of the previews of this source. { } Optional: {}

Trigger

Section titled “Trigger”

Underlying type: string

Trigger chooses which pull requests of a repository get a preview.

Validation:

  • Enum: [All Label]

Appears in:

Field Description
All TriggerAll gives every pull request a preview; the label no-preview
stops one.
Label TriggerLabel gives a preview only to the pull requests with the label
preview.