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:
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.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
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.
[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
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.