1. Updated version
There is an updated version of this proposal, see https://kurtstam.github.io/2015/10/15/Update-1-Proposal-for-Kubernetes-Service-Annotations.html
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. http://172.100.1.52/. There are cases where this is not possible and the actual service endpoint could be located at http://172.100.1.52/cxfcdi. 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 http://172.100.1.52/service1 and http://172.100.1.52/service2. 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
... <fabric8.annotations.service.servicePath>cxfcdi</fabric8.annotations.service.servicePath> <fabric8.annotations.service.protocol>REST</fabric8.annotations.service.protocol> <fabric8.annotations.service.descriptionPath>cxfcdi/swagger.json</fabric8.annotations.service.descriptionPath> <fabric8.annotations.service.descriptionType>SwaggerJSON</fabric8.annotations.service.descriptionType> ...
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.