Custom deployment manifest
==========================
Sometimes the built-in pod template isn't enough — you need a sidecar container, a volume
shared between lambdas running on the same node, an
extra annotation for your own tooling, or similar. The `LAMBDA_DEPLOYMENT_SETTINGS` setting 
lets you supply your own Kubernetes ``Deployment`` manifest, per namespace, and luna-lambda
deploys lambdas from *that* instead of its own template.

How it works
------------

- Every namespace entry in `LAMBDA_DEPLOYMENT_SETTINGS` (`default_namespace`, and each entry
  of `allowed_namespaces`) has a `deployment_manifest` field holding the manifest for lambdas
  in that namespace, as a JSON string.
- `default_namespace.deployment_manifest` is always set — out of the box it's exactly the
  manifest luna-lambda has always deployed lambdas from, so nothing changes until you edit it.
  It's also the fallback: any namespace in `allowed_namespaces` that leaves its own
  `deployment_manifest` as `null` uses this one.
- To customize a namespace, write its `deployment_manifest` as a JSON string via the
  configurator's settings API. No restart is needed — luna-lambda picks up the change on its
  next config reload.

Getting started
----------------

1. Start from the default manifest (fetch it from the configurator, or copy the example
   below) rather than writing one from scratch.
2. Add whatever you need — a volume/mount, a sidecar, etc. — leaving
   the existing placeholders in place.
3. Write it back as the `deployment_manifest` for the namespace you want it to apply to.
4. Create a lambda in that namespace and confirm it comes up as expected.

.. code-block:: json

    {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "{APP_NAME}"
      },
      "spec": {
        "replicas": "{APP_REPLICAS}",
        "selector": {"matchLabels": {"app": "{APP_NAME}"}},
        "template": {
          "metadata": {"labels": {"app": "{APP_NAME}"}},
          "spec": {
            "containers": [
              {
                "name": "{APP_NAME}",
                "image": "{IMAGE}",
                "resources": {
                  "requests": {"memory": "{RAM_REQUEST}G", "cpu": "{CPU_REQUEST}m"},
                  "limits": {"memory": "{RAM_LIMIT}G", "cpu": "{CPU_LIMIT}m"}
                },
                "args": ["{LAUNCH_COMMAND}"]
              }
            ]
          }
        }
      }
    }

Placeholders
------------

luna-lambda fills in a few placeholders when it deploys from your manifest — the ones shown
above (``{APP_NAME}``, ``{IMAGE}``, ``{APP_REPLICAS}``, ``{CPU_LIMIT}``/``{RAM_LIMIT}``/
``{CPU_REQUEST}``/``{RAM_REQUEST}``, ``{LAUNCH_COMMAND}``), ``{LAMBDA_KIND}``, ``{CONFIGURATOR_ADDRESS}``
and the startup-probe timing placeholders. Keep the ones you're not deliberately changing.

Configurator address
--------------------

The `LAMBDA_DEPLOYMENT_SETTINGS` namespace sections has optional `luna_config_address` field which address of
configurator service will be used by each lambda to pull settings from. If such address does not specified
for namespace where lambda is placed the default one will be used (`http://configurator:5070/1`).
The `allowed_namespaces` section also may contains optional `luna_config_address` field.

.. note::

    The `luna_config_address` does not make any effect for previously created lambdas.

.. warning::

    If you remove any of the resource placeholders (``{CPU_LIMIT}``/``{RAM_LIMIT}``/
    ``{CPU_REQUEST}``/``{RAM_REQUEST}``), e.g. by hardcoding the values, the lambda get request
    still returns the ``deploy_parameters.resources`` that were sent in the lambda creation
    request — not the real limits/requests set via your custom manifest. Check the actual
    values on the deployment in your cluster instead.

luna-lambda also writes a few values into the manifest after substitution, regardless of what
you wrote: the node selector and
required environment variables. If you've restructured or removed the section one of these
would normally go into (e.g. dropped ``resources.limits`` entirely), luna-lambda doesn't fail
the deployment — it just skips that one injection, so double check the result if you do this.

Limitations
-----------

- There's no template fallback beyond `default_namespace.deployment_manifest` — don't clear it.
- `deployment_manifest` must be valid JSON. This is checked at service startup and on every
  config reload; invalid JSON stops the service from starting.
- Beyond the placeholder/value substitution described above, your manifest is used exactly as
  provided — luna-lambda doesn't otherwise validate it against your cluster. A manifest that's
  structurally fine but wrong for your cluster (bad resource requests, a volume that doesn't
  exist, ...) will surface as a failed pod, not a rejected setting.