Luna services requirements
--------------------------

There are several requirements for luna-services for lambda work.

General requirement is *Luna-Configurator* service, see `service configuration <./config.html>`_ for details.

It is also required `luna_lambda` enabled in *ADDITIONAL_SERVICES_USAGE* setting.

There are several lambda types, including *standalone* lambda which does not require any other service by default,
but lambdas of any other types can have more requirements, see requirements for specific `lambda` from
`lambda types <./lambda_types.html>`_ for specific requirements.

S3 storage requirements
-----------------------

The `luna-lambda` service requires s3 bucket for storing archives with lambda.

.. note::
    It is not required to use amazon s3 service, the `minio object storage <https://min.io/>`_ also fits the requirements.

Read/write access is required for the `specified bucket <./config.html#configuration-requirements>`_.

.. warning::
    At present, there is no mechanism of s3 bucket garbage collection, but be careful removing lambdas data.
    The lambda `update mechanism <./lambda_updates.html>`_ may use those data.

The s3 storage is determined by *S3* setting of `luna-lambda`. See `service configuration <./config.html>`_ for configuration details.


Kubernetes cluster requirements
-------------------------------

The `luna-lambda` service requires some access rights in kubernetes cluster whose provided by
`specified credentials <./config.html#configuration-requirements>`_.

Service provides a kubernetes mechanism for isolating groups of resources within a single cluster. This mechanism calls `namespace`.

Namespace has several restrictions:
    - Contain between 2 and 63 characters.
    - Contain only lowercase alphanumeric characters or `-`.
    - Start with an alphanumeric character.
    - End with an alphanumeric character.
    - Don't start with `kube-` because it's reserved kubernetes name.

For more information about namespace see `kubernetes documentation <https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces>`_.

By default service uses `default` namespace of kubernetes cluster, so it is required to grant
creation/monitoring/deletion rights (including service/deployment/pod creation, deletion).
It is recommended to ask kubernetes administrator to grant access for the above.

The simplest way to allow lambda creation and management is to execute next command for kubernetes:

.. code-block:: sh

    kubectl create clusterrolebinding permissive-binding --clusterrole=cluster-admin --user=admin --user=kubelet --group=system:serviceaccounts

.. warning::
    It is highly not recommended to use similar decisions in production.
    It is highly recommended that you negotiate with your Kubernetes cluster administrator and use the security policy for your Kubernetes cluster as required.

.. note::
    At present, there is no possibility to allow lambda to use mount directories or replicate to different nodes.
    These possibilities might be added in future releases.

Kubernetes cluster - GPU usage
------------------------------

It is possible to create `lambda` which can use GPU resources (by using `enable_gpu` from `parameters` section,
see `lambda creation request <./api.html#tag/createLambda>`_).

Lambdas supports only nvidia GPUs. For more information about GPU usage see
`kubernetes documentation <https://kubernetes.io/docs/tasks/manage-gpus/scheduling-gpus/>`_.

If only one GPU is available but more needed, it is possible to enable GPU sharing,
see `NVIDIA GPU sharing <https://docs.nvidia.com/datacenter/cloud-native/gpu-operator/latest/gpu-sharing.html>`_
for information.

.. note::
    The `luna-lambda` does not manage cluster resources (including) gpu allocation, it manages by kubernetes administrator.

Docker registry requirements
----------------------------

The `luna-lambda` service requires docker registry for lambda image storage.
The registry must be specified using `LAMBDA_REGISTRY`, see `configurator requirements <./config.html#configuration-requirements>`_
for details.

Those registry also must contain *base lambda* images provided by VL:
    - image named `lpa-lambda-base` for all lambdas without Luna SDK support
    - image name `lpa-lambda-base-fsdk` for lambdas with Luna SDK support (`for example <./handlers.html#id10>`_)

If those registry is insecure registry, it is also required to add it to *LAMBDA_INSECURE_REGISTRIES* setting.

The registry storage is determined by *LAMBDA_REGISTRY* setting of `luna-lambda`. See `service configuration <./config.html>`_ for configuration details.

Lambda - base image requirements
--------------------------------

The `luna-lambda` service creates each `lambda` based on one of two base docker images: `lpa-lambda-base` or `lpa-lambda-base-fsdk`,
but there is a possibility to create custom base image for lambda.

The `lpa-lambda-base` image intended for most lambdas and provides basic functionality for lambda.

The `lpa-lambda-base-fsdk` image in addition to base image functionality provides functionality for FSDK usage by lambda.

The custom base lambda image is intended for complex lambdas for which not enough opportunities of `lpa-lambda-base` or `lpa-lambda-base-fsdk`
base images (For example, multi-stage docker container building, including large libraries or data into docker container).

There are several requirements for custom base lambda image:

- It must use `lpa-lambda-base` or `lpa-lambda-base-fsdk` as base image

- It must not remove or modify any installed dependencies (`python3`, `gcc` and so on)

- It must located at the same registry as other base lambda images

To use custom lambda base image it requires to specify it's *name* and *tag* for
`lambda creation request <./_static/api.html#operation/createLambda>`_ or
`put lambda request <./_static/api.html#operation/putLambda>`_.


Lambda - Archive requirements
-----------------------------

Lambda creation is initiated by `lambda creation request <./_static/api.html#operation/createLambda>`_ which is required
archive which has the following requirements:

- zip archive without a password

- minimum required content is a `lambda_main.py` file (see `python code requirements <#lambda-general-python-code-requirements>`_ for details)

- it is possible to add a `requirements.txt` file - all requirements from the file will be included in the lambda docker image

  example:

  .. code-block:: text
    :caption: requirements.txt

      numpy==1.24.2

- It is possible to add additional directories to be used as static routes. They should be placed in the `static` directory in the root of the archive, and their names should contain only upper and lower case letters, numbers, and the characters `-`, `_`.

  Routes within the static directory are mapped directly to the corresponding paths of the lambda. The structure within the static directory is preserved, meaning that a file placed inside a subdirectory of static will be accessible under the same relative path from the lambda.

  This functionality is supported for all types of Lambda.

  See `standalone lambda with static route <./standalone.html#id13>`_ example.

- it is possible to add additional command to docker container building stage.
  See `create lambda <./_static/api.html#operation/createLambda>`_ for api description.

  Keep in mind that lambda use CentOS 8 docker image as basic image while working with system dependencies.

  For example to use `pillow` library in lambda make the following steps:

    - add `pillow` to requirements.txt
    - add the following list of command to `user_docker_commands` (in lambda creation request)

      .. code-block:: text

         RUN yum install -y epel-release
         RUN yum install -y libjpeg-turbo-devel

    - perform all other standard actions to create lamdba

    .. warning::
        It is not recommended to perform actions which are not required root access using root user.

        To switch between users, use `USER root` and `USER luna` commands.

        For more information about docker build commands see `dockerfile reference <https://docs.docker.com/engine/reference/builder/>`_

    .. warning::
         It is not possible to perfectly validate additional user specified docker commands so use it on your own risk

- it is possible to run several lambda process at the same times.
  See `create lambda <./_static/api.html#operation/createLambda>`_ for api description.

  - add the count of lambda process to `workers` between 1 and 32 (in lambda creation request). By default its 1.

- there are several files and folders whose addition to archive will take no effect, because these modules will be automatically
  replaced during lambda creation:

  .. code-block::
     :caption: (from the root archive folder)

      ├──run.py
      └──luna_lambda_tools

- you can add custom documentation to the zip archive with the lambda. It's recommended to be used with standalone lambdas.
  Documentation must be placed in *docs* directory in HTML and YAML formats. Files must be named as *lambda.yml* and *lambda.html*.
  Both HTML and YAML files are required.

  .. code-block::
     :caption: (example zip structure)

      lambda.zip
      ├── docs
      │  ├── lambda.html
      │  └── lambda.yml
      └── lambda_main.py


Lambda - General python code requirements
-----------------------------------------

General requirements:

- Python 3.12 or higher.

- The luna-lambda-tools library is required for development. Available in `VL pypi <http://pypi.visionlabs.ru/>`_.

  Example of `luna-lambda-tools` installation using pip:

  .. code-block:: bash

      pip install --trusted-host pypi.visionlabs.ru --extra-index-url http://pypi.visionlabs.ru/root/public/+simple luna-lambda-tools

- The lambda entry point is the `main` function in `lambda_main.py` file. It must:
    - represents an asynchronous function
    - takes one argument - `request: StandaloneLambdaRequest` (for `standalone` lambda) / `request: HandlersLambdaRequest` (for `handlers` lambda)
      (More information about lambda types and differences of *handlers* and others available at `lambda types description <./lambda_types.html>`_.)
    - returns dictionary

  example:

    .. code-block:: python

        from luna_lambda_tools import StandaloneLambdaRequest

        async def main(request: StandaloneLambdaRequest) -> dict:
            result = request.json["data"]
            return {"result": result}

More possibilities described at `lambda development <./lambdas.html#development>`_