Workflow overview

A CGC workflow is a Python description of work that should run in CGC. It connects:

• a container image containing the required software,
• CPU, memory, and optional GPU resources,
• optional persistent storage,
• a command to execute,
• methods for checking status, reading logs, and cleaning up.

What runs where?

Your workflow script starts on your computer. It defines the workload and asks CGC to create it. The actual command runs in a container in CGC.

Your computer                         CGC
-------------                         ---
Run the Python workflow script
Build a shell command
Call submit(), create(), or deploy()  -> Create the workload
                                      Run the command in a container
Read status and logs                 <- Return workload information

Creating Image, Volume, or App objects does not create a CGC resource. Creation happens when you call:

• submit() for a job,
• create() for a long-running resource,
• deploy() for a long-running HTTP service.

The public workflow primitives are imported from cgc.sdk:

from cgc.sdk import App, Image, ServicePort, ShellCommand, Volume

Higher-level ready-made workflows, such as YOLO, RT-DETR, and dataset helpers, are imported from cgc.sdk.recipes.

Choose the workload type

Type	Use it when	How it starts	How it ends
Job	A command has a clear end, such as processing a file or generating a report.	task.submit(...)	The command finishes or fails.
Resource	A process should keep running without an external HTTP URL.	resource.create()	You delete the resource.
HTTP service	A server should receive requests through a CGC URL.	service.deploy(...)	You delete the endpoint.

Long-running resources and HTTP services use entity="custom" by default. A custom entity runs your selected Image. You can also select a resource template available in the current CGC environment by passing its name as entity; template-based resources receive arguments instead of a custom image and startup command.

For an HTTP service, deploy() creates the resource and configures its primary port. When additional_ports are declared, the SDK waits for the resource to reach Running before adding the primary and additional ports.

You define the function name

Names such as process_file, generate_report, or convert_image are not SDK functions. You create them to describe your own task:

@app.function(cpu=1, memory=2)
def process_file(input_url):
    return "command that processes the file"

The SDK replaces the decorated Python function with a workflow object. You then use methods such as process_file.submit(...).

The Python function runs locally to build a shell command. CGC runs the returned command inside the selected container image.

Learning path

1. Create your first workflow job.
2. Process images with a reusable job, volume, and Filebrowser.
3. Deploy a long-running HTTP service.
4. Explore ready-to-use workflows for datasets, YOLO, and RT-DETR.
5. Look up all classes and arguments in the API reference.

Complete scripts for these tutorials are collected on the Workflow examples page.

Before running a workflow, install the SDK and confirm the selected CGC context:

pip install cgcsdk
cgc context list