Previews YAML

5 minute read

Each repository you want to enable for CloudBees Previews requires a .preview.yaml in the root directory. .preview.yaml forms the contract between the application and the preview environment. Most importantly, it tells CloudBees Previews which type of technology the project uses, and how to translate a request for a preview environment into a live deployment.

.preview.yaml can contain multiple named environment configurations, called contexts. You can select a context by providing the context name in the pull request comment, for example, /preview web. If there is no explicit name specified with the(/preview) comment, the context name defaults to "default".

Each supported technology has a specific configuration format explained in detail in the following sections.

Generated manifests

The generated manifests format is useful if you are not using a Kubernetes deployment technology like Helm or Kustomize. Generated manifests only require that you have a containerized application for which you can provide the image. In the configuration, you specify the image, its command and arguments, environment variables, as well as which port the application uses. CloudBees Previews uses this information to generate a set of default Kubernetes resources for the environment.

previews.yaml configuration for generated manifests shows how the configuration for an example application my-app might look:

previews.yaml configuration for generated manifests
apiVersion: 1.0.0                                 (1)
previews:
- name: default                                   (2)
  container:
    image: my.registry/my-app:${{env.commit.sha}} (3)
    command:
    - serve                                       (4)
    args:
    - debug=true                                  (5)
    env:                                          (6)
      DB_NAME: "my-app"
      DB_USER: "${{secrets.mysql_db.user}}"
      DB_PASS: "${{secrets.mysql_db.pass}}"
    port: 8080                                    (7)
    config:
      deployTimeout: "20m"                        (8)
1File format version for compatibility purposes.
2Preview identifier. By choosing default, you can create the environment by either adding /preview or /preview default as a comment on the pull request. This value is mandatory.
3Image to run. ${{env.commit.sha}} is a variable interpolated by CloudBees Previews at build time. See Variable interpolation for more information. This value is mandatory.
4Command to run the application container. This value is optional.
5Command-line arguments for the application container. This value is optional.
6List of environment variables passed to the container, potentially referencing configured custom secrets. This value is optional.
7Port on which the application is listening. This value is optional.
8Timeout the deployer waits for the preview to become ready (ms|s|m|h).

By default, CloudBees Previews assumes you want to expose an HTTP(S) port and uses name based virtual hosting to expose your application. However, you can configure this behavior.

Ingresses

Ingresses are a Kubernetes resource type that route from outside the cluster to services within the cluster. By default, generated manifests create an Ingress for your application using the environment’s unique name together with the Ingress host specified during the CloudBees Previews installation. The final environment URL has the form: http:://${{env.name}}.<environments.ingress.host>.

NodePorts

If you do not want to use an Ingress, for example, because your application provides a non-HTTP based port, you can set an explicit protocol type as part of the .preview.yaml configuration. The explicit protocol instructs CloudBees Previews to create a NodePort instead of an Ingress. Example Exposing application as NodePort shows the explicit use of protocol:

Exposing application as NodePort
apiVersion: 1.0.0
previews:
- name: default
  container:
    image: my.registry/my-app:${{env.commit.sha}}
    command:
    - serve
    args:
    - debug=true
    ports:
    - value: 8080
      protocol: TCP (1)
1Setting the protocol to TCP instructs CloudBees Previews to expose the application as NodePort. Other possible values for protocol are HTTP, TCP, and UDP. The default is HTTP.
When using NodePorts, you might have to configure your firewall to allow connections for the default node port range 30000 - 32767.

Helm

Previews can also be created from Helm charts. This is recommended when you’re developing an individual chart or if the built-in manifest generation is not sufficient.

Local chart

If you already maintain a Helm chart within your Git repository, you can simply refer to its path and configure static local values files as well as dynamic values that are provided at runtime by CloudBees Previews (e.g. for container image(s) or Ingress hostnames), as the following example shows:

previews.yaml configuration using a local Helm chart
apiVersion: 1.0.0                                (1)
previews:
- name: myappchart
  helm:
    chart: ./charts/myappchart                   (2)
    valuesFiles:                                 (3)
    - ./charts/myappchart/preview-values.yaml
    values:                                      (4)
      image:
        tag: ${{env.commit.sha}}
      ingress:
        host: myapp.${{env.hostname}}
        tlsSecretName: ${{env.ingress.tlsSecretName}}
      instanceName: ${{env.name}}
    config:
      deployTimeout: "20m"                        (5)
1File format version for compatibility purposes.
2Path to a deployable chart within the repository.
3Paths to values files (corresponds to the -f option of the helm template command; optional).
4Embedded values with placeholder support (corresponds to the --set option of the helm template command; optional).
5Timeout the deployer waits for the image pull to succeed and the preview to become ready (ms|s|m|h).

CloudBees Previews automatically builds your chart’s dependencies, including transitive dependencies, when required. It can use any Helm repository that is referenced within the provided chart.

If your chart supports path-based Ingresses, you can also assign ${{env.name}} to a corresponding path value of your chart.

Remote chart

If you don’t want to maintain a chart within your Git repository and generated manifests do not meet your requirements, you can refer to a remote chart. Using a remote chart lets you customize Kubernetes manifests consistently within your organization, maintain a chart for similar applications centrally, and avoid maintaining redundant chart templates within many repositories. Using a remote Helm chart looks similar to using a local chart. The differences are that the configuration must specify a repository URL, the chart specifies a name instead of a path, and you may specify the version field as well, as the following example shows:

previews.yaml configuration using a remote Helm chart
apiVersion: 1.0.0                                (1)
previews:
- name: myappchart
  helm:
    repository: https://helm.repo.example.org    (2)
    chart: hello-world                           (3)
    version: 0.9.x                               (4)
    valuesFiles:                                 (5)
    - ./charts/myappchart/preview-values.yaml
    values:                                      (6)
      image:
        tag: ${{env.commit.sha}}
      ingress:
        host: myapp.${{env.hostname}}
        tlsSecretName: ${{env.ingress.tlsSecretName}}
      instanceName: ${{env.name}}
    config:
      deployTimeout: "20m"                       (7)
1File format version for compatibility purposes.
2Helm repository URL where the chart is located.
3Name of the chart located within the repository.
4Version of the chart located within the repository. It may contain version ranges. If this is empty, the latest version of the chart is used.
5Paths to values files (corresponds to the -f option of the helm template command; optional).
6Embedded values with placeholder support (corresponds to the --set option of the helm template command; optional).
7Timeout the deployer waits for the image pull to succeed and the preview to become ready (ms|s|m|h).

Variable interpolation

CloudBees Previews lets you use a predefined set of variables in .preview.yaml to configure image tags and Ingresses generically. The following variables are currently available for interpolation:

env.commit.sha

The Git commit SHA for which the preview environment is created.

env.commit.shortSha

The Git short commit SHA (7 digits) for which the preview environment is created.

env.name

A unique name for the environment provided by CloudBees Previews.

env.hostname

A unique hostname that is built from env.name and the domain that is globally configured using the CloudBees Previews Helm chart’s value environments.ingress.host.

env.ingress.tlsSecretName

The name of a Kubernetes Secret that contains the TLS certificate for the preview.

env.ingress.class

The name of a Kubernetes Ingress class that should be used for the preview.

env.image.pullSecretName

The name of the Secret containing the Docker credentials for pulling from the configured private image registries. See Using private image registries.

secrets.*

Namespace of all custom secrets made available via the GitRepository. See also Using custom secrets. Secrets can only be referenced within the env section of a container preview (see previews.yaml configuration for generated manifests) or within values of a Helm preview (see previews.yaml configuration using a local Helm chart).