Shulou(Shulou.com)06/01 Report--

This article is about how to understand the Kubernetes OpenAPI interface. The editor thinks it is very practical, so I share it with you. I hope you can get something after reading this article. Let's take a look at it.

Kubernetes automatically generates interface documents that conform to the OpenAPI specification according to the code.

Query OpenAPI documents

Kube-apiserver provides / openapi/v2 interface to query the API document, which conforms to the OpenAPI 2.0 specification by the interface name. As follows:

[root@ecs-d8b6 kubernetes] # curl localhost:8080/openapi/v2 {"swagger": "2.0", "info": {"title": "Kubernetes", "version": "v1.19.0"},...}

This interface returns the complete API document, which is limited to a small amount of output.

This API returns files in JSON format by default. In addition to supporting the JSON format, the protocol buffer format is also supported. The client can specify the required format in the Accept field of the HTTP header. The Accept field values application/json and application/com.github.proto-openapi.spec.v2@v1.0+protobuf correspond to two file formats respectively.

Interface evolution

The / openapi/v2 interface was supported by Kubernetes as early as version 1.10, and before version 1.14, Kubernetes provided other interfaces to provide multiple versions of the specification as well as API documents in various formats.

For example, query the interface for kube-apiserver in Kubernetes version 1.13, as follows:

[root@ecs-d8b6 kubernetes] # curl localhost:8080/ {"paths": ["/ api", "/ api/v1", "/ apis", "/ apis/",... "/ openapi/v2", "/ swagger-2.0.0.json", "/ swagger-2.0.0.pb-v1", "/ swagger-2.0.0.pb-v1.gz", "/ swagger.json" "/ swaggerapi",...]}

/ swagger-2.0.0.json: returns the API document in JSON format (Swagger 2.0 specification)

/ swagger-2.0.0.pb-v1: returns the API document in protocol buffer format (Swagger 2.0 specification)

/ swagger-2.0.0.pb-v1.gz: same as / swagger-2.0.0.pb-v1, but returns the compressed API document

/ swagger.json: same as / swagger-2.0.0.json

/ swaggerapi: returns the API document in JSON format (Swagger v1.2).

Kubernetes unifies all of these interfaces into the / openapi/v2 interface in version 1.14.

Design thinking

After introducing the previous interfaces, readers are asked to think about the following questions before reading:

Why support protocol buffer format?

Why should many interfaces be normalized to the / openapi/v2 interface?

Why protocol buffer is supported

One advantage of using the OpenAPI specification to describe API is that it is convenient for programs to process, and programs can verify request information against API documents.

For example, kubectl validates each request against OpenAPI documents. In earlier versions of Kubernetes, kube-apiserver did not support eTag, so kubectl must obtain a complete API document from kube-apiserver each time when it initiates a request to kube-apiserver. At that time, the API document of Kubernetes has grown to the size of 1.5MB, and each time kubectl downloads this document, it consumes more time, which seriously affects the performance and experience of kubectl.

In order to improve the performance and experience of kubectl, kube-apiserver as a HTTP server can support eTag, so that kubectl, as a HTTP client, can cache API documents locally. However, kube-apiserver support for eTag is a huge workload and will not be easy to implement in the short term, because almost all API needs to be modified at the same time.

Another solution is to reduce the size of the API document. As a data exchange format, protocol buffer is more efficient than JSON format. According to the test records at that time, using protocol buffer format can reduce the volume of API documents by 44%, and the document download time will naturally decrease. In addition, because the deserialization performance of protocol buffer is also better than that of JSON, kubectl not only reduces the document download time, but also increases the deserialization time by using protocol buffer format interface documents.

According to OpenAPI specification, interface description file in JSON format is the first choice. The main driving force of Kubernetes supporting interface document in protocol buffer format is to solve the performance problem of kubectl.

Why should the interface be normalized?

The OpenAPI-related interfaces in Kubernetes version 1.13 are shown earlier, from which you can clearly feel messy. It is convenient for humans to read, but it is very unfriendly to the program, for example, the program cannot query the list of versions of the OpenAPI specification supported by Kubernetes.

For this reason, Kubernetes integrates all OpenAPI-related interfaces into the / openapi interface, and the complete interface design is as follows:

/ openapi: used to query the list of supported OpenAPI specification versions, such as v2, v3, etc.

/ openapi/v2: corresponding to OpenAPI v2

/ openapi/v3: corresponding to OpenAPI v3

The format of the document is no longer reflected in the interface, but is specified by the client through the Accept field in the HTTP request header.

This interface design is not only clear, but also has good extensibility, and can easily support multiple versions of the OpenAPI specification.

As of v1.18.0, Kubernetes has only implemented the / openapi/v2 interface, but it clearly points out the direction of future evolution.

The above is how to understand the Kubernetes OpenAPI interface, the editor believes that there are some knowledge points that we may see or use in our daily work. I hope you can learn more from this article. For more details, please follow the industry information channel.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.