---
updatedAt: 2026-07-16T10:10:49.000Z
agentTools:
  projectIndex: https://developer.ixon.cloud/llms.txt
---

# Cloud Functions Architecture and Tooling

A deeper look at how Cloud Functions run, the tools that power them, and what happens between a caller's request and a function's response.

<Callout icon="📘" theme="info">
  ### New here?

  If you haven't already, start with **<Anchor target="_blank" href="doc:what-is-a-cloud-function">What is a Cloud Function?</Anchor>** for the high-level picture. This page goes one level deeper, into the runtime, the tooling, and the request lifecycle.
</Callout>

# Runtime architecture

A Cloud Function is hosted by the **Ingress** — the `ixoncdkingress` Python package, which performs the following actions:

1. It runs an **HTTP server**;
2. Routes **incoming calls** to the correct Python function;
3. **Injects** a `FunctionContext` object so your function has everything it needs to do its work: resources, configuration, an API client, and clients for Document Store and Object Storage.

# Local development vs. cloud deployment

The same Cloud Function code runs in two architecturally different environments. Knowing the differences helps you debug, configure, and deploy with confidence.

## Local development

When you run `make run`, the Makefile orchestrates the following:

1. **Sets up a Python virtual environment** in `./venv` if one doesn't already exist, using your installed Python 3.12+.
2. **Installs dependencies** from `requirements.txt` and `requirements-dev.txt` into the venv. Your function's runtime dependencies live in `requirements.txt`; development-only tools live in `requirements-dev.txt`.
3. **Starts a MongoDB Docker container** to provide a local Document Store. This is why Docker is a prerequisite — without it, Document Store calls will fail locally.
4. **Starts the Ingress** by running `python -m ixoncdkingress` with `CBC_PATH=./functions`. The Ingress listens on `http://127.0.0.1:8020/` and exposes the `functions/` directory as the module root for callable functions.
5. **Loads&#x20;**`context_values.yaml` so any config you define there is available locally via `context.config`.

The local Document Store **resets on every restart**. The Ingress also **auto-reloads** your function code on save, so you don't need to restart the server to test small edits.

## Cloud deployment

In IXON Cloud, the architecture is the same in shape but the moving parts are managed for you:

* The **Ingress runs in IXON Cloud's infrastructure**, not on your machine.
* The **Document Store** uses persistent, per-function MongoDB collections.
* **Configuration** comes from the encrypted Settings stored under **Admin > Apps > (your function) > More options > Settings**. `context_values.yaml` is *not* used in the cloud.
* **API access scopes** are enforced. A deployed Cloud Function cannot call IXON API resources by default — you must grant scopes under **Studio > Cloud Functions > (your function) > API Access**.
* **Logs** are captured and can be downloaded under **Studio > Cloud Functions > (your function) > More options > Download logs**.

<Callout icon="❗️" theme="error">
  ### Configuration parity

  Use the **same configuration schema locally and in the cloud**, or your function may behave differently in production than in development. Treat `context_values.yaml` as a stand-in for the encrypted Settings, not a separate concept.
</Callout>

# Tooling

| Tool               | Role                                                                                                                                                                                                                   |
| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Python 3.12.x+     | The language Cloud Functions are written in. **Earlier versions are not supported.**                                                                                                                                   |
| `ixoncdkingress`   | The Python package that runs the function host, builds the FunctionContext, provides the Document Store client and more. To be compatible with `python 3.12.x` this package must be `ixoncdkingress v1.x.x` or higher. |
| Docker             | Used during local development to run a MongoDB container for the local Document Store.                                                                                                                                 |
| `Makefile`         | Manages `venv` setup, dependency installation, and starting the Ingress.**&#x20;Do not modify it** — it is an integrated part of the workspace.                                                                        |
| `venv`             | Isolates your function's Python dependencies from the system Python. Created automatically by `make run`.                                                                                                              |
| `requirements.txt` | Your function's runtime dependencies.                                                                                                                                                                                  |

# The FunctionContext

Every exposed function receives a `FunctionContext` as its first argument. The FunctionContext is the single entry point to everything your function needs at runtime: who's calling, what configuration is in effect, and how to talk to data stores or APIs.

```python
from ixoncdkingress.function.context import FunctionContext

@FunctionContext.expose
def my_function(context: FunctionContext, **kwargs):
    # context.user, context.company, context.agent, context.asset
    # context.config
    # context.api_client
    # context.document_db_client
    ...
```

Only functions decorated with `@FunctionContext.expose` are callable from outside the workspace — undecorated helpers stay private.

For the full surface area of `FunctionContext`, see the **<Anchor target="_blank" href="doc:context-api">SDK reference</Anchor>**.

# Request lifecycle

Let's take the `greet` function found in the `backend-component-workspace` as an example. Here's what happens between a caller pressing a button and your function returning a result:

1. **The caller invokes the function.** A UI Component calls `client.call('functions.example.greet', {...})`; a backend caller invokes the equivalent endpoint via the IXON API.
2. **IXON Cloud authenticates the caller** and verifies they are allowed to call this function in this context.
3. **The Ingress builds the FunctionContext.** Resources are populated based on where the caller is: a Device Page contributes `context.agent`; an Asset Page contributes `context.asset`; the active company always contributes `context.company`. Configuration is loaded from the encrypted Settings.
4. **The Ingress dispatches to your code.** The dotted path `functions.example.greet` resolves to the `greet` function in `functions/example.py`.
5. **Your function executes.** It may read or write to the Document Store, call the IXON API, call an external service, or simply transform its inputs.
6. **The return value is serialised to JSON** and sent back to the caller. Exceptions are caught, logged, and returned as errors.

# Versioning

A Cloud Function in IXON Cloud has a current version. When you deploy a new version, subsequent calls use the new code. Downloadable logs cover the **current version only**, for the last 48 hours of calls.