4 min • read

Annotations

Contents

About annotations

Annotations are used to attach metadata to your Kubernetes objects. Typically they are used to provide contextual information around the object for teammates or information used by third-party tools. Service Catalog combines these uses to build a readily available catalog of your services, accessible by your teammates via Ambassador Cloud.

Supported annotations

Service Catalog's supported annotation keys all start with a8r.io followed by the specific field. These are the metadata keys that Service Catalog supports:

KeyDescriptionExample
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

To learn more about the a8r.io/rollouts.* annotations, see the progressive delivery reference.

Annotate via kubectl

shell
kubectl annotate svc <service name> a8r.io/owner="<your name>"

If an annotation already exists for that key, you will get an error. You must add the --overwrite flag:

shell
kubectl annotate --overwrite svc <service name> a8r.io/owner="<your name>"

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

shell
kubectl annotate svc <service name> --namespace <namespace> a8r.io/owner="<your name>"

Annotate via YAML

shell
apiVersion: v1
kind: Service
metadata:
Name: your_service_name
annotations:
a8r.io/repository: "https://github.com/<your org>/<your repo>"

Example YAML

An example service YAML completely annotated can be seen below:

yaml
apiVersion: v1
kind: Service
metadata:
Name: ambassador
annotations:
a8r.io/description: "Edge Stack, responsible for handling all ingress traffic"
a8r.io/owner: "Edgey"
a8r.io/chat: "#ambassador"
a8r.io/bugs: "https://github.com/datawire/ambassador/issues"
a8r.io/logs: "https://kibana.getambassador.io"
a8r.io/documentation: "https://www.getambassador.io/docs/edge-stack/latest/"
a8r.io/repository: "https://github.com/datawire/ambassador"
a8r.io/support: "http://a8r.io/slack"
a8r.io/runbook: "https://www.getambassador.io/docs/edge-stack/latest/topics/running/debugging/"
a8r.io/incidents: "https://incidents.getambassador.io"
a8r.io/uptime: "https://uptime.getambassador.io"
a8r.io/performance: "https://performance.getambassador.io"
a8r.io/dependencies: "Redis"

Once you have modified your YAML, don’t forget to apply this with kubectl or via your standard deployment process:

shell
kubectl apply -f my_service.yaml