Celerity

celerity/vpc

Spec Version: v2026-02-27-draft
Ecosystem Compatibility: v0 (Current) / v1 (Preview)

blueprint transform: celerity-2026-02-27-draft

Ecosystem Compatibility

v0 (Current): AWS only, supporting Amazon VPCs.
v1 (Preview): Multi-cloud, supporting Amazon VPCs, Google Cloud VPCs and Azure VNets.

Specification

The specification is the structure of the resource definition that comes under the spec field of the resource in a blueprint. The rest of this section lists fields that are available to configure the celerity/vpc resource followed by examples of different configurations for the resource and how the VPC behaves in target environments along with additional documentation.

Feature Availability

✅ Available in v0 - Features currently supported
🔄 Planned for v0 - Features coming in future v0 evolution
🚀 Planned for v1 - Features coming in v1 release

name (required)

A unique name for the VPC that will be used to identify the VPC in the target environment. This will be used as a resource tag in target environments that support resource tagging for networking resources.

The name is also the key used to share a VPC across applications: a celerity/vpc declared in referenced mode locates the existing Celerity-managed VPC by matching this name, so the referencing resource must use the same name as the managed VPC it points at.

type

string

preset

The preset of the VPC that determines the configuration of the VPC resources in the target environment.

This can be one of the following values:

standard: A multi-AZ VPC with a public and private subnet in 3 availability zones (6 subnets in total).
public: A multi-AZ VPC with a public subnet in 3 availability zones.
isolated: A multi-AZ VPC with a private subnet in 3 availability zones.
light: A VPC with a public and private subnet in a single availability zone.
light-public: A VPC with a public subnet in a single availability zone.

For target environments that supports Dual-stack VPCs for Ipv4 and Ipv6 traffic, all presets will be configured to support both Ipv4 and Ipv6 traffic.

✅ Available in v0

allowed values

standard | public | isolated | light | light-public

default value

standard

type

string

mode

Determines whether Celerity provisions the VPC or references an existing Celerity-managed VPC.

This can be one of the following values:

managed: Celerity provisions the VPC and its associated networking resources from the preset, and owns their lifecycle.
referenced: The resource is a reference to an existing Celerity-managed VPC that has the same name. Celerity does not provision or modify any networking resources; it resolves the existing VPC along with its subnets, routing and access controls, this allows applications, databases and caches defined in this blueprint to be placed into it.

referenced mode allows a VPC to be shared across multiple applications (blueprints) without native cross-blueprint links. One application declares the VPC in managed mode (the owner), and any number of other applications declare a celerity/vpc with the same name in referenced mode. Each application places its own resources into the shared VPC through its own local links; the VPC itself is matched by name in the target environment, so no link crosses a blueprint boundary.

When mode is referenced:

preset is ignored — the topology already exists and is not re-derived.
Target-environment networking options in the app deploy configuration (for example aws.vpc.cidrBlock) are ignored, for the same reason.
The referenced VPC must be one that Celerity created in managed mode, identified by the Celerity VPC name. Referencing a VPC provisioned outside of Celerity is not supported by this field.

Celerity does not provision or modify the shared network topology of a referenced VPC: its subnets, routing, gateways and network access controls belong to the application that declared it in managed mode. It does create the network access controls that this application's own handlers, databases and caches need, scoped to this application so they are never adopted or removed by the VPC's owner or by another application sharing it. This is what allows each application sharing a VPC to be deployed and destroyed independently.

Sharing a VPC is supported within a single cloud account. Cross-account sharing is not supported, since an application would need permission to create network access controls in an account it does not deploy into.

✅ Available in v0

allowed values

managed | referenced

default value

managed

type

string

Annotations

There are no annotations required for linking other resources to a celerity/vpc resource or modifying the behaviour of a VPC resource.

linkSelector.byLabel can be used to target VPCs from other resource types.

Outputs

Outputs are computed values that are accessible via the {resourceName}.spec.* field accessor in a blueprint substitution. For example, if the resource name is myVpc, the output would be accessible via ${myVpc.spec.id}.

id

The ID of the created VPC in the target environment.

type

string

examples

vpc-1234567890 (AWS VPC)

projects/my-project/global/networks/my-vpc (Google Cloud VPC)

my-vnet (Azure VNet)

Linked From

VPC resources can not be linked to from other resources.

Links To

`celerity/api`

When a VPC resource links to a celerity/api resource, the VPC will be used to place the API in the target environment when the API is deployed as a containerised application.

In serverless environments the API itself is managed by the cloud provider and is never deployed to a customer-managed network, so the placement cascades to the API's handlers: every handler linked to the API is attached to the VPC as though it were linked to the celerity/vpc directly. The celerity.api.vpc.egress annotation narrows their outbound access, and on serverless targets that support it the celerity.api.vpc.subnetType annotation selects the subnet tier.

✅ Available in v0 for serverless targets, where the link places the API's handlers.

✅ Available in v0 for the ECS-backed AWS target, where the link places the ECS service running the API and the load balancer fronting it.

🚀 Planned for v1 - Placement of the API itself in the EKS-backed AWS target and in the Google Cloud and Azure containerised targets.

`celerity/handler`

When a VPC resource links to a celerity/handler resource, the VPC will be used to place the handler in the target environment when the handler is deployed as a part of a FaaS application. A link between a VPC and handler will have no effect on handlers in a containerised application.

✅ Available in v0

`celerity/consumer`

When a VPC resource links to a celerity/consumer resource, the VPC will be used to place the consumer in the target environment when the consumer is deployed as a containerised application.

In serverless environments the consumer is a binding between an event source and a handler with no compute of its own, so the placement cascades to the consumer's handlers. The celerity.consumer.vpc.egress annotation narrows their outbound access, and on serverless targets that support it the celerity.consumer.vpc.subnetType annotation selects the subnet tier.

✅ Available in v0 for serverless targets, where the link places the consumer's handlers.

✅ Available in v0 for the ECS-backed AWS target, where the link places the ECS service running the consumer application.

🚀 Planned for v1 - Placement of the consumer application itself in the EKS-backed AWS target and in the Google Cloud and Azure containerised targets.

`celerity/schedule`

When a VPC resource links to a celerity/schedule resource, the VPC will be used to place the schedule application component in the target environment when the schedule is deployed as a containerised application.

In serverless environments the schedule is a binding between a scheduler and a handler with no compute of its own, so the placement cascades to the schedule's handlers. The celerity.schedule.vpc.egress annotation narrows their outbound access, and on serverless targets that support it the celerity.schedule.vpc.subnetType annotation selects the subnet tier.

✅ Available in v0 for serverless targets, where the link places the schedule's handlers.

✅ Available in v0 for the ECS-backed AWS target, where the link places the ECS service running the schedule application.

🚀 Planned for v1 - Placement of the schedule application component itself in the EKS-backed AWS target and in the Google Cloud and Azure containerised targets.

`celerity/workflow`

When a VPC resource links to a celerity/workflow resource, the VPC will be used to place the workflow runtime service in the target environment. Workflows are always deployed as containerised services with the aws, gcloud or azure target environment, where they can also run on serverless container infrastructure such as AWS Fargate, Google Cloud Run or Azure Container Apps.

🚀 Planned for v1 - A VPC resource will be able to link to celerity/workflow resources when workflows are supported.

`celerity/cache`

When a VPC resource links to a celerity/cache resource, the VPC will be used to place the cache instance or cluster in the target environment.

✅ Available in v0

`celerity/sqlDatabase`

When a VPC resource links to a celerity/sqlDatabase resource, the VPC will be used to place the SQL database instance or cluster in the target environment.

✅ Available in v0

Placing an application component in a VPC

Which resource carries the compute depends on the target environment. In containerised environments the celerity/api, celerity/consumer and celerity/schedule resources are the unit of compute and the VPC places them directly. In serverless environments they are trigger bindings with no compute of their own, and the handlers are the compute.

So that the same blueprint expresses "run this component's compute in this network" on either target, a VPC linked to a celerity/api, celerity/consumer or celerity/schedule in a serverless environment places the handlers linked to that component. Each inheriting handler is attached to the VPC exactly as though it were linked to the celerity/vpc directly.

This means you can place an application in a VPC by labelling the components you already declare in the blueprint, rather than by selecting the handlers, which are commonly derived from code:

resource appVpc: celerity/vpc {
    spec {
        name = "app-network"
        preset = "standard"
    }

    select by label {
        network = "app-network"
    }
}

resource ordersApi: celerity/api {
    metadata {
        labels = {
            network = "app-network"
        }
    }

    spec {
        protocols = ["http"]
    }
}

A label on the component is all that is required. The following rules apply to inherited placements:

A celerity/vpc linked to a handler directly takes precedence; the handler does not inherit a placement from any component it is bound to. This is how a single handler opts into a different VPC, or out of the component's placement settings.
A handler belongs to at most one VPC. Inheriting different VPCs from more than one component (for example an API placed in one VPC and a consumer placed in another, both linked to the same handler) is an error. Link that handler to the intended celerity/vpc directly to resolve it.
A component's celerity.<component>.vpc.* placement annotations apply to every handler inheriting its placement, and a handler's own celerity.handler.vpc.* annotation of the same name overrides it. Which annotations exist depends on the target environment; see outbound internet access and, for serverless targets, subnet placement.
Only the label the VPC's link selector matched the component on is carried onto the handler's compute; the component's other labels are not.

Reach within a VPC

Inside the VPC, a handler can reach exactly the resources it is linked to. Placing a handler in a VPC grants it a network location, not access; each link to a celerity/sqlDatabase, celerity/cache or other resource in that VPC opens the access that link needs. Two handlers placed in the same VPC therefore cannot reach each other's databases unless each is linked to them.

This applies to reach within the network. Calls out of your application are covered by outbound internet access below.

Outbound internet access

Placing a handler in a VPC does not, by itself, take away its ability to call out of your application. Where the VPC provides an outbound path, the handler keeps it, so a third-party HTTP API or OIDC discovery for a jwt guard keeps working. Placement restricts what the handler can reach inside the network, which is covered above.

Whether an outbound path exists is a property of the preset, and needs no configuration either way. standard and light provide one; isolated deliberately provides none. public and light-public provide one without any gateway to pay for, at the cost of what they can reach: the details depend on the target environment and on how the handler is deployed. For AWS, see outbound internet access from serverless handlers.

✅ Available in v0

Restricting outbound access

Outbound access is on by default wherever the VPC provides it, and the celerity.handler.vpc.egress annotation narrows it. It accepts internet, none, or a comma-separated list of CIDR ranges. It can also be set on the containing celerity/api, celerity/consumer or celerity/schedule as celerity.<component>.vpc.egress, applying to every handler that inherits the component's placement.

resource ordersApi: celerity/api {
    metadata {
        labels = {
            network = "app-network"
        }
        annotations = {
            "celerity.api.vpc.egress" = "none"
        }
    }

    spec {
        protocols = ["http"]
    }
}

Setting this annotation to internet or a CIDR list in a VPC that provides no outbound path is reported as an error before anything is deployed, rather than surfacing as a handler that times out at runtime. Leaving it unset is never an error: it resolves to whatever the VPC supports.

✅ Available in v0

A handler that is not linked to a VPC is not VPC-attached and retains full outbound internet access.

Subnet placement in serverless environments

The handler's celerity.handler.vpc.subnetType annotation selects which subnet a VPC-attached serverless function is placed in. It accepts public or private and defaults to private.

This annotation is target-specific

subnetType is only considered by serverless targets that place functions in specific subnets of a customer-managed VPC, which today means AWS Lambda alone. It has no effect on other serverless targets: Google Cloud (Cloud Functions / Cloud Run) attaches functions to a VPC through a Serverless VPC Access connector and egress settings, and Azure Functions use VNet integration. Neither offers a public/private subnet choice for the function, so setting the annotation for those targets does nothing rather than something different.

The rest of this section describes AWS behaviour.

A VPC-attached Lambda never receives a public IPv4 address, which makes subnet choice behave differently than it does for a typical instance:

private (default): the function can reach the resources it is linked to in the VPC, such as a celerity/sqlDatabase or celerity/cache, and where the VPC provides a NAT gateway it has a route to the public internet over both IPv4 and IPv6. This default requires the VPC to provide a private subnet; on the public and light-public presets, which provision none, set subnetType to public explicitly.
public: the function can reach the resources it is linked to in the VPC, and reaches the public internet over IPv6 only. A VPC-attached function is never assigned a public IPv4 address, so it cannot use the internet gateway for IPv4 the way an instance or a Fargate task can. It is assigned an IPv6 address, which is globally routable, so IPv6 destinations are reachable without a NAT gateway.

On a preset that provisions private subnets, public is rarely the right choice: the NAT gateway is provisioned and billed either way, so the only effect is to lose IPv4 access.

Examples

Create a Standard VPC

Blueprint Language

version "2025-11-02"
transform "celerity-2026-02-27-draft"

resource myVpc: celerity/vpc {
    spec {
        name = "my-vpc"
        preset = "standard"
    }
}

YAML

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    myVpc:
        type: "celerity/vpc"
        spec:
            name: "my-vpc"
            preset: "standard"

One application owns the VPC in managed mode (the default). This is the blueprint that provisions the networking resources:

Blueprint Language

version "2025-11-02"
transform "celerity-2026-02-27-draft"

resource sharedVpc: celerity/vpc {
    spec {
        name = "platform-shared-vpc"
        preset = "standard"
    }
}

Any other application references the same VPC by name in referenced mode. It provisions no networking resources of its own, but its handlers, caches and databases are placed into the shared VPC:

Blueprint Language

version "2025-11-02"
transform "celerity-2026-02-27-draft"

resource sharedVpc: celerity/vpc {
    spec {
        name = "platform-shared-vpc"
        mode = "referenced"
    }
}

YAML

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    sharedVpc:
        type: "celerity/vpc"
        spec:
            name: "platform-shared-vpc"
            mode: "referenced"

Target Environments

Local Development

VPCs are not provisioned in the local development environment.

AWS

✅ Available in v0

Celerity VPCs are provisioned in AWS using the EC2 VPCs and associated networking resources. The Celerity VPC presets map to configurations of subnets, routing and access controls required for resources such as applications, databases and caches to be placed in the VPC.

A managed VPC is tagged with its Celerity name. A referenced VPC is resolved by looking up that same name tag in the target AWS account, so a VPC shared across applications is matched without any cross-blueprint reference. Because AWS VPCs are regional, the referenced VPC must be in the same region as the resources being placed into it.

Outbound internet access from serverless handlers

Whether a VPC-attached serverless handler has an outbound path follows from the preset, and needs no configuration:

Preset	Outbound internet
`standard`, `light`	✅ IPv4 and IPv6
`public`, `light-public`	✅ IPv6 only, with no gateway charges
`isolated`	❌ the preset deliberately provides no outbound path

✅ Available in v0

IPv6-only egress is not a general substitute for a NAT gateway

The public and light-public presets are the cost-optimised choice: a serverless handler placed in them reaches the internet over IPv6 through the internet gateway, and no NAT gateway is provisioned or billed.

The limit is that this only reaches destinations that publish an IPv6 address. A third-party API that is IPv4-only is unreachable from these presets, and there is no way to reach it without a NAT gateway. Choose them when you know what your handlers call out to; choose standard or light when you do not, or when you depend on a service that has not published IPv6 addresses.

If a handler needs the internet and nothing inside the VPC, the cheapest answer remains to leave it out of the VPC entirely: a handler that is not VPC-attached has full outbound access over both protocols and costs nothing in gateways.

Handlers in a private subnet reach the internet over IPv6 through an egress-only path, so IPv6 traffic can leave the VPC but nothing on the internet can open a connection to a handler.

Google Cloud

🚀 Planned for v1 - The Google Cloud deployment target is planned for v1, it may become available in a future v0 evolution.

Celerity VPCs are provisioned in Google Cloud using the VPC resource type in custom mode along with associated networking resources. The Celerity VPC presets map to configurations of subnets, routing and access controls required for resources such as applications, databases and caches to be placed in the VPC. A referenced VPC is resolved by its Celerity name (via network labelling); Google Cloud VPCs are global, so no region needs to match.

Azure

🚀 Planned for v1 - The Azure deployment target is planned for v1, it may become available in a future v0 evolution.

Celerity VPCs are provisioned in Azure using VNets and associated networking resources. The Celerity VPC presets map to configurations of subnets, routing and access controls required for resources such as applications, databases and caches to be placed in the VNet. A referenced VNet is resolved by its Celerity name; as with AWS, Azure VNets are regional, so the referenced VNet must be in the same region as the resources placed into it.

App Deploy Configuration

Configuration specific to a target environment can be defined for celerity/vpc resources in the app deploy configuration file.

This section lists the configuration options that can be set in the deployTarget.config object in the app deploy configuration file.

AWS Configuration Options

✅ Available in v0

aws.vpc.cidrBlock

The CIDR block for the IPv4 range to use for the VPC.

type

string

default value

10.0.0.0/16

aws.vpc.enableDNSSupport

When set to true, DNS support will be enabled for the VPC. For more information, see DNS attributes in your VPC.

type

boolean

default value

true

aws.vpc.enableDNSHostnames

Indicates whether the instances launched in the VPC get DNS hostnames. If enabled, instances in the VPC get DNS hostnames; otherwise, they do not. This is disabled by default for nondefault VPCs. You will want to enable DNS hostnames if you intend to use VPC endpoints to connect to AWS services using the public host names that SDKs use to connect to the services by default.

type

boolean

default value

false

Celerity VPC

On this page