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 inlower-constraints.txt
changed to lower version (this is highly unlikely). In this caseprotobuf
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 thegRPC plugin
for it. The most simple way to get them is to installgrpcio-tools
:(venv) [kuryr-kubernetes]$ pip install grpcio-tools==1.19
Note
We’re installing specific version of
grpcio-tools
to get specific version ofprotoc
compiler. The version ofprotoc
compiler should be equal to theprotobuf
package version inlower-constraints.txt
. This is because olderprotobuf
might be not able to use files generated by newer compiler. In case you need to use more recent compiler, you need updaterequirements.txt
andlower-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
andapi_pb2.py
:(venv) [kuryr-kubernetes]$ python -m grpc_tools.protoc -I./ \ --python_out=. --grpc_python_out=. \ kuryr_kubernetes/pod_resources/api.proto