..
      This work is licensed under a Creative Commons Attribution 3.0 Unported
      License.

      http://creativecommons.org/licenses/by/3.0/legalcode

      Convention for heading levels in Neutron devref:
      =======  Heading 0 (reserved for the title in a document)
      -------  Heading 1
      ~~~~~~~  Heading 2
      +++++++  Heading 3
      '''''''  Heading 4
      (Avoid deeper levels because they do not render well.)

==================================
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:

.. code-block:: console

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

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

.. code-block:: console

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

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

.. code-block:: console

   $ 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:

.. code-block:: console

   $ 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:

.. code-block:: console

   [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``:

  .. code-block:: console

     (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:

     .. code-block:: console

        (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``:

  .. code-block:: console

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