Skip to content
eventide-ossPublic

About

Kubernetes operator and CLI (vesperctl) for ephemeral preview environments, one per pull request.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Vesper: preview environments that set on time. One isolated namespace per pull request, deleted when its TTL ends.

CI Latest release License: Apache-2.0 Go version

Vesper gives each pull request its own preview environment on Kubernetes: a running copy of your application at that version, with its own URL, isolated from the others, and deleted automatically when its time to live (TTL) ends. It is an operator that runs in your cluster, and a CLI, vesperctl.

Quickstart · Documentation · Security model · Contributing

How it works

The life of a preview in four steps. 1, you ask for a preview: a PreviewEnvironment names an image, a port and a TTL; phase Pending. 2, Vesper runs it, isolated, in a namespace of its own with a Deployment, a Service, a quota and a default-deny NetworkPolicy; once the pods run, it is Ready with its URL. 3, its TTL runs out, 24 hours by default, from 1 minute to 7 days, and vesperctl extend buys time; phase Expired. 4, nothing is left: Vesper deletes the namespace and everything in it, and a finalizer makes sure the cleanup runs.

Vesper does not build images: your CI builds one per pull request, and a PreviewEnvironment points at it. The operator watches these objects and does the rest. The architecture goes through it step by step.

Quickstart

On a local kind cluster:

kind create cluster --name vesper
kubectl apply -f https://github.com/eventide-oss/vesper/releases/download/v0.1.0/install.yaml
kubectl -n vesper-system rollout status deploy/vesper-controller-manager

# install vesperctl from the release: see the quickstart, step 3
vesperctl create demo --image nginxinc/nginx-unprivileged:1.27-alpine --port 8080 --ttl 2h
vesperctl get demo      # phase, URL, expiry, conditions and events

The quickstart walks through it, from installing vesperctl to opening the preview in a browser, in about ten minutes. On a real server, with a domain and HTTPS: try Vesper on a server.

Why Vesper

Before a pull request is merged, people want to see the change running. A shared staging environment gets crowded, and running the branch on a laptop is not open to everyone. A preview per pull request solves both, as long as it is isolated and does not stay forever.

  • Isolated by default. Each preview gets a namespace with the restricted Pod Security profile, a ResourceQuota, a LimitRange and a default-deny NetworkPolicy. A namespace is a soft boundary, though: the security model says what Vesper protects against, and what it does not.
  • Gone on time. A TTL from 1 minute to 7 days; when it ends, the namespace and everything in it is deleted. No orphans.
  • Easy to follow. vesperctl list and vesperctl get show the phase, the URL, the expiry, the conditions and the events. Prometheus metrics included.
  • Verifiable. Releases ship checksums and build provenance attestations; the image runs as a non-root user and is pinned by digest.

Documentation

All the guides are listed in docs/, and published on the documentation site.

Where we're going

Today you create a preview yourself, and it runs one application. Two steps take Vesper to a preview of the whole pull request, opened and closed on its own.

v0.2 · From a pull request to a preview

A GitHub App receives the events of the pull request: the preview opens with it, follows each push, and closes with it. Vesper posts the URL on the pull request, like this:

Concept of a comment by the Vesper bot on a pull request: your preview is ready; preview pr-42, status Ready, a link to visit the preview, the image, and an expiry in 23 hours.

v0.3 · A whole stack per preview

Testing a change end to end needs more than one image. A preview will run several components side by side, a frontend, an API and a database seeded with test data, in the namespace of the preview, so the pull request is tested as it will run.

Concept of the comment for a multi-service preview: your preview stack is ready, 3 of 3 components. web is public with a link; api answers inside the namespace at http://api:8080; postgres at postgres:5432, seeded.

How it will work under the hood:

Concept of a multi-service preview. 1, the pull request sends a signed webhook to Vesper. 2, Vesper creates a namespace where an Ingress leads to web, web calls api, and api calls postgres, all inside a default-deny NetworkPolicy. 3, Vesper comments the URL and the status of each component on the pull request. 4, when the pull request closes or the TTL ends, the namespace and the whole stack are deleted.

The GitHub integration is available to try from v0.2.0-rc.2: Previews from pull requests sets it up, and vesper-demo shows it live. The rest of v0.2 is in its milestone. The multi-service previews are concepts, planned in the v0.3 milestone, whose design starts with #162: the shape of the API is not decided yet.

  • v0.2, GitHub integration. Previews from pull requests, private images, protected preview URLs.
  • v0.3, multi-service previews. Several components and a seeded database per preview.
  • Later, ideas rather than promises. Policies per team, other forges such as GitLab, previews that sleep when nobody uses them, the OpenSSF Best Practices badge and an application to the CNCF Sandbox.

Status

v0.1.0 is the first release. The API is v1alpha1 and may change before v1.0. What v0.1 covers, and how it was checked, is in the acceptance of v0.1.

Contributing

Contributions are welcome. Read CONTRIBUTING.md first, and pick one of the good first issues. The project follows a Code of Conduct and a simple governance. Every change starts from an issue and ends in a small pull request that follows the template. AI agents also read AGENTS.md.

If Vesper is useful to you, a star helps others find it.

License

Apache-2.0. The name and the logo of Vesper are described in the brand guide.

About

Kubernetes operator and CLI (vesperctl) for ephemeral preview environments, one per pull request.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages