Preview apps

What is a preview?#

A preview (Review App) is a running copy of a pull request (merge request on GitLab). For every PR, EJO creates a separate namespace in your shared cluster, deploys the application there and writes a URL of the form https://<preview-name>.preview.example.com into a PR comment. When the PR closes, the namespace is deleted.

Previews work on GitHub, GitLab and Azure DevOps. On this page "PR" also covers GitLab merge requests.

• The preview name (also the namespace name) starts with ejo-, contains the repository name and ends in -pr-<number>.
• New pushes to the same PR update the same namespace.
• Each PR gets a single comment, updated on every push.

Per SCM#

On GitLab and Azure DevOps, EJO needs a GitLab token or an Azure DevOps PAT to write comments and statuses; without one, no comment or status is written and you see the preview under Delivery > Previews. See Connect your source control.

Prerequisites#

• An environment of type Kubernetes.
• An agent installed with the Preview namespaces (Review Apps) option. This lets the agent create and delete preview namespaces. See Installing an agent.
• An ingress controller in the cluster and a wildcard DNS record for the preview domain, for example *.preview.example.com.
• A CNI that enforces NetworkPolicy (for example Calico or Cilium; k3s's built-in controller does too). Plain flannel does not.

Setup#

1. On the environment page, press Set up previews. The preview setup wizard opens.
2. In Preview base domain, enter the domain your wildcard DNS points at, for example preview.example.com. The wizard shows an example URL.
3. Set the ingress class, TLS secret, TTL, quota and egress as needed (see the table below).
4. Tick My cluster's CNI enforces NetworkPolicy.
5. On the repository binding, turn on Preview on PR (isolated name, tear down when the PR closes). This also turns on the PR trigger. See Triggers and bindings.

You can also set the binding options with the preview: block of the .ejo file. See The .ejo file.

Environment settings#

Binding settings#

Previews in the pipeline#

In preview runs, K8S_DEPLOY and HELM_UPGRADE steps deploy into the PR namespace and create an Ingress automatically. K8S_DEPLOY waits for the rollout, then requests the health path for wait_seconds (default 60); if nothing answers, the step fails.

Several services in one PR can share the same preview host. Give each step a name with preview_service and a path with preview_path:

steps:
  - name: web
    kind: K8S_DEPLOY
    config:
      image: "{{.WebImage}}"
      container_port: 3000
      preview_service: web
  - name: api
    kind: K8S_DEPLOY
    config:
      image: "{{.ApiImage}}"
      container_port: 8080
      preview_service: api
      preview_path: /api
      preview_health_path: /api/healthz

SECRET variables defined for the environment are written to a Secret named ejo-preview-vars in each preview namespace, and K8S_DEPLOY hands these values to the container.

Isolation and egress#

Preview namespaces are isolated with NetworkPolicy: by default they can reach only their own namespace and DNS. Open up what the apps really need with the egress allowlist:

Egress changes reach existing previews on their next push.

Warning: If your CNI does not enforce NetworkPolicy, previews are not isolated. Check this carefully if production and previews share a cluster.

With the merge gate#

With Also wait for the Review App URL on the binding, the merge gate waits until the PR run has a preview URL. This wait runs on the EJO side on every SCM; on the SCM side:

• On GitHub, the merge gate ruleset also requires the ejo/preview status.
• On Azure DevOps, EJO adds a second blocking status policy for the name preview.
• On GitLab, EJO changes nothing extra.

Manage previews#

The Delivery > Previews page lists previews across every Kubernetes environment. From a preview's detail panel you can:

• Pin: keep the preview out of TTL cleanup.
• Extend TTL (+24h): extend its lifetime. An extension can be between 1 and 168 hours.
• Redeploy: rerun its latest pull request deployment.
• Restart, Sleep, Wake: restart the workloads, scale them to zero, or bring them back to their earlier replica count.
• View pods, logs, events and quota usage.
• Tear down: remove the preview right away.

Pinning, extending and tearing down need the developer or admin role.

Teardown#

A preview is removed when the PR closes (merged or closed on GitLab, completed or abandoned on Azure DevOps), when its TTL expires, when its label is removed, or when it is removed from the console. The namespace is deleted and the PR comment is updated with the heading ### EJO preview removed and the reason.

Next steps#

• Triggers and bindings
• Supply chain security
• Troubleshooting