Deployment previews are a clean, simple mechanism to easily provide access to a development version of a service while it is still a pull request, before merging the new code. This reduces development time by making it significantly faster to iterate on new features or bugfixes. This means you no longer need to manually coordinate deployments to staging or test environments, deployment previews can handle as many development streams as you need for you.
- An application that can be deployed to K8s that is set up for GitOps:
- A repo that has all of the application code
- A declarative deployment configuration for that application (it could be in a second repo, or in the same one. In this tutorial, we use a second repo)
- A cluster connected to Ambassador Cloud (and be running Edge Stack 2.2.x+)
- Ambassador Cloud GitOps integration enabled on the repo containing the application code
- Argo CD set up to sync the deployment configuration into the cluster
- A container registry that has read/write permissions (we're using Docker in this tutorial, but it could be any)
Does your environment look different? We're actively working on making deployment previews more useful for more environments. Please let us know what your environment looks like. If you're an existing customer, please create a ticket; all other users please submit your email below.
To use deployment previews, you need to configure CI, Ambassador Cloud, and ArgoCD to work together, using a GitOps workflow:
Your cluster must be connected to Ambassador Cloud, and the GitHub repository for your service (the code repository) must have the Ambassador Cloud GitOps integration enabled. If you haven't done this yet, follow the GitOps with Ambassador Cloud quick start.
ArgoCD must be configured to sync manifests from a GitHub or GitLab repository into your cluster. This is the infrastructure repository; it may or may not be the same code respiratory. Confirm how your repository is configured before proceeding.
If you haven't configured how manifests are synced from your GitLab or GitHub repository yet, follow the ArgoCD quick start to complete this process.
Deployment previews rely on a Telepresence pod daemon container for routing. Your cluster must have RBAC configured for the deployment preview daemon container:bashkubectl apply -f https://app.getambassador.io/yaml/pod-daemon/deploy-previews-rbac.yaml
Your cluster needs a Secret containing your Ambassador Cloud API Key:yaml---apiVersion: v1kind: Secretmetadata:name: deployment-preview-apikeynamespace: deploy-previewstype: OpaquestringData:AMBASSADOR_CLOUD_APIKEY: "$AMBASSADOR_CLOUD_APIKEY"
This example assumes your are deploying your previews in the
deploy-previewsnamespace. There must be a
deployment-preview-apikeySecret in any namespace you use with deployment previews.
$AMBASSADOR_CLOUD_APIKEYwith your Ambassador Cloud API key. You can generate an API key from the Ambassador Cloud Settings
For every pull request you want to preview, CI in the code repository must:
- Build a Docker image for your service.
- Push the Docker image to a Docker registry that is accessible by your cluster.
- Commit a new manifest to the infrastructure repository that deploys the newly-built image to your cluster.
The exact way CI does these three things depends on your service. See the Manifest Requirements section below for more details.
When a pull request in the code repository is closed or merged, CI needs to delete the manifests it created.
After setup is complete, open a pull request in your code repository:
After CI publishes the image and manifests for your new deployment, Argo syncs the new deployment preview manifests into your cluster. (This may take a few minutes, depending on how Argo is configured.)
Once argo has synced the new manifests into your cluster, the deployment preview pod requests a new preview URL from Ambassador Cloud. Once the URL has been created, it is posted to your PR as a comment.
Simply open the preview URL in your browser and (if needed) authenticate to Ambassador Cloud to interact with your new deployment. You can share this URL with other members of your Ambassador Cloud organization to get their feedback, too.
Once your PR is merged or closed, CI removes the deployment preview manifests. If Argo is properly configured to automatically prune resources, it removes the deployment preview from your cluster. (Again, this may take a few minutes, depending on how Argo is configured.)
Since CI is responsible for creating the manifests used to deploy your service, it has enormous flexibility in how exactly the manifest is created. However, the manifest must include the deployment preview daemon container in your target application Deployment resource and its ServiceAccount:
serviceAccountName: ambassador-deploy-previewscontainers:# Include your application container# - name: your-original-application# image: image-built-from-pull-request# [...]# Inject the preview-daemon container- name: pod-daemonimage: docker.io/datawire/tel2:2.5.6-podd.0ports:- name: httpcontainerPort: 80- name: httpscontainerPort: 443resources:limits:cpu: "0.1"memory: 100Miargs:- pod-daemon- --workload-name=$NAME- --workload-namespace=$NAMESPACE- --port=$PORT- --ingress-tls=true- --ingress-port=443- --ingress-host=$INGRESS_HOST- --ingress-l5host=$PUBLIC_HOSTNAME- --pull-request=$PULL_REQUEST_URLenv:- name: AMBASSADOR_CLOUD_APIKEYvalueFrom:secretKeyRef:name: deployment-preview-apikeykey: AMBASSADOR_CLOUD_APIKEY- name: MANAGER_NAMESPACEvalue: ambassador
In the manifest, several things must be customized:
$PORTneed to match the name, namespace, and port of your live application (non-preview) Deployment.
$INGRESS_HOSTneeds to be the DNS name or IP address of the Edge Stack running in your cluster. In standard installations, it should be
$PUBLIC_HOSTNAMEneeds to be the DNS name where you would access your live application.
- If your Edge Stack is not doing TLS on port 443, edit the
- If your Telepresence traffic-manager is not running in the
ambassadornamespace, edit the
For an example of CI editing the manifest, see the deployment previews demo GitHub repo.