Docsright arrowAmbassador Cloudright arrowAnnotating in Ambassador Cloud

4 min • read

Annotating in Ambassador Cloud

Service Catalog lists all the services in your cluster, including helpful information like the owner, a description of the service, links to documentation, and more.

This information is all sourced from annotations set on the services. Annotations can be set either via kubectl or via Kubernetes YAML files.

A Convention for Annotations

The following are the supported annotation keys, also documented at

AnnotationDescriptionExample text description of the service for humansEdge Stack, responsible for handling all ingress traffic or equivalent username (prefix with @), email address, or unstructured owner description@edgey channel, or link to other external chat system#ambassador to external bug tracker to external log viewer to external project documentation to external VCS repository to external support center to external project runbook present, prevent the service from appearing in the Service Catalogany to external incident dashboard to external uptime dashboard to external performance dashboard text description of the service dependencies for humansRedis to the directory containing manifests for this servicepath/to/directory to target for rollout pull requestsmain repository type for rollouts; currently, only dockerhub is supporteddockerhub image name that should be updated by of the Kubernetes Deployment or Rollout object to update for rolloutsdemo-app separated list of Mapping objects that should control rollout trafficdemo-app-mapping,other-mapping

Annotating with kubectl

Find a service you would like to add an owner annotate to in your Service Catalog.

Run the following command, filling in the service name and your name:

Refresh your browser the owner is field updated.

If an annotation already exists for that key you will get an error; add the --overwrite flag:

If your service is in a namespace other than default, you must specify it with the --namespace flag:

While this is a quick and effective way to set a single annotation on a service, it doesn't scale well to setting multiple annotations. It also doesn't follow GitOps best practices; resource updates should be stored in version control and applied through a deployment pipeline. To accomplish this, you can add annotations to your YAML directly.

Annotating YAML config files directly

Open the YAML config file of one of your services.

Navigate to the metadata property and locate the annotations property directly beneath it.

If you cannot find an annotations property, add one to your config in the location shown above.

Now add the following annotation, filling in your repo URL: "<repo URL>"

Your updated Service config should look something like this:

Finally, apply the updated YAML to your cluster: