Skip to main content

prefect-northflank

PyPI version

Prefect integrations for running flows on the Northflank platform.

This collection provides a Prefect worker that can execute flow runs as containerized jobs on Northflank's cloud platform, giving you powerful orchestration capabilities with Northflank's container-native infrastructure.

Installation

Install prefect-northflank with pip:

pip install prefect-northflank

Quick Start

  1. Set up Northflank credentials:

    from prefect_northflank import Northflank
    
    credentials = Northflank(
        api_token="your-northflank-api-token",
    )
    credentials.save("northflank-creds")
    
  2. Create a work pool:

    prefect work-pool create --type northflank my-northflank-pool
    
  3. Configure your deployment (prefect.yaml):

    deployments:
    - name: my-northflank-deployment
      entrypoint: flows.py:my_flow
      work_pool:
        name: my-northflank-pool
        job_variables:
          credentials: "{{ prefect.blocks.northflank.northflank-creds }}"
          project_id: "your-northflank-project-id"
          deployment_external_image_path: "prefecthq/prefect:3-python3.12"
          billing_deployment_plan: "nf-compute-20"
    
  4. Start a worker:

    prefect worker start --pool my-northflank-pool
    
  5. Deploy and run your flow:

    prefect deploy --all
    prefect deployment run 'my-flow/my-northflank-deployment'
    

Configuration

Flattened Configuration Structure

The Northflank worker uses a flattened configuration structure to work with Prefect's JSON schema requirements. Complex nested objects are flattened using underscore notation:

  • billing.deploymentPlan → billing_deployment_plan
  • deployment.external.imagePath → deployment_external_image_path
  • settings.activeDeadlineSeconds → settings_active_deadline_seconds
  • deployment.storage.ephemeralStorage.storageSize → deployment_storage_ephemeral_storage_size

This allows for easier configuration in YAML files and work pools while maintaining compatibility with the full Northflank API.

Worker Configuration

The Northflank worker supports the following configuration options:

Parameter Type Description Default
Core Configuration
credentials Northflank API credentials Required
project_id str Northflank project ID Required
cleanup_job bool Delete job after completion True
name str Job name Auto-generated
description str Job description Auto-generated
tags List[str] Resource tags None
Infrastructure
infrastructure_architecture str CPU architecture (x86/arm) None
Billing
billing_deployment_plan str Resource allocation plan "nf-compute-20"
billing_gpu_enabled bool Enable GPU support False
billing_gpu_type str GPU type None
billing_gpu_count int Number of GPUs 1
billing_gpu_timesliced bool Timesliced GPU sharing None
External Deployment
deployment_external_image_path str Container image path None
deployment_external_credentials str Registry credentials ID None
Internal Deployment
deployment_internal_id str Build service ID None
deployment_internal_branch str Git branch None
deployment_internal_build_sha str Commit SHA to deploy None
deployment_internal_build_id str Build ID to deploy None
Docker Configuration
deployment_docker_config_type str Docker config type "customCommand"
deployment_docker_custom_command str Custom command None
Storage
deployment_storage_ephemeral_storage_size int Ephemeral storage per container, in MB (at least 1024) Platform default
deployment_storage_shm_size int Memory-backed /dev/shm, in MB (at least 64) Platform default
Runtime
runtime_environment Dict[str, str] Environment variables None
Settings
settings_backoff_limit int Retry attempts 3
settings_active_deadline_seconds int Job timeout (seconds) 3600
settings_run_on_source_change str Source change trigger "never"

Deployment Types

The Northflank worker supports two deployment strategies. Only one should be specified per job. If none is configured, the worker defaults to external deployment with the Prefect image.

1. External Image Deployment (Default)

Deploy from a pre-built container image from any registry:

job_variables:
  deployment_external_image_path: "prefecthq/prefect:3-python3.12"
  deployment_external_credentials: "my-registry-creds-id"  # Optional for private registries

2. Internal Build Service Deployment

Deploy from Northflank's build service output:

job_variables:
  deployment_internal_id: "build-service-123"
  deployment_internal_branch: "main"
  deployment_internal_build_sha: "latest"  # Or specific commit SHA
  # OR
  deployment_internal_build_id: "build-456"  # Specific build ID

Docker Configuration

Docker settings can be combined with either deployment type to control how the container runs:

job_variables:
  deployment_external_image_path: "prefecthq/prefect:3-python3.12"
  deployment_docker_config_type: "customCommand"
  deployment_docker_custom_command: "python my_script.py"

Runtime Storage

Set runtime disk and shared memory sizes in your deployment's job variables:

job_variables:
  deployment_storage_ephemeral_storage_size: 2048
  deployment_storage_shm_size: 256  # Optional memory-backed /dev/shm

The API describes these values in MB. Ephemeral storage must be at least 1024; shared memory must be at least 64. Unset values use the platform defaults. Shared memory uses RAM and is separate from the runtime disk. Requested sizes must fit your Northflank project's resource allowance.

For an existing work pool, update its base job template to include these variables and their job configuration mappings, or create a new pool after upgrading the worker package. Deployment job variables require matching entries in the pool's base job template.

Environment Variables

The worker automatically injects Prefect environment variables into job containers:

  • PREFECT__FLOW_RUN_ID: The unique flow run identifier (note the double underscore)
  • PREFECT_API_URL: Prefect server/cloud API URL (if configured)
  • PREFECT_API_KEY: Prefect API authentication key (if configured)
  • Any other Prefect settings configured in the current environment

User-provided environment variables in runtime_environment take precedence over automatic variables.

Examples

Basic Flow Example

from prefect import flow

@flow
def my_flow():
    print("Hello from Northflank!")
    return "Flow completed successfully"

if __name__ == "__main__":
    my_flow()

GPU Configuration Example

# prefect.yaml for GPU workloads
deployments:
  - name: gpu-training
    entrypoint: train_model.py:training_flow
    work_pool:
      name: northflank-gpu-pool
      job_variables:
        credentials: "{{ prefect.blocks.northflank.my-creds }}"
        project_id: "proj-123456"
        deployment_external_image_path: "nvidia/pytorch:23.10-py3"
        billing_deployment_plan: "nf-gpu-h100-80-1g"
        billing_gpu_enabled: true
        billing_gpu_type: "h100-80"
        billing_gpu_count: 2
        settings_active_deadline_seconds: 14400  # 4 hours
        runtime_environment:
          CUDA_VISIBLE_DEVICES: "0,1"
          TORCH_CUDA_ARCH_LIST: "8.9"

Build Service Deployment Example

# prefect.yaml for internal build service deployment
deployments:
  - name: my-build-deployment
    entrypoint: flows.py:my_flow
    work_pool:
      name: my-northflank-pool
      job_variables:
        credentials: "{{ prefect.blocks.northflank.my-creds }}"
        project_id: "proj-123456"
        deployment_internal_id: "build-service-abc123"
        deployment_internal_branch: "main"
        billing_deployment_plan: "nf-compute-50"
        runtime_environment:
          ENVIRONMENT: "production"
          LOG_LEVEL: "info"

Authentication

API Token Setup

  1. Log in to your Northflank dashboard
  2. Navigate to Account Settings > API
  3. Create a new API Role with the following permissions:
    • Project > General > Read
    • Project > Jobs > General — Create, Read, Delete
  4. Create a new API Token using the role you just created
  5. Store the token securely using Prefect's block system
from prefect_northflank import Northflank

credentials = Northflank(api_token="nf-...")
credentials.save("my-northflank-creds")

Development

Setup

  1. Clone the repository:

    git clone https://github.com/northflank/prefect-northflank.git
    cd prefect-northflank
    
  2. Install with uv:

    uv sync
    uv run python -m pip install -e .
    

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For support with this integration, please:

  1. Check the documentation
  2. Search existing issues
  3. Create a new issue if needed

Metadata

Release files for prefect-northflank 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for prefect-northflank 1.0.2
File Size Uploaded Provenance Actions
prefect_northflank-1.0.2.tar.gz 12.1 kB Without provenance Details for prefect_northflank-1.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for prefect-northflank 1.0.2
File Interpreter ABI Platform Actions
prefect_northflank-1.0.2-py3-none-any.whl Python 3 none any Details for prefect_northflank-1.0.2-py3-none-any.whl

Total release size: 25.7 kB

Release files / prefect_northflank-1.0.2.tar.gz

Download URL prefect_northflank-1.0.2.tar.gz
Size 12.1 kB
Tags Source
SHA-256 checksum
How to use checksums
393a7f64cde624c82ed59ced99dcaf7b27484caf1334c7b48ee19e184bffa8f8
BLAKE2b-256 checksum
How to use checksums
4e65e31d23308d84bdf48404be8bc858b715cb1a056aca4c87d399a96cd10522
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.16

Release files / prefect_northflank-1.0.2-py3-none-any.whl

Download URL prefect_northflank-1.0.2-py3-none-any.whl
Size 13.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6ba4d4647ba1598a8f537d50349795fa260e80f9f53b2ec216b89f018f44a098
BLAKE2b-256 checksum
How to use checksums
69886840d19c7dcc16c698bb217b3404300cb7c4f73da29e7020d407f6b7a78b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.16

Security for prefect-northflank 1.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page