One-click Preview Environments

Preview Environments

Preview Environments are branch specific namespaces that are created from the Cloud UI. You can create those from the Preview Environments tabs in the Project page.

These type of environments are useful when you don't want to set-up automatic deployment from CI or to give users the ability to spin-up production like previews of the application on-demand. This might be relevant for a user who does not have access to the code of your project or your cloud provider or to someone who is not familiar with the steps required to spin up an environment from the CLI.

Setup

To be able to effortlessly create preview environment you'll need to go through few configuration steps to allow Garden Cloud to connect to your cluster and to deploy to dynamically created namespaces.

Authentication to your providers

Garden Cloud needs to be able to authenticate to your providers. Please follow the Authenticating to your providers guide to set this up.

Templating your Preview Environment name, namespaces, hostnames

Garden Cloud exposes an environment variable called GARDEN_RUN_NUMBER which can be used to template hostnames, namespaces and the likes.

Here's an example configuration to use the variable to setup a namespace and hostname for Preview Environments.

# project.garden.yaml
kind: Project
name: vote-demo
defaultEnvironment: dev
id: <garden-cloud-id>
domain: https://<garden-cloud-hostname>

variables:
  # We template the GARDEN_RUN_NUMBER in the prev-env-name
  # If the variable is not defined, we use local.username
  prev-env-name: vote-demo-preview-${local.env.GARDEN_RUN_NUMBER || local.username}
[...]

environments:
  - name: preview
    # We use the variable above to set the namespace
    defaultNamespace: ${var.prev-env-name}
    variables:
      # We set a new variable to template the hostname for our ingress
      base-hostname: ${var.prev-env-name}.your-domain.com

providers:
  [...]

# vote.garden.yaml

kind: Module
name: vote
type: container
services:
  - name: vote
    args: [npm, run, serve]
    ports:
      - name: http
        containerPort: 8080
    ingresses:
      - path: /
        port: http
        # We reference the templated variable here
        hostname: vote.${variables.base-hostname}
    dependencies:
      - api
tests:
[...]

Creating Preview Environments

To create a new Preview Environment, please select the branch you want to deploy and a Garden environment where you want to deploy your project to.

Garden Cloud will proceed to schedule a Runner which will run garden deploy against your chosen branch and environment.

Create Environment

Environment Creating

Environment Created

Updating a Preview Environment

To update a Preview Environment, please click the Update icon for your Environment in the list.

Garden Cloud will proceed to schedule a Runner which will run garden deploy for the branch and environment that you choose originally.

Updating Environment

Deleting a Preview Environment

To delete a Preview Environment, please click the Delete icon for your Environment in the list.

Garden Cloud will proceed to schedule a Runner which will run garden delete for the branch and environment that you originally chosen.

Environment Delete - Confirm

Environment Deleting

Troubleshooting

Authentication failed

You might find the deploy fails with a similar message:

Authentication to cluster failed

Authentication to cluster failed - Logs

Please check and re-test your Authentication method, making sure the secrets used in the initialization scripts are correctly stored in Garden Cloud.

Deleting the environment failed because branch does not exist

In case the branch was deleted, it will not be possible to remove the preview environment since it is configured to run on a specific branch. Re-create the branch and push it to the repo before trying to delete the environment again. If the deleted branch was merged with the main git branch, it is often safe to create a branch with the same name directly from main.