Workflow API reference

Use this page after following the tutorials:

• Workflow overview
• Your first workflow job
• Reusable workflow jobs
• Long-running HTTP services
• Ready-to-use workflows

Image

Image.from_registry(name, repository_secret="")

Argument	Default	Meaning
name	Required	Container image name, tag, or digest.
repository_secret	""	CGC/Kubernetes secret used to pull a private image.

Returns an Image definition. It does not create a CGC resource.

ShellCommand

ShellCommand(executable, arguments=(), prelude="")

Argument	Default	Meaning
executable	Required	List or tuple containing the executable and optional subcommands, for example ("python", "-m", "my_service").
arguments	()	List or tuple of non-empty command arguments. An item can contain an option and its value, for example "--port 8000".
prelude	""	Optional shell setup executed before the main process, for example a small pip install command.

render() validates and quotes the executable and arguments, then returns the shell command. prelude is raw shell syntax and must only contain trusted setup commands. A ShellCommand can be returned by a custom inference function; job functions still return a shell command string.

Each arguments item is split once: "--label hello world" becomes a flag and the value hello world. Put tokens that must not be split, such as python -c source, in executable.

ServicePort

ServicePort(name, port, ingress=False)

Argument	Default	Meaning
name	Required	Non-empty CGC port name.
port	Required	Unique container port between 1 and 65535.
ingress	False	Whether CGC should create a public ingress for this additional port.

Use ServicePort entries in app.inference(additional_ports=[...]). Their names and numbers cannot duplicate the primary port or another additional port.

Names are stripped and lowercased before duplicate checks. Names accept up to 32 letters, digits or hyphens; ports must be integers and ingress must be a boolean.

Volume

Volume.from_name(
    name,
    mount_path="",
    size=None,
    storage_class=None,
    create_if_missing=False,
)

Argument	Default	Meaning
name	Required	CGC volume name.
mount_path	""	Path where the volume is mounted in the container.
size	None	Capacity in GB when creating the volume.
storage_class	None	Storage class; None uses the platform default.
create_if_missing	False	Metadata indicating that the workflow expects a missing volume to be created.

Method	Meaning
create(size=None, storage_class=None)	Creates the volume. Method arguments override values stored in the definition.
ensure()	Uses a ready volume or creates it when missing.
ready()	Returns whether the volume is ready.
delete(force=False)	Deletes the volume and its files.

Call ensure(), then wait for ready() before submitting the job. create_if_missing=True alone does not create a volume. Multiple volumes require default mount paths; a custom mount_path supports one volume only.

App

App(name, image=None, volumes=None, environment=None)

Argument	Default	Meaning
name	Required	Workflow name and default resource-name prefix.
image	None	Default Image used by workflow steps.
volumes	None	Default list of Volume definitions.
environment	None	Default environment variables as a string dictionary.

App stores shared configuration. It does not create a resource.

app.function() and app.job()

Both decorators create the same type of short-lived workflow task.

@app.function(
    image=None,
    name=None,
    cpu=1,
    memory=2,
    gpu=0,
    gpu_type="",
    volumes=None,
    environment=None,
    arguments=None,
    ttl_seconds_after_finished=3600,
    shm_size=0,
)

Argument	Default	Meaning
image	App image	Image used by this job.
name	App and function names	Base job name. A unique suffix is added.
cpu	1	CPU cores reserved for the job.
memory	2	Memory reserved in GB.
gpu	0	Number of GPUs.
gpu_type	""	CGC GPU identifier.
volumes	App volumes	Volumes attached to the job.
environment	{}	Variables merged with the App environment.
arguments	[]	Additional container arguments.
ttl_seconds_after_finished	3600	Seconds before a finished job is removed; None disables automatic cleanup.
shm_size	0	Shared memory size in GB.

The decorated function must return a non-empty shell command.

submit()

run = task.submit(*function_args, wait=False, **function_kwargs)

Passes the supplied values to the decorated function, creates a job, and returns JobRun.

for_each()

runs = task.for_each(*iterables, wait=False, kwargs=None)

Creates one job for each group produced by zip(*iterables). kwargs contains named values passed to every function call.

submit(wait=True) waits and returns JobRun, but does not raise for Failed or Timeout. Check the status before continuing.

JobRun

Method	Default arguments	Return value
status()	None	Current phase, NotFound, or Unknown.
wait()	poll_seconds=5, timeout_seconds=600	Succeeded, Failed, or Timeout.
logs()	timestamps=False	Job log response.
delete()	None	Delete response.

app.resource()

app.resource(
    image=None,
    name=None,
    startup_command=None,
    cpu=1,
    memory=2,
    gpu=0,
    gpu_type="",
    volumes=None,
    environment=None,
    repository_secret="",
    # Keyword-only options:
    arguments=None,
    entity="custom",
    shm_size=0,
    node_port_enabled=False,
)

Argument	Default	Meaning
image	App image	Container image.
name	<app-name>-resource	Exact CGC resource name.
startup_command	None	Command started in a custom container. When a custom resource has neither a command nor arguments, the SDK uses sleep infinity.
arguments	[]	Arguments parsed by the existing backend. Cannot be combined with startup_command.
entity	"custom"	Custom image or the name of a resource template available in the current CGC environment.
cpu	1	CPU cores.
memory	2	Memory in GB.
gpu	0	Number of GPUs.
gpu_type	""	CGC GPU identifier.
volumes	App volumes	Attached volumes.
environment	{}	Variables merged with App variables.
repository_secret	Image secret	Private registry secret override.
shm_size	0	Shared memory in GB.
node_port_enabled	False	Enables node-port exposure.

Returns ResourceDefinition, which provides create(), ready(), and delete().

A custom resource requires an image. A template resource must not receive an image or startup_command; pass its native arguments through arguments.

Pass arguments, entity, shm_size and node_port_enabled to app.resource() by keyword only.

app.inference()

@app.inference(
    image=None,
    name=None,
    port=8000,
    port_name="web",
    cpu=1,
    memory=2,
    gpu=0,
    gpu_type="",
    volumes=None,
    environment=None,
    repository_secret="",
    shm_size=0,
    node_port_enabled=False,
    ingress=True,
    # Keyword-only options:
    entity="custom",
    additional_ports=None,
)

Argument	Default	Meaning
image	App image	Container image.
name	App and function names	CGC resource name.
entity	"custom"	Custom image or a resource template available in the current CGC environment.
port	8000	Port used by the HTTP server.
port_name	"web"	CGC port and ingress identifier.
additional_ports	[]	Additional ServicePort definitions configured after the resource reaches Running.
cpu	1	CPU cores.
memory	2	Memory in GB.
gpu	0	Number of GPUs.
gpu_type	""	CGC GPU identifier.
volumes	App volumes	Attached volumes.
environment	{}	Variables merged with App variables.
repository_secret	Image secret	Private registry secret override.
shm_size	0	Shared memory in GB.
node_port_enabled	False	Enables node-port exposure.
ingress	True	Creates an ingress URL.

For entity="custom", a function may return a non-empty shell command, a ShellCommand, or a list/tuple of arguments for the image entrypoint. A backend template accepts a list/tuple of arguments; do not supply a custom image or shell command in that declaration. entity and additional_ports in app.inference() are keyword-only options.

Argument List Limitations

The backend splits "--port 8000" into a flag and value. Items with more than one space are rejected, and repeated keys may be overwritten. Use ShellCommand for complex custom commands.

deploy()

endpoint = service.deploy(
    *function_args,
    wait=False,
    reuse_existing=False,
    resource_timeout_seconds=600,
    poll_seconds=5,
    **function_kwargs,
)

Creates the resource and its ports, then returns DeployedEndpoint. Additional ports force a wait for Running, even when wait=False, because the backend can only add them to an available resource. A port configuration error preserves the created resource for inspection and explicit cleanup.

A readiness error or timeout stops port setup and preserves the resource. Already added ports are not rolled back. Exceptions include the resource name and available code, reason and details.

reuse_existing=False raises on a name conflict. True reuses the resource and can add missing ports, but does not update its image, command, environment or existing ports.

DeployedEndpoint

Property or method	Default arguments	Return value
url	None	Primary-port ingress URL; raises SDKException when primary ingress is disabled.
exists()	None	Whether the compute listing contains a pod labelled with this resource's app-name.
refresh_url()	None	Refreshed primary-port ingress URL.
status()	None	Running or Pending.
wait()	poll_seconds=5, timeout_seconds=600	Running or Timeout.
wait_http()	path="", status_code=200, poll_seconds=5, timeout_seconds=300, request_timeout=10	Successful HTTP response or SDKException.
post_json()	path, payload, headers=None, timeout=30	Decoded JSON or response text.
logs()	timestamps=False	Resource log response.
delete()	None	Delete response.

With primary ingress=False, do not use url, wait_http() or post_json(). Internal ports are reachable from workloads in the same namespace. The handle exposes only the primary port URL.

port_name="http" normally uses the root ingress path /; other names normally add /<port_name>. Use the returned URL and match application routes to that prefix. wait() returning Running is not an HTTP health check.

RTDetrWorkflow

Import it from the ready-made workflow recipes:

from cgc.sdk.recipes.rtdetr import RTDetrConfig, RTDetrWorkflow

RTDetrWorkflow(
    name,
    image,
    volume=None,
    config=None,
    inference_name=None,
)

Argument	Default	Meaning
name	Required	Workflow and default inference resource name.
image	Required	Image used by RT-DETR.
volume	None	Persistent volume required for dataset and training workflows, but not pretrained inference.
config	RTDetrConfig()	Model and resource configuration.
inference_name	Workflow name	Separate inference resource name.

RTDetrConfig arguments:

Argument	Default	Meaning
model_name	rtdetr-l.pt	Ultralytics model weights.
gpu_type	nvidia-rtx-a5000	GPU identifier used by training jobs.
epochs	3	Number of training epochs.
image_size	640	Training image size in pixels.
install_packages	True	Installs required Python packages when remote commands start.
download_cpu	2	CPU cores for dataset download jobs.
download_memory	8	Memory in GB for dataset download jobs.
train_cpu	4	CPU cores for training jobs.
train_memory	24	Memory in GB for training jobs.
inference_cpu	4	Inference CPU cores.
inference_memory	16	Inference memory in GB.
inference_gpu	1	Inference GPU count.
inference_gpu_type	nvidia-rtx-a5000	Inference GPU identifier.
inference_port	8000	Generated server port.
inference_port_name	api	CGC port name.
ttl_seconds_after_finished	86400	Seconds before completed training jobs are removed.

workflow.deploy_pretrained_inference(
    wait=False,
    gpu=None,
    gpu_type=None,
    reuse_existing=False,
)

Argument	Default	Meaning
wait	False	Waits for the inference resource to run.
gpu	None	Overrides config.inference_gpu for this deployment.
gpu_type	None	Overrides config.inference_gpu_type for this deployment.
reuse_existing	False	Reuses an inference resource with the same name.

Returns DeployedEndpoint.

RoboflowDataset

Import dataset helpers from the recipes package:

from cgc.sdk.recipes.datasets import RoboflowDataset, VolumeDataset

RoboflowDataset(
    workspace_id,
    project_id,
    version,
    format="yolov11",
    api_key="",
    target_class="",
)

Argument	Default	Meaning
workspace_id	Required	Roboflow workspace identifier.
project_id	Required	Roboflow project identifier.
version	Required	Numeric dataset version.
format	yolov11	Roboflow export format.
api_key	""	Roboflow API key used by the download job.
target_class	""	Optional target-class metadata.

Pass it to YoloWorkflow.download() or RTDetrWorkflow.download(), then call submit() on the returned job definition. See Datasets.

VolumeDataset

VolumeDataset(
    name,
    path,
    data_yaml="data.yaml",
    target_class="",
)

Argument	Default	Meaning
name	Required	Logical dataset name.
path	Required	Dataset directory on the workflow volume.
data_yaml	data.yaml	Ultralytics dataset configuration file.
target_class	""	Optional target-class metadata.

The workflow checks this dataset on the volume instead of downloading it.

YoloWorkflow

Import it from the ready-made workflow recipes:

from cgc.sdk.recipes.yolo import YoloConfig, YoloWorkflow

YoloWorkflow(
    name,
    image,
    volume=None,
    config=None,
    inference_name=None,
)

It uses the same constructor and shared Ultralytics configuration fields as RTDetrWorkflow. YoloConfig defaults model_name to yolo11n.pt.

Important methods:

Method	Meaning
download(dataset)	Returns a dataset download/check job definition.
train(dataset, model_id=None)	Returns a YOLO training job definition.
deploy_inference(dataset, model_id=None, wait=False, reuse_existing=False)	Deploys weights produced by training.
deploy_pretrained_inference(wait=False, gpu=None, gpu_type=None, reuse_existing=False)	Deploys pretrained weights without a volume.

See YOLO inference.