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>`_.

At present, the 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.

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

- 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.11 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>`_