What is Envy?
Envy creates temporary compositions of microservice applications on Kubernetes with Istio, Cilium, or Linkerd. It deploys the services you change and reuses the rest from an approved running application. HTTP compositions receive a preview URL; endpoint-free Jobs report execution lifecycle without an ingress route.
Each preview gets a URL. The optional GitHub App creates previews for labelled PRs, updates them from successful builds of the current head commit, and cleans them up when the label is removed, the PR closes, or the TTL expires. Developers, CI workflows, and coding agents can create previews, wait for readiness, fetch log snapshots, and request cleanup through the envy CLI, REST API, or MCP server.
Three concepts
Section titled “Three concepts”| Concept | Meaning |
|---|---|
| Baseline | An approved deployed application with registered service addresses and a readiness check. It can represent main, a release, or another reference deployment. |
| Override | A replacement container image for an approved service. Envy deploys it in a temporary namespace. |
| Composition | A temporary selection of baseline bindings and zero to three overrides, with an expiry time. HTTP selections also receive a URL. |
How a request reaches your change
Section titled “How a request reaches your change”For a change to service-b, the preview uses the existing gateway and service-a, then routes to your replacement service-b:
Both URLs reuse gateway and service-a. The selected mesh selects service-b v2 only when the request carries the matching composition ID. Both service-b versions connect to the same shared data.
Scroll sideways to follow wider branches, or read the connections below.
Read the connections
- Baseline URL → gateway · v1: baseline request.
- Preview URL → gateway · v1: preview request.
- gateway · v1 → service-a · v1: forward baggage.
- service-a · v1 → service-b · v1: no matching context.
- service-a · v1 → service-b · v2: composition=cmp-123.
- service-b · v1 → Database & cache: read / write.
- service-b · v2 → Database & cache: read / write.
The preview ingress sets baggage: composition=<id>. Applications must forward that header on downstream HTTP calls. The selected mesh uses it to select the matching override; calls without matching composition context use the baseline.
Existing OpenTelemetry instrumentation can provide this propagation when configured for W3C Baggage on both incoming handlers and outgoing clients. See the routing contract for an example.
What stays shared
Section titled “What stays shared”Unchanged services, databases, caches, and external dependencies remain shared. Writes from a preview can change baseline data. Envy provides request routing and separate override workloads; it does not create an independent copy of application state.
This model suits integration testing against an existing reference application. Tests that require independent databases or destructive migrations need separate data arrangements. Optional Google Pub/Sub isolation provides filtered preview subscriptions when applications and baseline subscriptions implement its contract; other messaging systems remain shared. Read Sharing & Isolation before onboarding an application.
Preview lifecycle
Section titled “Preview lifecycle”- Create a composition with approved images and a TTL (8 hours by default).
- For HTTP components, wait until workload readiness, routing, and the declared ingress check succeed. For endpoint-free Jobs, wait for the reported execution lifecycle.
- Run your own functional tests against the preview URL or inspect the Job outcome. Readiness confirms the configured check, not every application behavior.
- Update images in place or request teardown. The reconciler also cleans up expired compositions.
An HTTP URL is allocated when creation is accepted. Time to readiness or completion depends on image pulls, workload startup, routing where required, and verification.
Start here
Section titled “Start here”- Local quickstart: check the prerequisites and install locally with Helm.
- Install a release: deploy with Helm and open the dashboard.
- GitHub PR previews: enable label-driven automation after onboarding.
- Web interface: see the preview workflow before installing.
- Workload types: choose HTTP previews, finite Jobs, or scheduled Jobs.
- Onboard an application: register an existing deployment.
- Architecture: understand the control plane and request path.
- MCP server: connect a coding agent.
For terminal workflows, install the CLI. Contributors can run Envy from source in a dedicated Kind cluster.