Service Catalog Quick Start

The Power of Kubernetes Annotations

Have you ever been asked to troubleshoot a failing Kubernetes service and struggled to find basic information about the service such as the source repository and owner? Troubleshooting always begins with information gathering.

Kubernetes annotations are designed to solve exactly this problem. They are designed to add metadata to Kubernetes objects.

Using kubectl, let's create a basic service named ghost-service with the a8r.io/description annotation set to "An annotated ghost service that points to nowhere in particular".

Copy and paste this into your terminal:

cat <<EOF | kubectl create -f -
apiVersion: v1
kind: Service
metadata:
  name: ghost-service
  annotations:
    a8r.io/description: "An annotated ghost service that points to nowhere in particular"
spec:
  ports:
    - protocol: TCP
      port: 80
EOF

You can easily view all of the annotations on your new service using kubectl:

$ kubectl describe svc ghost-service
  
  Name:              ghost-service
  Namespace:         default
  Labels:            <none>
  Annotations:       a8r.io/description: An annotated ghost service that points to nowhere in particular
  ...

You can also add annotations using the kubectl annotate command:

$ kubectl annotate svc ghost-service a8r.io/owner=Casper
  
  service/ghost-service annotated
  
$ kubectl describe svc ghost-service 
  
  Name:              ghost-service
  Namespace:         default
  Labels:            <none>
  Annotations:       a8r.io/owner: Casper
                     a8r.io/description: An annotated ghost service that points to nowhere in particular
  ...

As your number of services grows it can be challenging to view all of the annotation information via kubectl describe.

Ambassador Cloud Service Catalog provides a centralized view with an easily navigable web-based UI of your services running in all of your clusters. Let’s configure this now!

Prerequisites

Service Catalog requires Edge Stack version 1.12 or greater to be installed in your cluster.

Install Edge Stack from here if needed.

If you already have Edge Stack installed, check your version by running this command:

kubectl get deploy -n ambassador ambassador -o jsonpath='{.spec.template.spec.containers[0].image}'

Is the image at version 1.12 or greater? Then you are ready to start using Service Catalog!

If not, follow this doc to upgrade Edge Stack.

1. Connect your Cluster to Ambassador Cloud

The Service Catalog is a web-based interface that lists all of your cluster's Services. You can view, add, and update metadata associated with each Service, such as the owner, version control repository, and associated Slack channel.

1. Log in to Ambassador Cloud with your GitHub account.

2. At the top, hover over All Clusters then click Add a Cluster.

3. Follow the prompts to name the cluster and click Generate a Cloud Token.

4. Follow the prompts to install the cloud token into your cluster.

5. When the token installation completes, refresh the Service Catalog page.

If you installed Edge Stack into an empty cluster you won't see any services in your catalog (except for the Edge Stack services which start with ambassador). Apply this sample app to quickly see an example of a service in the catalog:

kubectl apply -f http://getambassador.io/yaml/quickstart/qotm.yaml

Then refresh your Service Catalog page and you should see the quote service listed.

2. Claim Ownership of a Service

Click the quote service in the list. The service details page now opens that displays additional information about the service.

The metadata for each service is determined by annotations included within your Kubernetes YAML config files. You can annotate the config of the ambassador service that you have just installed to display your name.

1. Change the name of the owner of the quote service by replacing <your name> in the command below and running it:

   Terminal

   copied

   kubectl annotate --overwrite svc quote -n ambassador a8r.io/owner="<your name>"

2. Refresh your Service Catalog page anl dook at the quote service to see the change with your name.

Modifying the annotations via kubectl is quick and easy, but the changes made to the annotations will not remain if a new deployment of the service is made.

Let's set another annotation using YAML instead to ensure that a new deployment includes the annotations.

3. Add Additional Metadata via YAML

Open the YAML config file of one of your services. If you applied our quote service earlier, you can download the YAML here.

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

   yaml

   copied

   apiVersion: v1
   kind: Service
   metadata:
     name: <service name>
     annotations:

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

2. Now add the following annotation, replacing <repo URL> with the related Git repository for the service:

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

   Your updated Service config should look something like this:

   yaml

   copied

   apiVersion: v1
   kind: Service
   metadata:
     Name: <service name>
     annotations:
       a8r.io/repository: "https://github.com/datawire/ambassador"

3. Now apply this updated YAML to your cluster, replacing the file name:

   Terminal

   copied

   kubectl apply -f my_service.yaml

What's Next?

You've updated the owner and repo URL, but Service Catalog supports many more annotations! See the full list here.