1. This post is now old
The final proposal got accepted, please see:
2. Original proposal
The original proposal can be found at https://kurtstam.github.io/2015/09/22/Proposal-for-Kubernetes-Service-Annotations.html. This updated proposal incorporates feedback from https://github.com/kubernetes/kubernetes/issues/14828.
3. 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.
4. Proposal
Kubernetes allows the creation of Service Annotations. Here we propose the use of the following annotations
-
'apiman.io/servicepath' - the path part of the service endpoint url. An example value could be 'cxfcdi',
-
'apiman.io/servicetype' - the protocol of the service. Example values can be 'SOAP' or 'REST',
-
'apiman.io/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',
-
'apiman.io/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" : {
"apiman.io/servicetype" : "REST",
"apiman.io/servicepath" : "cxfcdi",
"apiman.io/descriptionpath" : "cxfcdi/swagger.json",
"apiman.io/descriptiontype" : "SwaggerJSON"
},
...
5. 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.apiman.io.servicePath>cxfcdi</fabric8.annotations.service..apiman.io.servicePath> <fabric8.annotations.service.apiman.io.serviceType>REST</fabric8.annotations.service..apiman.io.serviceType> <fabric8.annotations.service.apiman.io.descriptionPath>cxfcdi/swagger.json</fabric8.annotations.apiman.io.service.descriptionPath> <fabric8.annotations.service.apiman.io.descriptionType>SwaggerJSON</fabric8.annotations.service.apiman.io.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.
6. 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 that we incorporated feedback from standard Kubernetes annotation convention and that we hope this convention will be standardized by Kubernetes as every service developer runs into these issues.