Deployments

Deployments are modeled as async lifecycle rows, not fire-and-forget requests.

Canonical Deploy Flow

The preferred frontend flow is:

  1. upload main.dart, Dockerfile, and pubspec.yaml

  2. create or update the draft function

  3. call POST /api/v1/projects/{projectId}/deployments

  4. poll status and events until a terminal state

Deployment Endpoints

  • POST /api/v1/projects/{projectId}/deployments

  • GET /api/v1/projects/{projectId}/deployments/{deploymentId}

  • GET /api/v1/projects/{projectId}/deployments/{deploymentId}/events

  • POST /api/v1/projects/{projectId}/deployments/{deploymentId}/undeploy

The older function-level deploy trigger still exists, but new frontend work should prefer the project-scoped async deployment API.

What The Backend Validates

Before queueing a deployment, the backend checks:

  • function ownership and project scoping

  • deployability of the selected Dart runtime

  • pubspec.yaml SDK compatibility with the allowed runtime windows

  • presence of explicit artifact sources or a compatible fallback path

  • provider-specific target and auth fields

  • GCP entitlements for the selected runtime target

If a runtime is still executable but already in a warning window, the deployment response can include warning text.

GCP Runtime Targets

GCP deployments require an explicit target.runtimeTarget.

Supported values:

  • cloud_run: standard target for normal DCF customer workloads

  • gke: advanced target for enterprise customers that already operate a GKE cluster, namespace, deployment, and container

The frontend defaults GCP projects to Cloud Run. GKE remains intentionally gated behind the GCP GKE runtime-target entitlement so smaller customers do not need to manage Kubernetes just to deploy a Dart service.

Required GCP target fields for every deployment:

  • projectId

  • region

  • artifactRepository

  • runtimeTarget

Additional Cloud Run field:

  • serviceName

Additional GKE fields:

  • namespace

  • deploymentName

  • containerName

Cloud Run access mode is resolved from the saved function access settings. A public function deploys with --allow-unauthenticated; a private function deploys with --no-allow-unauthenticated. GKE deployments record the same intent in metadata, but enforcement happens in the customer’s ingress, gateway, IAP, or equivalent runtime policy.

AWS Lambda Target

AWS deployments use the saved AWS OIDC integration, S3 artifact bucket, and CodeBuild project.

Required AWS target fields:

  • region

  • bucket

  • codebuildProject

  • ecrRepositoryUri

  • lambdaExecutionRoleArn

Deployment behavior:

  • DCF assumes the customer IAM role through AssumeRoleWithWebIdentity

  • DCF uploads the function artifact to s3://<bucket>/builds/app.zip

  • DCF starts the configured CodeBuild project with the standard DCF buildspec override plus S3_BUCKET, S3_KEY=builds/app.zip, FUNCTION_NAME, AWS_REGION, ECR_REPOSITORY_URI, and LAMBDA_EXECUTION_ROLE_ARN

  • CodeBuild builds and pushes the Lambda container image to customer-owned ECR

  • CodeBuild owns the Lambda create/update work inside the customer account

  • CodeBuild creates a public Lambda Function URL when the function does not already have one

  • DCF waits for CodeBuild to finish and records the Lambda deployment metadata

The CodeBuild project and buildspec must match the DCF contract. See AWS Customer OIDC Setup for the customer-side requirements.

Event Timeline

Deployment events are append-only. They exist so the frontend does not have to infer runner progress from a single status string.

Typical deployment progression:

  • deployment.queued

  • deployment.started

  • deployment.building

  • deployment.deploying

  • deployment.succeeded or deployment.failed

Typical undeploy progression:

  • undeploy.queued

  • undeploy.started

  • undeploy.succeeded or undeploy.failed

Undeploy And Delete

Deleting a function is not the same as undeploying it.

  • undeploy removes the live runtime resources

  • delete removes the function record only when the latest deployment lifecycle is no longer active

If a function is still live or mid-lifecycle, delete returns a conflict and the live deployment must be removed first.