the Pull Request is built as a preview docker image and chart and deployed into the preview environment
a comment is added to the Pull Request to let your team know the preview application is ready for testing with a link to open the application. So in one click your team members can try out the preview!
Adding more resources
Its common when creating, for example, a web front end to need a backend or database to work from to verify that the microservice works.
For each application the preview environment is defined by a helm chart at: charts/preview/Chart.yaml.
So you can easily add any dependent helm charts to your preview environment by adding new entries in the file charts/preview/requirements.yaml.
You can find possible charts to install by searching helm. e.g. to find a postgresql chart try:
helm search postgres
Once you know the chart and the repository its in you can add it to your charts/preview/requirements.yaml file (the postgresql section in dependencies array):
# !! File must end with empty line !!dependencies:-alias:exposename:exposecontrollerrepository:https://chartmuseum.build.cd.jenkins-x.ioversion:2.3.56-alias:cleanupname:exposecontrollerrepository:https://chartmuseum.build.cd.jenkins-x.ioversion:2.3.56# Ephemeral PostgeSQL created in preview environment.-name:postgresqlrepository:https://kubernetes-charts.storage.googleapis.comversion:2.6.2# !! "alias: preview" must be last entry in dependencies array !!# !! Place custom dependencies above !!-alias:previewname:demo179repository:file://../demo179
Note: - alias: preview must be last entry in dependecies array and requirements.yaml file must end with empty line.
If you need any additional resources like ConfigMap, Secret or Service resources you can add them to charts/preview/templates/*.yaml.
You can always service link from the Preview Environment namespace to other namespaces by creating a Service with an externalName which links to a Service running in another namespace (such as Staging or Production) or to point to a service running outside of the Kubernetes cluster completely.
jx step link services --from-namespace jx-staging --includes "*" --excludes "cheese*"
If you need to tweak your application when running in a Preview Environment you can add custom settings to the charts/preview/values.yamlfile
Post preview jobs
One of the extension points of Jenkins X lets you put a hook in after a preview job has been deployed. This hook applies to all apps in a team even existing ones, for all new pull requests/changes. (You don’t have to add it to each pipeline by hand - it can be used to enforce best practices).
This means you can run a container Job against the preview app, validating it, before the CI pipeline completes. Should this Job fail, the pull request will be marked as a failure.
This creates a post preview job which runs the zap-baseline.py command inside the specified docker image (it will pull the image and run it, and then shut it down) which scans the running preview app for any problems.
The $JX_PREVIEW_URL environment variable is made available in case the job needs to access the running preview app. Use -c to pass commands to the container.
This job runs after the preview has been deployed. If it returns non zero, the PR will be marked as a failure.
You can also run:
jx get post preview
to list any configured post preview jobs, and:
jx delete post preview job --name=NAME_HERE
And it will remove that post preview job (for the whole team).
To get more detail on using preview environments check out this blog post