jx-preview

jx-preview is a small command line tool for creating Preview Environments in Jenkins X

Overview

The jx preview create command will create a new Preview environment, by default in its own unique namespace called jx-$owner-$repo-pr-$number using a helmfile located by default in the preview/helmfile.yaml directory.

New projects created with Jenkins X 3.x already have the preview/helmfile.yaml included. If your repository does not include this file it will be added into git in the Pull Request as an extra commit.

System tests in previews

If you wish to use a preview environment to run tests and interacting with the preview you can source the .jx/variables.sh file to then be able to interact with the preview via the PREVIEW_* environment variables.

e.g.

- name: test-preview
  image: golang:1.17.9
  script: |
    #!/usr/bin/env sh
    source .jx/variables.sh
    curl -v $PREVIEW_URL

Environment variables

The following variables are added to the .jx/variables.sh file by the jx preview create command:

• PREVIEW_URL the URL of the preview environment if it can be discovered
• PREVIEW_NAME the name of the Preview custom resource which has the full metadata
• PREVIEW_NAMESPACE the namespace of the preview environment which you can use via myservice.$PREVIEW_NAMESPACE.svc.cluster.local to access services in your preview

How it works

Creating a new preview environment creates a Preview custom resource for each Pull Request on each repository so that we can track the resources and cleanly remove them when you run jx preview destroy pr jx preview gc

For reference see the Preview.Spec documentation

Installation

If you are using Jenkins X 3.x then its already included by default so there's nothing to install.

If you are not using Jenkins X 3.x then you need to install the jx3/jx-preview chart to:

• install the Preview custom resource used to track the Preview environments
• setups a CronJob to garbage collect Preview environments when the Pull Requests have been closed or merged

To install the jx3/jx-preview chart using helm 3.x try the following::

• Add jx3 helm charts repo

helm repo add jx3 https://storage.googleapis.com/jenkinsxio/charts

helm repo update

• Install (or upgrade)

# This will install jx-preview in the jx namespace (with a jx-preview release name)

helm upgrade --install jx-preview --namespace jx jx3/jx-preview

Uninstalling

To uninstall the chart, simply delete the release.

# This will uninstall jx-preview in the jx-preview namespace (assuming a jx-preview release name)

# Helm v3
helm uninstall jx-preview --namespace jx

Debug

To debug jx preview inside a Running container: First modify you pipeline by editing pullrequest.yaml in your project, before jx preview add:

while true
do
  echo "waiting for debug"
  sleep 30
done

build your version of jx preview locally, and copy it inside the container

make build
kubectl cp ./build/jx-preview pr-xxxxxxxx:/ -c step-promote-jx-preview

once the pipeline reaches the promote-jx-preview step, exec into the container:

kubectl exec -it pr-xxxxxxxx -c step-promote-jx-preview -- sh

and run:

apk update
apk add go
go get github.com/go-delve/delve/cmd/dlv

then debug your binary using dlv (you can change create with gc...)

source /workspace/source/.jx/variables.sh # copied from pipeline
/tekton/home/go/bin/dlv --listen=:2345 --headless=true --api-version=2 exec /jx-preview create

redirect traffic from your port 2345 to the container in another terminal

kubectl port-forward pr-xxxxxxxx 2345

attach your debugger and happy debugging.

Do not forget to make build and kubectl cp after each change

Commands

See the jx-preview command reference