airflow.providers.modal.hooks.modal¶
Hook that resolves a modal connection to an authenticated Modal client.
Classes¶
Hook for Modal. |
Module Contents¶
- class airflow.providers.modal.hooks.modal.ModalHook(modal_conn_id=default_conn_name, *args, **kwargs)[source]¶
Bases:
airflow.providers.common.compat.sdk.BaseHookHook for Modal.
Turns an Airflow connection of type
modalinto amodal.Client, so every piece of Airflow code that talks to Modal (operators, the Common AI sandbox toolset backend, a future executor) reads credentials the same way instead of each one reaching for the worker’s environment.Connection fields:
Login: Modal token id (
ak-...).Password: Modal token secret (
as-...).Extra
environment(optional): Modal environment name to scope app lookups and sandboxes to. When unset, the Modal SDK resolves it fromMODAL_ENVIRONMENTor the active profile in~/.modal.toml.
Credential precedence:
Token id and secret on the connection: the client is built from exactly those.
A connection with neither token field set, or no connection at all for the default connection id: the Modal SDK’s own resolution applies (
MODAL_TOKEN_ID/MODAL_TOKEN_SECRET, then~/.modal.toml). This keeps a worker that already hasmodal token newrun on it working without any Airflow configuration.Exactly one of the two token fields set: an error. A half-filled connection is a misconfiguration, and silently falling back to ambient credentials would hide it.
Workspace is not a connection field because Modal derives it from the token itself.
- Parameters:
modal_conn_id (str | None) – Modal connection id. Pass
Noneto skip connection lookup entirely and use ambient credentials.
- property credentials: tuple[str, str] | None[source]¶
Token id and secret from the connection, or
Noneto defer to the Modal SDK.
- property environment_name: str | None[source]¶
Modal environment from the connection extra, or
Noneto defer to the Modal SDK.
- property client: modal.Client[source]¶
The Modal client, built once per hook instance and per process.
A client owns a gRPC transport, and the Modal SDK documents its recovery of a client inherited across
os.fork()as best-effort, recommending a fresh client instead. So the cache is keyed on the PID: a hook whose client was populated before a fork (for example one held by an executor or a long-lived plugin) rebuilds it on first use in the child instead of reusing the parent’s transport.
- property client_kwargs: dict[str, Any][source]¶
Keyword arguments that route a Modal SDK call through this connection’s credentials.
For calls that also take
environment_name(Function.from_name,Cls.from_name,Secret.from_name,Volume.from_name,App.lookup) prefer the matching hook method, which applies the connection’s environment as well. Use this for calls that only take a client, such asmodal.Sandbox.list(**hook.client_kwargs).
- lookup_app(name, *, create_if_missing=False)[source]¶
Look up a Modal app by name in the connection’s environment.
- get_function(app_name, name, *, version=None)[source]¶
Return a handle to a deployed Modal function in the connection’s environment.
Call
.remote(...),.spawn(...)or.map(...)on the result as with any Modal function handle.
- get_cls(app_name, name, *, version=None)[source]¶
Return a handle to a deployed Modal class in the connection’s environment.
- get_secret(name, *, required_keys=None)[source]¶
Return a named Modal secret from the connection’s environment.
- get_volume(name, *, create_if_missing=False)[source]¶
Return a named Modal volume from the connection’s environment.
- create_sandbox(*entrypoint, app_name, create_app_if_missing=False, **sandbox_kwargs)[source]¶
Create a Modal sandbox under a named app, through this connection.
The app is resolved with
lookup_app(), so the sandbox lands in the connection’s environment (Modal derives a sandbox’s environment from its app). Remaining keyword arguments go tomodal.Sandbox.createunchanged:image,gpu,cpu,memory,timeout,secrets,volumesand so on.
- get_sandbox(sandbox_id)[source]¶
Reattach to an existing sandbox by id, through this connection.
- Parameters:
sandbox_id (str) – The
sb-...id returned bySandbox.object_id.
- test_connection()[source]¶
Authenticate against Modal and report the outcome for the connection form.
Explicit credentials are checked with
modal.Client.verify(), which opens a throwaway client, sends oneClientHelloand closes it again, so repeated tests from the API server do not accumulate transports. The ambient path checks the SDK’s sharedfrom_envclient, which the hook does not own and therefore does not close.