Installing CloudBees Previews

Follow the steps from example Basic installation via Helm to install CloudBees Previews using the CloudBees Previews Helm chart from the CloudBees chart repository.

Basic installation via Helm

kubectl create namespace previews
kubectl create secret generic --namespace previews license \          (1)
  --from-file=cert=cloudbees-ci-license.cert \
  --from-file=key=cloudbees-ci-license.key

helm repo add cloudbees https://charts.cloudbees.com/public/cloudbees (2)
helm repo update                                                      (3)

export ingress_host=previews.acme.com

helm install --namespace previews previews cloudbees/cloudbees-previews -f - <<EOF
global:
  license:
    secret: license
  analytics:
    enabled: true                                                     (4)
  ingress:
    host: ${ingress_host}                                             (5)
apiserver:
  auth:
    apiTokenSecretName: ""                                            (6)
EOF▼

1	Loads the CloudBees CI license.
2	Registers the public CloudBees Helm repository in your local Helm installation.
3	Downloads the latest CloudBees Helm repository index and registers the latest available chart versions with your local Helm installation.
4	Opts in to sending basic usage information to CloudBees. This will include the organization mentioned in the CloudBees CI license and the version of CloudBees Previews. As with Data collection for the CloudBees Analytics Plugin in CloudBees CI, no sensitive data will be transmitted without anonymization, but you may opt out by setting this to `false` instead.
5	Specifies the Ingress hostname. This value is mandatory.
6	Specifies the name of a Kubernetes Secret containing a token used to authenticate API clients. The Kubernetes Secret must hold a token within the `token` key. If you don’t specify a Secret name, a Secret will be generated once during installation but never updated. Alternatively, you can provide an API token here directly using the `apiToken` field, and let the chart generate the Kubernetes Secret.

Refer to CloudBees Previews Helm chart values for the full list of installation values.

If you let Previews generate the API token, you can obtain it from the Kubernetes Secret <RELEASE_NAME>-apiserver-auth-token as follows:

$ kubectl --namespace previews get secret previews-apiserver-auth-token -o jsonpath='{.data.token}' | base64 -d
YeOCuCyDcWpxzI2wbBMeOEs8f3YsNRdy▼

By default, the command listed above installs the latest version of the Helm chart. If you want to install a particular version, you can specify it by adding the --version option to the helm install command.

Name-based virtual hosting

You can use name-based virtual hosting with CloudBees Previews, but it is your responsibility to configure the virtual hosts. For more general information about name-based virtual hosting, refer to the Kubernetes documentation.

To use name-based virtual hosting, you either need to create a wildcard DNS record for your CloudBees Previews hostname, or you can dynamically create DNS entries. CloudBees recommends that you use a wildcard DNS entry, for example *.previews.acme.com, to direct all subdomains of the specified wildcard domain to the CloudBees Previews LoadBalancer. You can also automate creating DNS entries using ExternalDNS. Please refer to the ExternalDNS documentation for installation and configuration instructions.

You can use nip.io for a quick test of CloudBees Previews without having to configure any DNS settings. Use previews.<Cluster LoadBalancer IP>.nip.io as ingress host in the example Basic installation via Helm. This approach does not support TLS.

If you are using Kubernetes Ingress in your preview environments, name-based virtual hosting imposes constraints on the ingress controller: it must be possible to route traffic to a new domain merely by creating an Ingress resource in a new namespace.

For example, NGINX Ingress Controller is known to work with CloudBees Previews: the controller automatically coalesces whatever Ingress resources it finds and routes accordingly. The ingress controller built into Google Kubernetes Engine (GKE) using a static IP address is known not to work: each Ingress resource produces a new load balancer, which requires a distinct IP address.

TLS

To use CloudBees Previews with HTTPS, you must provide a wildcard certificate for the hostname. Place this certificate, together with its private key, in a Kubernetes Secret located in the CloudBees Previews installation namespace. Then, you can reference this secret as an additional value in your helm install command.

Installation of CloudBees Previews with TLS enabled

kubectl create namespace previews
kubectl create secret generic --namespace previews license \
  --from-file=cert=cloudbees-ci-license.cert \
  --from-file=key=cloudbees-ci-license.key
kubectl create secret tls --namespace previews tls \         (1)
  --cert=tls.cert --key=tls.key

export ingress_host=previews.acme.com
export ingress_class=nginx

helm install --namespace previews previews cloudbees/cloudbees-previews -f - <<EOF
global:
  license:
    secret: license
  analytics:
    enabled: true
  ingress:
    host: ${ingress_host}
    class: ${ingress_class}
    tlsSecret: tls
EOF▼

1	Loads the TLS certificate and private key for *.previews.acme.com.

In Installation of CloudBees Previews with TLS enabled the CloudBees Preview webhook component and the preview environments share the same subdomain and TLS secret. Refer to Using a dedicated domain for environments for more information on how to further secure your SCM provider integration.

Hierarchical Namespace Controller (HNC)

CloudBees Previews depends on the Hierarchical Namespace Controller (HNC) and installs it by default. If your cluster already has HNC installed, you can set hnc.install to false to skip its installation.

HNC enables CloudBees Previews to create an isolated namespace for each preview environment. In this case, the CloudBees Previews installation namespace serves as the root namespace for any preview environments you create.