YAML specification#

This page outlines the specification for valid Executor YAML files.

Such YAML configurations can be used to generate a Executor object via load_config().

To generate a YAML configuration from a Flow Python object, use save_config().

YAML completion in IDE#

We provide a JSON Schema for your IDE to enable code completion, syntax validation, members listing and displaying help text. Here is a video tutorial to walk you through the setup.

PyCharm users#

  1. Click menu Preferences -> JSON Schema mappings;

  2. Add a new schema, in the Schema File or URL write https://api.jina.ai/schemas/latest.json; select JSON Schema Version 7;

  3. Add a file path pattern and link it to *.jaml or *.jina.yml or any suffix you commonly used for Jina Flow’s YAML.

VSCode users#

  1. Install the extension: YAML Language Support by Red Hat;

  2. In IDE-level settings.json add:

"yaml.schemas": {
    "https://api.jina.ai/schemas/latest.json": ["/*.jina.yml", "/*.jaml"],
}

You can bind Schema to any file suffix you commonly used for Jina Flow’s YAML.

Example YAML#

The following constitutes an example Flow YAML:

jtype: Flow
version: '1'
with:
  protocol: http
executors:
# inline Executor YAML
- name: firstexec
  uses:
    jtype: MyExec
    py_modules:
      - executor.py
# reference to Executor YAML
- name: secondexec
  uses: indexer.yml
  workspace: /home/my/workspace
# reference to Executor Python class
- name: thirdexec
  uses: CustomExec  # located in executor.py

Fields#

jtype#

String that is always set to “Flow”, indicating the corresponding Python class.

version#

String indicating the version of the Flow.

with#

Keyword arguments passed to Flow __init__() method. You can set Flow-specific arguments and Gateway-specific arguments here:

Flow arguments#

Name

Description

Type

Default

name

The name of this object.

This will be used in the following places:
- how you refer to this object in Python/YAML/CLI
- visualization
- log message header
- …

When not given, then the default naming strategy will apply.

string

None

workspace

The working directory for any IO operations in this object. If not set, then derive from its parent workspace.

string

None

log_config

The YAML config of the logger used in this object.

string

default

quiet

If set, then no log will be emitted from this object.

boolean

False

quiet_error

If set, then exception stack information will not be added to the log

boolean

False

uses

The YAML path represents a flow. It can be either a local file path or a URL.

string

None

env

The map of environment variables that are available inside runtime

object

None

inspect

The strategy on those inspect deployments in the flow.

If REMOVE is given then all inspect deployments are removed when building the flow.

string

COLLECT

Gateway arguments#

Name

Description

Type

Default

name

The name of this object.

This will be used in the following places:
- how you refer to this object in Python/YAML/CLI
- visualization
- log message header
- …

When not given, then the default naming strategy will apply.

string

gateway

workspace

The working directory for any IO operations in this object. If not set, then derive from its parent workspace.

string

None

log_config

The YAML config of the logger used in this object.

string

default

quiet

If set, then no log will be emitted from this object.

boolean

False

quiet_error

If set, then exception stack information will not be added to the log

boolean

False

timeout_ctrl

The timeout in milliseconds of the control request, -1 for waiting forever

number

60

polling

The polling strategy of the Deployment and its endpoints (when shards>1).
Can be defined for all endpoints of a Deployment or by endpoint.
Define per Deployment:
- ANY: only one (whoever is idle) Pod polls the message
- ALL: all Pods poll the message (like a broadcast)
Define per Endpoint:
JSON dict, {endpoint: PollingType}
{‘/custom’: ‘ALL’, ‘/search’: ‘ANY’, ‘*’: ‘ANY’}

string

ANY

uses

The config of the executor, it could be one of the followings:
* an Executor YAML file (.yml, .yaml, .jaml)
* a Jina Hub Executor (must start with jinahub:// or jinahub+docker://)
* a docker image (must start with docker://)
* the string literal of a YAML config (must start with ! or jtype: )
* the string literal of a JSON config

When use it under Python, one can use the following values additionally:
- a Python dict that represents the config
- a text file stream has .read() interface

string

BaseExecutor

uses_with

Dictionary of keyword arguments that will override the with configuration in uses

object

None

uses_metas

Dictionary of keyword arguments that will override the metas configuration in uses

object

None

uses_requests

Dictionary of keyword arguments that will override the requests configuration in uses

object

None

py_modules

The customized python modules need to be imported before loading the executor

Note that the recommended way is to only import a single module - a simple python file, if your
executor can be defined in a single file, or an __init__.py file if you have multiple files,
which should be structured as a python package. For more details, please see the
Executor cookbook <https://docs.jina.ai/fundamentals/executor/executor-files/>__

array

None

port

The port for input data to bind to, default is a random port between [49152, 65535]

number

random in [49152, 65535]

host_in

The host address for binding to, by default it is 0.0.0.0

string

0.0.0.0

native

If set, only native Executors is allowed, and the Executor is always run inside WorkerRuntime.

boolean

False

output_array_type

The type of array tensor and embedding will be serialized to.

Supports the same types as docarray.to_protobuf(.., ndarray_type=...), which can be found
here <https://docarray.jina.ai/fundamentals/document/serialization/#from-to-protobuf>.
Defaults to retaining whatever type is returned by the Executor.

string

None

prefetch

Number of requests fetched from the client before feeding into the first Executor.

Used to control the speed of data input into a Flow. 0 disables prefetch (disabled by default)

number

0

title

The title of this HTTP server. It will be used in automatics docs such as Swagger UI.

string

None

description

The description of this HTTP server. It will be used in automatics docs such as Swagger UI.

string

None

cors

If set, a CORS middleware is added to FastAPI frontend to allow cross-origin access.

boolean

False

no_debug_endpoints

If set, /status /post endpoints are removed from HTTP interface.

boolean

False

no_crud_endpoints

If set, /index, /search, /update, /delete endpoints are removed from HTTP interface.

Any executor that has @requests(on=...) bind with those values will receive data requests.

boolean

False

expose_endpoints

A JSON string that represents a map from executor endpoints (@requests(on=...)) to HTTP endpoints.

string

None

uvicorn_kwargs

Dictionary of kwargs arguments that will be passed to Uvicorn server when starting the server

More details can be found in Uvicorn docs: https://www.uvicorn.org/settings/

object

None

grpc_server_kwargs

Dictionary of kwargs arguments that will be passed to the grpc server when starting the server # todo update

object

None

ssl_certfile

the path to the certificate file

string

None

ssl_keyfile

the path to the key file

string

None

expose_graphql_endpoint

If set, /graphql endpoint is added to HTTP interface.

boolean

False

protocol

Communication protocol between server and client.

string

GRPC

host

The host address of the runtime, by default it is 0.0.0.0.

string

0.0.0.0

proxy

If set, respect the http_proxy and https_proxy environment variables. otherwise, it will unset these proxy variables before start. gRPC seems to prefer no proxy

boolean

False

graph_description

Routing graph for the gateway

string

{}

graph_conditions

Dictionary stating which filtering conditions each Executor in the graph requires to receive Documents.

string

{}

deployments_addresses

dictionary JSON with the input addresses of each Deployment

string

{}

deployments_disable_reduce

list JSON disabling the built-in merging mechanism for each Deployment listed

string

[]

compression

The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression.

string

None

timeout_send

The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default

number

None

runtime_cls

The runtime class to run inside the Pod

string

GRPCGatewayRuntime

timeout_ready

The timeout in milliseconds of a Pod waits for the runtime to be ready, -1 for waiting forever

number

600000

env

The map of environment variables that are available inside runtime

object

None

shards

The number of shards in the deployment running at the same time. For more details check https://docs.jina.ai/fundamentals/flow/create-flow/#complex-flow-topologies

number

1

replicas

The number of replicas in the deployment

number

1

monitoring

If set, spawn an http server with a prometheus endpoint to expose metrics

boolean

False

port_monitoring

The port on which the prometheus server is exposed, default is a random port between [49152, 65535]

number

random in [49152, 65535]

retries

Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas)

number

-1

floating

If set, the current Pod/Deployment can not be further chained, and the next .add() will chain after the last Pod/Deployment not this current one.

boolean

False

executors#

Collection of Executors used in the Flow. Each item in the collection corresponds to on add() call and specifies one Executor.

All keyword arguments passed to the Flow add() method can be used here.

Name

Description

Type

Default

name

The name of this object.

This will be used in the following places:
- how you refer to this object in Python/YAML/CLI
- visualization
- log message header
- …

When not given, then the default naming strategy will apply.

string

None

workspace

The working directory for any IO operations in this object. If not set, then derive from its parent workspace.

string

None

log_config

The YAML config of the logger used in this object.

string

default

quiet

If set, then no log will be emitted from this object.

boolean

False

quiet_error

If set, then exception stack information will not be added to the log

boolean

False

timeout_ctrl

The timeout in milliseconds of the control request, -1 for waiting forever

number

60

polling

The polling strategy of the Deployment and its endpoints (when shards>1).
Can be defined for all endpoints of a Deployment or by endpoint.
Define per Deployment:
- ANY: only one (whoever is idle) Pod polls the message
- ALL: all Pods poll the message (like a broadcast)
Define per Endpoint:
JSON dict, {endpoint: PollingType}
{‘/custom’: ‘ALL’, ‘/search’: ‘ANY’, ‘*’: ‘ANY’}

string

ANY

uses

The config of the executor, it could be one of the followings:
* an Executor YAML file (.yml, .yaml, .jaml)
* a Jina Hub Executor (must start with jinahub:// or jinahub+docker://)
* a docker image (must start with docker://)
* the string literal of a YAML config (must start with ! or jtype: )
* the string literal of a JSON config

When use it under Python, one can use the following values additionally:
- a Python dict that represents the config
- a text file stream has .read() interface

string

BaseExecutor

uses_with

Dictionary of keyword arguments that will override the with configuration in uses

object

None

uses_metas

Dictionary of keyword arguments that will override the metas configuration in uses

object

None

uses_requests

Dictionary of keyword arguments that will override the requests configuration in uses

object

None

py_modules

The customized python modules need to be imported before loading the executor

Note that the recommended way is to only import a single module - a simple python file, if your
executor can be defined in a single file, or an __init__.py file if you have multiple files,
which should be structured as a python package. For more details, please see the
Executor cookbook <https://docs.jina.ai/fundamentals/executor/executor-files/>__

array

None

port

The port for input data to bind to, default is a random port between [49152, 65535]

number

random in [49152, 65535]

host_in

The host address for binding to, by default it is 0.0.0.0

string

0.0.0.0

native

If set, only native Executors is allowed, and the Executor is always run inside WorkerRuntime.

boolean

False

output_array_type

The type of array tensor and embedding will be serialized to.

Supports the same types as docarray.to_protobuf(.., ndarray_type=...), which can be found
here <https://docarray.jina.ai/fundamentals/document/serialization/#from-to-protobuf>.
Defaults to retaining whatever type is returned by the Executor.

string

None

entrypoint

The entrypoint command overrides the ENTRYPOINT in Docker image. when not set then the Docker image ENTRYPOINT takes effective.

string

None

docker_kwargs

Dictionary of kwargs arguments that will be passed to Docker SDK when starting the docker ‘
container.

More details can be found in the Docker SDK docs: https://docker-py.readthedocs.io/en/stable/

object

None

volumes

The path on the host to be mounted inside the container.

Note,
- If separated by :, then the first part will be considered as the local host path and the second part is the path in the container system.
- If no split provided, then the basename of that directory will be mounted into container’s root path, e.g. --volumes="/user/test/my-workspace" will be mounted into /my-workspace inside the container.
- All volumes are mounted with read-write mode.

array

None

gpus

This argument allows dockerized Jina executor discover local gpu devices.

Note,
- To access all gpus, use --gpus all.
- To access multiple gpus, e.g. make use of 2 gpus, use --gpus 2.
- To access specified gpus based on device id, use --gpus device=[YOUR-GPU-DEVICE-ID]
- To access specified gpus based on multiple device id, use --gpus device=[YOUR-GPU-DEVICE-ID1],device=[YOUR-GPU-DEVICE-ID2]
- To specify more parameters, use `–gpus device=[YOUR-GPU-DEVICE-ID],runtime=nvidia,capabilities=display

string

None

disable_auto_volume

Do not automatically mount a volume for dockerized Executors.

boolean

False

host

The host address of the runtime, by default it is 0.0.0.0.

string

0.0.0.0

quiet_remote_logs

Do not display the streaming of remote logs on local console

boolean

False

upload_files

The files on the host to be uploaded to the remote
workspace. This can be useful when your Deployment has more
file dependencies beyond a single YAML file, e.g.
Python files, data files.

Note,
- currently only flatten structure is supported, which means if you upload [./foo/a.py, ./foo/b.pp, ./bar/c.yml], then they will be put under the same workspace on the remote, losing all hierarchies.
- by default, --uses YAML file is always uploaded.
- uploaded files are by default isolated across the runs. To ensure files are submitted to the same workspace across different runs, use --workspace-id to specify the workspace.

array

None

runtime_cls

The runtime class to run inside the Pod

string

WorkerRuntime

timeout_ready

The timeout in milliseconds of a Pod waits for the runtime to be ready, -1 for waiting forever

number

600000

env

The map of environment variables that are available inside runtime

object

None

shards

The number of shards in the deployment running at the same time. For more details check https://docs.jina.ai/fundamentals/flow/create-flow/#complex-flow-topologies

number

1

replicas

The number of replicas in the deployment

number

1

monitoring

If set, spawn an http server with a prometheus endpoint to expose metrics

boolean

False

port_monitoring

The port on which the prometheus server is exposed, default is a random port between [49152, 65535]

number

random in [49152, 65535]

retries

Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas)

number

-1

floating

If set, the current Pod/Deployment can not be further chained, and the next .add() will chain after the last Pod/Deployment not this current one.

boolean

False

install_requirements

If set, install requirements.txt in the Hub Executor bundle to local

boolean

False

force_update

If set, always pull the latest Hub Executor bundle even it exists on local

boolean

False

compression

The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression.

string

None

uses_before_address

The address of the uses-before runtime

string

None

uses_after_address

The address of the uses-before runtime

string

None

connection_list

dictionary JSON with a list of connections to configure

string

None

disable_reduce

Disable the built-in reduce mechanism, set this if the reduction is to be handled by the Executor connected to this Head

boolean

False

timeout_send

The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default

number

None

Variables#

Jina Flow YAMLs support variables and variable substitution according to the Github Actions syntax.

This means that the following variable substitutions are supported:

Environment variables#

Use ${{ ENV.VAR }} to refer to the environment variable VAR. You can find all Jina environment variables here.

Context variables#

Use ${{ CONTEXT.VAR }} to refer to the context variable VAR. Context variables can be passed to f.load_config(..., context=...) in the form of a Python dictionary.

Relative paths#

Use ${{root.path.to.var}} to refer to the variable var within the same YAML file, found at the provided path in the file’s structure. Note that the only difference between environment variable syntax and relative path syntax is the omission of spaces in the latter.