Blocks

Prefect blocks store typed configuration that can be used across workflows and deployments. The most common use case for blocks is storing credentials used to access external systems such as AWS or GCP. Prefect supports a large number of common blocks and provides a Python SDK for creating your own.

​

How blocks work

There are three layers to a block: its type, a document, and a Python class.

​

Block type

A block type is essentially a schema registered with the Prefect API. This schema can be inspected and discovered in the UI on the Blocks page.

To see block types available for configuration, use prefect block type ls from the CLI or navigate to the Blocks page in the UI and click +.

These types separate blocks from Prefect variables, which are unstructured JSON documents. In addition, block schemas allow for fields of SecretStr type which are stored with additional encryption and not displayed by default in the UI.

Block types are identified by a slug that is not configurable.

from prefect.blocks.core import Block


class Cube(Block):
    edge_length_inches: float


# register the block type under the slug 'cube'
Cube.register_type_and_schema()

​

Block document

A block document is an instantiation of the schema, or block type. A document contains specific values for each field defined in the schema.

All block types allow for the creation of as many documents as you wish. Building on our example above:

from prefect.blocks.core import Block


class Cube(Block):
    edge_length_inches: float


# instantiate the type with specific values
rubiks_cube = Cube(edge_length_inches=2.25)

# store those values in a block document 
# on the server for future use
rubiks_cube.save("rubiks-cube")


# instantiate and save another block document
tiny_cube = Cube(edge_length_inches=0.001)
tiny_cube.save("tiny")

Block documents can also be created and updated in the UI or API for easy change management. This allows you to work with slowly changing configuration without having to redeploy all workflows that rely on it; for example, you may use this to rotate credentials on a regular basis without touching your deployments.

​

Block class

A block class is the primary user-facing object; it is a Python class whose attributes are loaded from a block document. Most Prefect blocks encapsulate additional functionality built on top of the block document.

For example, an S3Bucket block contains methods for downloading data from, or upload data to, an S3 bucket; a SnowflakeConnector block contains methods for querying Snowflake databases.

Returning to our Cube example from above:

from prefect.blocks.core import Block

class Cube(Block):
    edge_length_inches: float

    def get_volume(self):
        return self.edge_length_inches ** 3

    def get_surface_area(self):
        return 6 * self.edge_length_inches ** 2


rubiks_cube = Cube.load("rubiks-cube")
rubiks_cube.get_volume() # 11.390625

​

Pre-registered blocks

​

Built-in blocks

Commonly used block types come built-in with Prefect. You can create and use these block types through the UI without installing any additional packages.

​

Blocks in Prefect integration libraries

Some block types that appear in the UI can be created immediately, with the corresponding integration library installed for use. For example, an AWS Secret block can be created, but not used until the prefect-aws library is installed.

Find available block types in many of the published Prefect integrations libraries. If a block type is not available in the UI, you can register it through the CLI.

Anyone can create a custom block type and, optionally, share it with the community.

​

Additional resources

You can manage blocks with the Prefect CLI.

You can manage blocks with the Terraform provider for Prefect.