- The Mapping Object
- Automatic Retries
- Canary Releases
- Circuit Breakers
- Cross-Origin Resource Sharing
- Method-based Routing
- Prefix Regex
- Traffic Shadowing
- Developer Portal
- Edge Policy Console
- The Ambassador Module
- Gzip Compression
- Host CRD, ACME Support, and External Load Balancer Configuration
- Ingress Controller
- Troubleshooting Ambassador
- Custom Filters
- Knative Serverless Framework
- Prometheus monitoring
- Frequently Asked Questions
The Ambassador Edge Stack Operator is a Kubernetes Operator that controls the complete lifecycle of Ambassador in your cluster. It also automates many of the repeatable tasks you have to perform for the Ambassador Edge Stack. Once installed, the AES Operator will automatically complete rapid installations and seamless upgrades to new versions of Ambassador. Read more about the benefits of the Operator.
A Kubernetes operator is a software extension that makes it easier to manage and automate your Kubernetes-based applications, in the spirit of a human operator. Operators complete actions such as deploying, upgrading and maintaining applications, and many others. Read more about Kubernetes Operators here.
This document covers installing the Operator:
And also shows how the Operator automatically updates versions.
Start by installing the operator:
Create the Operator Custom Resource schema with the following command:
kubectl apply -f https://github.com/datawire/ambassador-operator/releases/latest/download/ambassador-operator-crds.yaml
Install the actual CRD for the Ambassador Operator in the
ambassadornamespace with the following command:
kubectl apply -n ambassador -f https://github.com/datawire/ambassador-operator/releases/latest/download/ambassador-operator.yaml
To install the Ambassador Operator CRD in a different namespace, you can specify it in
NSand then run the following command:$ NS="custom-namespace"$ curl -L https://github.com/datawire/ambassador-operator/releases/latest/download/ambassador-operator.yaml | \sed -e "s/namespace: ambassador/namespace: $NS/g" | \kubectl apply -n $NS -f -
Then, create the
AmbassadorInstallation Custom Resource schema and apply it to the AES Operator.
- To create the
AmbassadorInstallationCustom Resource schema, use the following YAML as your guideline.
- Save that file as
- Edit the
amb-install.yamland optionally complete configurations such as Version constraint or UpdateWindow:
- Finally, apply your
AmbassadorInstallationCRD to the AES Operator schema with the following command:
kubectl apply -n ambassador -f amb-install.yaml
After the initial installation of Ambassador, the Operator will check for updates every 24 hours and delay the update until the Update Window allows the update to proceed. It will use the Version Syntax for determining if any new release is acceptable. When a new release is available and acceptable, the Operator will upgrade Ambassador.
To specify version numbers, use SemVer for the version number for any level of
precision. This can optionally end in
*. For example:
1.0= exactly version 1.0
1.1= exactly version 1.1
1.1.*= version 1.1 and any bug fix versions 1.1.1, 1.1.2, 1.1.3, etc.
2.*= version 2.0 and any incremental and bug fix versions 2.0, 2.0.1, 2.0.2, 2.1, 2.2, 2.2.1, etc.
*= all versions.
3.0-ea= version 3.0-ea1 and any subsequent EA releases on 3.0. Also selects the final 3.0 once the final GA version is released.
4.*-ea= version 4.0-ea1 and any subsequent EA release on 4.0. This also selects:
- the final GA 4.0.
- any incremental and bug fix versions 4.* and 4
- the most recent 4.* EA release (i.e., if 4.0.5 is the last GA version and there is a 4.1-EA3, then this selects 4.1-EA3 over the 4.0.5 GA).
Read more about SemVer here.
updateWindow is an optional item that will control when the updates can take
place. This is used to force system updates to happen during specified times.
There can be any number of
updateWindow entries (separated by commas).
Never turns off automatic updates even if there are other entries in the
Never is used by sysadmins to disable all updates during
blackout periods by doing a
kubectl apply or using our Edge Policy Console to
updateWindow is in crontab format (see https://crontab.guru/) Some
0-6 * * * SUN: every Sunday, from 0am to 6am
5 1 * * *: every first day of the month, at 5am
The Operator cannot guarantee minute time granularity, so specifying a minute in the crontab expression can lead to some updates happening sooner/later than expected.
helmValues is an optional map of configurable parameters of the Ambassador chart
with some overriden values. Take a look at the current list of values
and their default values.
You must take into account some rules when settings these values in the
- All the values must be encoded as strings. This is specially important for integers (ie, use
"80"instead of just
- You must use a backslash to escape the
,characters:You must escape dot sequences as well, which may come in handy when charts use thehelmValues:name: "value1\,value2"
toYamlfunction to parse annotations, labels and node selectors. So you must use:instead of:# this is validhelmValues:nodeSelector.kubernetes\.io/role: master# this is NOT validhelmValues:nodeSelector:kubernetes.io/role: master
- Complex data structures must be collapsed, using dots for separating all the elements in a tree
for creating lists. For example, you should use:instead of:# this is validhelmValues:service.ports.name: "http"service.ports.port: "80"service.ports.targetPort: "8080"service.ports.name: "https"service.ports.port: "443"service.ports.targetPort: "8443"# this is NOT validhelmValues:service:ports:- name: httpport: 80targetPort: 8080- name: httpsport: 443targetPort: 8443
You can also install the AES Operator from a Helm Chart. The following Helm values are supported:
image.name: Operator image name
image.pullPolicy: Operator image pull policy
namespace: namespace in which to install the Operator
To do so:
Add the Helm repository to your Helm client with
helm repo add datawire https://getambassador.io
Run the following command:
helm install datawire/ambassador-operator
Once the new Operator is working, create a new CRD called
AmbassadorInstallationbased on the following YAML:$ cat <<EOF | kubectl apply -n ambassador -f -apiVersion: getambassador.io/v2kind: AmbassadorInstallationmetadata:name: ambassadorspec:version: 1.2.0EOF
AmbassadorInstallation is created for the first time, the Operator
will then use the list of releases available for the Ambassador Helm Chart for
determining the most recent version that can be installed, using the optional
Version Syntax for filtering the releases that are acceptable.
It will then install Ambassador, using any extra arguments provided in the
logLevel or any of the
$ cat <<EOF | kubectl apply -n ambassador -f -apiVersion: getambassador.io/v2kind: AmbassadorInstallationmetadata:name: ambassadorspec:version: 1.2.0EOF
After applying an
AmbassadorInstallation customer resource like this in a new cluster, the Operator will install a new instance of Ambassador 1.2.0 in the
ambassador namespace, immediately. Removing this
AmbassadorInstallation will uninstall Ambassador from this namespace.
To verify that everything was installed and configured correctly, you can visually confirm the set up in the Edge Policy Console on the “Debugging” tab. Alternatively, you can check the Operator pod in your cluster to check its health and run status.