Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

Fresh Espresso & Open Source Cloud

I have a passion for all things open source. I live in Ipswich MA and work for Red Hat, on the fabric8 project. Fabric8 is a cloud micro-services platform so you can deploy your applications to an all open source cloud. I kayak on the Atlantic Ocean along the coastal North East from Massachusetts to Maine whenever I can.

Proposal for Kubernetes Service Annotations.

1. Updated version

2. Problem description

  • Service URL - Every Service has one (or more) endpoint. As a rule the endpoint should be located at the root "/" of the localtion URL, i.e. There are cases where this is not possible and the actual service endpoint could be located at The Kubernetes metadata for a service does not capture the path part, making it hard to consume this service.

  • Service Type - Services use different protocols that clients need to speak in order to communicate with the service, some examples of service level protocols are SOAP, REST (Yes I know, technically REST isn’t a protocol but an architectural style). For service consumers it can be hard to tell what protocol is expected.

  • Service Description URL - To facilitate the consumption of the service by client, the location this document would be greatly helpful to the service consumer. In some cases the client side code can be generated from such a document. At the moment it is time consuming to find this document.

  • Service Description Type - A number of Definition Languages (DL) have been developed to describe the service. Some of examples are WSDL, WADL and Swagger. In order to consume a decription document it is good to know the type of DL used.

3. Proposal

3.1. Single endpoint info

Kubernetes allows the creation of Service Annotations. Here we propose the use of the following annotations

  • 'servicepath' - the path part of the service endpoint url. An example value could be 'cxfcdi',

  • 'protocol' - the protocol of the service. Example values can be 'SOAP' or 'REST',

  • 'descriptionpath' - the path part of the service description document’s endpoint. It is a pretty safe assumption that the service self documents. An example value for a swagger 2.0 document can be 'cxfcdi/swagger.json',

  • 'descriptiontype' - the type of Description Language used. Example values can be 'WSDL', 'WADL', 'SwaggerJSON', 'SwaggerYAML'.

The fragment below is taken from the service section of the kubernetes.json were these annotations are used

  "objects" : [ {
    "apiVersion" : "v1",
    "kind" : "Service",
    "metadata" : {
      "annotations" : {
        "protocol" : "REST",
        "servicepath" : "cxfcdi",
        "descriptionpath" : "cxfcdi/swagger.json",
        "descriptiontype" : "SwaggerJSON"

3.2. Multiple endpoint infos

There is one more use case we should consider which is that there can be multiple distinct services withing one service endpoint, for example and If this is the case we propose that you can name these different services by postfixing the annotation key with the name of the service.

  "objects" : [ {
    "apiVersion" : "v1",
    "kind" : "Service",
    "metadata" : {
      "annotations" : {
        "protocol.service1" : "REST",
        "servicepath.service1" : "service1",
        "descriptionpath.service1" : "service1/swagger.json",
        "descriptiontype.service1" : "SwaggerJSON"
        "protocol.service2" : "REST",
        "servicepath.service2" : "service2",
        "descriptionpath.service2" : "service2/swagger.json",
        "descriptiontype.service2" : "SwaggerJSON"

4. Example using the maven-fabric8-plugin

The maven fabric8 plugin supports defining service annotation properties in pom which then turn into Kubernetes service annotations. Each annotation simply needs to start with 'fabric8.annotations.service.'. The fragment below shows an example of its use


The example fragment is taken from the CXFCDI quickstart. Note that this information is used when this service is imported into the API Manager.

5. Conclusion

We’re proposing the use to Kubernetes Service Annotations to make it easier for service consumers to discover the actual service(s) on an endpoint. This includes information about the service path, protocol, description document and description type. Note we did not prefix the annotion keys with any 'domain/' as we hope that these annotations can be adopted as a standard Kubernetes annotation convention as every service developer runs into these issues.

About the author

Kurt Stam


comments powered by Disqus