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 a8r.io:

AnnotationDescriptionExample
a8r.io/descriptionUnstructured text description of the service for humansEdge Stack, responsible for handling all ingress traffic
a8r.io/ownerGitHub or equivalent username (prefix with @), email address, or unstructured owner description@edgey
a8r.io/chatSlack channel, or link to other external chat system#ambassador
a8r.io/bugsLink to external bug trackerhttps://github.com/datawire/ambassador/issues
a8r.io/logsLink to external log viewerhttps://kibana.getambassador.io
a8r.io/documentationLink to external project documentationhttps://www.getambassador.io/docs/edge-stack/latest/
a8r.io/repositoryLink to external VCS repositoryhttps://github.com/datawire/ambassador
a8r.io/supportLink to external support centerhttp://a8r.io/slack
a8r.io/runbookLink to external project runbookhttps://www.getambassador.io/docs/edge-stack/latest/topics/running/debugging/
a8r.io/ignoreWhen present, prevent the service from appearing in the Service Catalogany
a8r.io/incidentsLink to external incident dashboardhttps://incidents.getambassador.io
a8r.io/uptimeLink to external uptime dashboardhttps://uptime.getambassador.io
a8r.io/performanceLink to external performance dashboardhttps://performance.getambassador.io
a8r.io/dependenciesUnstructured text description of the service dependencies for humansRedis
a8r.io/rollouts.scm.pathPath to the directory containing manifests for this servicepath/to/directory
a8r.io/rollouts.scm.branchBranch to target for rollout pull requestsmain
a8r.io/rollouts.image-repo.typeImage repository type for rollouts; currently, only dockerhub is supporteddockerhub
a8r.io/rollouts.image-repo.nameBase image name that should be updated by rolloutsdocker.io/datawire/demo-image
a8r.io/rollouts.deploymentName of the Kubernetes Deployment or Rollout object to update for rolloutsdemo-app
a8r.io/rollouts.mappingsComa 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:

a8r.io/repository: "<repo URL>"

Your updated Service config should look something like this:

Finally, apply the updated YAML to your cluster: