Deploy contract

What CloudGrid does to your code on the way to a running service, and what you can change about it.

The platform owns the build recipe. You write source code and cloudgrid.yaml; the platform turns that into a container image, a Kubernetes Deployment, a Service, an Ingress, probes, and env injection. This page lists what the platform decides, what you control, and what is not user-overridable today.

If you came here from a build failure asking "where do I change X" — start with the override table and the versioning policy. If X is not in the override table, it is not user-changeable today; the path is to ask for it, not to work around it.

1. What the platform decides for you

These are platform choices. They apply to every service of the given type. No yaml field overrides them today.

Container port

Every service container listens on 8080 by default, regardless of type. The per-service port: yaml override swaps the listener for individual services whose framework hard-codes a different port — the default below is what applies when port: is absent.

• The platform injects PORT=<container-port> into the runtime environment (8080 by default; the per-service port: override when declared). Node and Python services read process.env.PORT / os.environ['PORT']; the synthesized nginx config (for static) is rendered with listen <container-port>. The Dockerfile template's EXPOSE directive is substituted from the same value, so the image, the manifest, and the probes all agree on a single number.
• The Kubernetes containerPort, the Service targetPort, all three probes, and the PORT env var all align on the same number. You can shift them together with port:; you can't make them disagree.
• Cluster-facing Service port: stays at 80 regardless — that is the port behind the internal URL the platform injects for service-to-service calls (a cluster-internal address of the shape http://<service>.<namespace>.svc.cluster.local:80; you never construct it by hand). The Service maps 80 to the container port; sibling URLs auto-injected as <UPPER>_URL always point at port 80.

Base image per service type

The platform's build pipeline synthesizes a Dockerfile from the service's type:. You do not supply one. The base images today:

Static-build runner

For type: static with a build: block, the platform runs your command (e.g. npm run build) in a build step using the runner image node:22-alpine (Node 22 LTS). This is the floor for Astro 6, Next.js 16, and Vite 7.

Synthesized nginx config (static services)

The platform writes the nginx config for type: static at image-build time. You do not supply nginx.conf. The synthesized config:

• Listens on 8080.
• Serves from /usr/share/nginx/html/.
• Routes a GET /health to a literal 200 ok.
• Falls through to index.html for any unmatched path (SPA-style).

If a nginx.conf is present in your service folder, it is ignored. The platform does not expose nginx tunables (gzip, cache headers, rate limits) through yaml today.

User Dockerfile — always ignored

Any Dockerfile in your project is silently stripped before the upload reaches the build, regardless of whether one exists at the project root, in services/<svc>/, or anywhere else.

You do not need to fix a failing build by editing a Dockerfile. The fix is one of:

• Make sure the entry file the platform expects exists (see the per-type entry-file contract in the CLOUDGRID.md reference the CLI installs into each project).
• Bind your server to process.env.PORT, not a hard-coded port.
• Add the missing dependency to package.json / requirements.txt.
• Make sure a build: block runs for frameworks that need a build step (Astro, Vite, SvelteKit — but not Next.js, which has its own template).

Env injection (auto-injected, in this order)

Every service container receives env vars in this order. Later sources override earlier ones, but the platform protects reserved keys against override.

1. Reserved platform vars. PORT, APP_NAME, SERVICE_NAME, NODE_ENV, CLOUDGRID_ORG_ID, CLOUDGRID_ENTITY_ID, RUNTIME_GATEWAY_URL.
2. Resource URLs for whatever the entity declares in requires: — MONGODB_URL, REDIS_URL, N8N_WEBHOOK_URL, plus the GCP service account binding when gcp: is declared.
3. Sibling-service URLs — one <UPPER_SVC>_URL per other service in the same yaml (e.g. a web service that has a sibling api gets API_URL).
4. Vault entries declared in the top-level vault: block — name on the left of each entry, resolved value on the right.
5. Static env from yaml — anything under services.<svc>.env:.
6. Runtime env — anything set via grid env set.
7. Secrets — anything set via grid secrets set (mounted from a per-entity Kubernetes Secret).

The platform's reserved keys cannot be overridden by the last three sources. grid env set PORT=… fails with RESERVED_KEY.

Probes

By default the platform configures Kubernetes startup, liveness, and readiness probes as TCP probes on the container port. A successful TCP connect counts as ready. You do not need a /health route.

You can opt in to a stricter HTTP probe per service with health: in yaml:

A separate external rollout probe (run after rollout) hits / and treats any HTTP response below 500 as up — so a 404 from a Next.js root still passes the rollout gate.

Image policy

• The Deployment's image: field is always <registry>/<image>:latest.
• Each build pushes both :latest and :sha-<short> to the registry; the sha tag exists for rollback and forensics.
• Rollback re-tags a chosen sha as :latest (see grid rollback).

You do not manage image tags or build numbers.

2. What you control via cloudgrid.yaml

The field-by-field reference is the CLOUDGRID.md file the CLI installs into each new project. Short summary of what is under your control today:

• What services exist — the services: map. Each service has a type:, optionally a path:, optionally a health: opt-in.
• What shared resources the entity needs — requires: (mongodb, redis, n8n, gcp services).
• How services depend on each other at startup — depends_on: per service.
• What env vars and secrets the service sees — env: in yaml, grid env set, grid secrets set, top-level vault:.
• For static sites — build: block with command: and optional output: directory.
• Cron services — schedule:, run:, timezone:.
• Where the source for each service lives — source.path: (default is services/<svc>/).
• Public exposure — expose: false to keep an entity internal (no Ingress, no public URL).
• Custom domains — custom_domains: list (additive to the default URL).

Anything not listed here — base image, Node version for server types, nginx config, build command flags for synthesized Dockerfiles — is platform-managed today.

3. What you can override and what you can't

If a knob you need is in the "No" column and you have a real use case, ask for it — don't work around the platform.

4. Smart defaults from package.json

At plug time the platform reads each uploaded service's package.json and fills yaml fields you left blank. The mechanism is additive — an explicit yaml field is never overridden; a smart default only applies when the yaml side is silent.

Precedence

Highest to lowest:

1. Explicit yaml field — whatever appears in cloudgrid.yaml.
2. Smart default — detected from package.json when the yaml is silent.
3. Platform default — the values above (Node 22 LTS, port 8080, no build command).

Any yaml that worked before this layer existed continues to deploy identically — smart defaults can only fill blanks.

Detection table

The semver-range resolver picks the highest matching supported major. engines.node: ">=20" resolves to 24; ^20 resolves to 20; >=18 <22 resolves to 20. A range that excludes every supported major (e.g. <18) resolves to nothing and the platform default applies.

What happens at plug time

For every service whose upload includes a parseable package.json, the deploy log surfaces one line:

Detected next from package.json. Using node_version 24, build_command 'next build'.

A service whose only signal is the static fallback (no framework dependency detected, no other field changed) produces no line — there is nothing to learn from a no-op detection.

Edge cases

• No package.json (static-only entity, index.html upload): smart defaults skip that service silently; platform defaults apply.
• Malformed package.json (invalid JSON, JSON-array root): treated as no signal, same as missing. The deploy does not fail.
• Validator-incompatible smart default: silently dropped. Example: engines.node detected for a type: node service does not fill node_version (the field is static-only — see the override table).
• Rollback: smart defaults skip entirely. The rollback target's previously-validated yaml is what re-deploys.

5. Versioning policy

When the platform changes a base image or a runner version, it is a fleet-wide change — every service of the affected type rebuilds on its next grid plug and runs against the new floor.

What counts as a version change

• A new minor or major for the runtime base image (node:20-alpine → node:22-alpine, nginx:1.27-alpine → nginx:1.28-alpine, python:3.11-slim → python:3.12-slim).
• A new minor or major for the static-build runner image.
• A change to the synthesized nginx config (new directives, changed defaults).
• A change to env injection order, or a new reserved key.

Patch-level bumps within the same minor (e.g. node:22-alpine → node:22.10-alpine as the upstream image rolls forward) are not announced — the alpine tag is a moving floor and re-pulls track upstream.

Announcement mechanism

Every version change ships via a CloudGrid release. The release note names the change, the floor it lifts, and any known-incompatible frameworks.

Why bumps happen

• A framework version your services use stops supporting the current floor (the Astro 6 / Node 22 case).
• A security advisory against the current floor (Alpine, openssl, upstream language runtime).
• A platform feature needs a runtime capability only available in a newer base.

The platform avoids bumps that don't gain anything. Bumps are intentional, named, and tied to a rollout date.

Backwards compatibility

The platform tries to keep bumps backwards-compatible: a service that worked on the previous floor should keep working on the new floor. When a bump cannot be backwards-compatible — for example, dropping a Python minor — the release note calls it out and the platform offers a version lever (like node_version:) for that cycle.