Previews YAML

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)▼

1	File format version for compatibility purposes.
2	Preview 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.
3	Image 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.
4	Command to run the application container. This value is optional.
5	Command-line arguments for the application container. This value is optional.
6	List of environment variables passed to the container, potentially referencing configured custom secrets. This value is optional.
7	Port on which the application is listening. This value is optional.
8	Timeout 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)▼

1	Setting 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)▼

1	File format version for compatibility purposes.
2	Path to a deployable chart within the repository.
3	Paths to values files (corresponds to the `-f` option of the `helm template` command; optional).
4	Embedded values with placeholder support (corresponds to the `--set` option of the `helm template` command; optional).
5	Timeout 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)▼

1	File format version for compatibility purposes.
2	Helm repository URL where the chart is located.
3	Name of the chart located within the repository.
4	Version of the chart located within the repository. It may contain version ranges. If this is empty, the latest version of the chart is used.
5	Paths to values files (corresponds to the `-f` option of the `helm template` command; optional).
6	Embedded values with placeholder support (corresponds to the `--set` option of the `helm template` command; optional).
7	Timeout 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).