Roman Dobosz fd440fcdcb Explicitly use code-block.

In this patch we convert preformatted directive (double colon at the end
of line) to code-block sphinx directive. Also, fixed formatting for
existing code-block directives, and changes restructuredtext code
directive into sphinx code-block.

Change-Id: I9db48fbb169263e3bf66eacca7d9bce6c355739f

2019-11-13 12:49:43 +01:00

4.5 KiB

Raw Blame History

HowTo Update PodResources gRPC API

Purpose

The purpose of this document is to describe how to update gRPC API files in kuryr-kubernetes repository in case of upgrading to a new version of Kubernetes PodResources API. These files are api_pb2_grpc.py, api_pb2.py and api.proto from kuryr_kubernetes/pod_resources/ directory.

api.proto is a gRPC API definition file generated from the kubernetes/pkg/kubelet/apis/podresources/<version>/api.proto of the Kubernetes source tree.

api_pb2_grpc.py and api_pb2.py are python bindings for gRPC API.

Note

There are only 2 reasons for update:

Kubernetes released new version of PodResources API and the old one is no longer supported. In this case, without update, we'll not be able to use PodResources service.
protobuf version in lower-constraints.txt changed to lower version (this is highly unlikely). In this case protobuf could fail to use our python bindings.

Automated update

contrib/regenerate_pod_resources_api.sh script could be used to re-generate PodResources gRPC API files. By default, this script will download v1alpha1 version of api.proto file from the Kubernetes GitHub repo and create required kuryr-kubernetes files from it:

[kuryr-kubernetes]$ ./contrib/regenerate_pod_resources_api.sh

Alternatively, path to api.proto file could be specified in KUBERNETES_API_PROTO environment variable:

$ export KUBERNETES_API_PROTO=/path/to/api.proto

Define API_VERSION environment variable to use specific version of api.proto from the Kubernetes GitHub:

$ export API_VERSION=v1alpha1

Manual update steps

Preparing the new api.proto

Copy the api.proto from K8s sources to kuryr_kubernetes/pod_resources/ and remove all the lines that contains gogoproto since this is unwanted dependency that is not needed for python bindings:

$ sed '/gogoproto/d' \
  ../kubernetes/pkg/kubelet/apis/podresources/<version>/api.proto \
  > kuryr_kubernetes/pod_resources/api.proto

Don't forget to update the file header that should point to the original api.proto and to this reference document:

// Generated from kubernetes/pkg/kubelet/apis/podresources/<version>/api.proto
// To regenerate api.proto, api_pb2.py and api_pb2_grpc.py follow instructions
// from doc/source/devref/updating_pod_resources_api.rst.

Generating the python bindings

(Optional) Create the python virtual environment:

[kuryr-kubernetes]$ python3 -m venv venv
[kuryr-kubernetes]$ . ./venv/bin/activate

To generate python bindings we need a protoc compiler and the gRPC plugin for it. The most simple way to get them is to install grpcio-tools:
```
(venv) [kuryr-kubernetes]$ pip install grpcio-tools==1.19
```
Note

We're installing specific version of grpcio-tools to get specific version of protoc compiler. The version of protoc compiler should be equal to the protobuf package version in lower-constraints.txt. This is because older protobuf might be not able to use files generated by newer compiler. In case you need to use more recent compiler, you need update requirements.txt and lower-constraints.txt accordingly.

To check version of compiler installed with grpcio-tools use:
```
(venv) [kuryr-kubernetes]$ python -m grpc_tools.protoc --version
libprotoc 3.6.1
```

Following command will generate api_pb2_grpc.py and api_pb2.py:

(venv) [kuryr-kubernetes]$ python -m grpc_tools.protoc -I./               \
    --python_out=. --grpc_python_out=.      \
    kuryr_kubernetes/pod_resources/api.proto

4.5 KiB Raw Blame History