Manifest settings
This page lists every setting of an application manifest, with its type, whether it is required or its default, and what it does. It is generated from the manifest’s JSON Schema, so your editor shows the same descriptions. For how the settings work together, read the application manifest reference and the guides, such as serving an application over HTTPS.
Each table’s section is headed by the line that starts it in the file, such
as [[spec.services]]. Each setting is named by its full TOML path:
[]stands for each entry of an array of tables:spec.services[].nameis thenameof each[[spec.services]].- A name in angle brackets, such as
<environment>, stands for a key you choose:spec.environments.<environment>is each environment table, such as[spec.environments.staging].
A template is a string that may reference
variables, such as "${{ vars.domain }}". Only
settings whose type includes a template accept references. Linked types like
it are described under value types, at the end of the page.
Names, such as those of applications, environments, services, volumes, jobs, secrets and routes, are 1 to 63 lowercase letters, digits or hyphens. They start with a letter and end with a letter or digit.
Top level
An application: what it runs, and how its environments and previews deploy it.
api_version
Type: "piqueld.dev/v1alpha1". Required.
Version of the manifest format.
kind
Type: "Application". Required.
Kind of resource the manifest describes.
metadata
Type: table. Required.
The application’s identity.
spec
Type: table. Required.
What the application runs, and how it deploys.
[metadata] table
The application’s identity.
metadata.name
Type: string. Required.
Name of the application. A manifest with another name applies to another application, so rename one with piquelctl app rename.
[spec] table
What the application runs, and how its environments and previews deploy it.
spec.environments.<environment>
Type: table. Optional.
Declares the environment <environment> and how it deploys, for at most 64 environments.
spec.exports
Type: array of tables. Optional.
Services of this application that other applications may reach, at most 64.
spec.imports
Type: array of tables. Optional.
Services of other applications this application reaches, at most 64.
spec.jobs
Type: array of tables. Optional.
Containers that run to completion during each deployment, such as database migrations, at most 16. They run in the order listed.
spec.manifest
Type: table. Optional.
The Git repository each deployment reads the manifest from. Without it, deployments use the saved manifest. A manifest read from the repository can’t change it: its own spec.manifest is ignored.
spec.previews
Type: table. Default: { visibility = "private" }.
Settings shared by every preview.
spec.routes
Type: array of tables. Optional.
HTTP routes to the services, at most 64. They take effect when an environment deploys them.
spec.secrets
Type: array of tables. Optional.
Secrets piqueld generates a value for in each environment, at most 64.
spec.services
Type: array of tables. Optional.
The application’s services, at most 64.
spec.variables.<variable>
Type: boolean, integer or template. Optional.
Default value of the variable <variable>, referenced as ${{ vars.<variable> }}. An environment’s or the previews’ own value replaces it. Variable names start with a letter or _, use letters, digits, _ or -, and are at most 63 bytes. Each table of variables holds at most 128.
spec.volumes
Type: array of tables. Optional.
Named volumes the services mount, at most 64.
[spec.environments.<environment>] table
Declares an environment and where it deploys from. Without promote_from, the environment builds its own manifest: the saved one, or a branch of the spec.manifest repository. A block that sets none of branch, commit, promote_from and sync leaves an existing environment’s source as it is, unless the previous manifest set one of them: removing them returns the environment to the default source.
spec.environments.<environment>.branch
Type: string. Optional.
Branch of the manifest repository the environment deploys. By default, the branch spec.manifest names. Needs spec.manifest.
spec.environments.<environment>.commit
Type: string. Optional.
Full commit the environment deploys instead of its branch’s head. Without branch, by default the commit spec.manifest pins. Needs spec.manifest, and excludes sync.
spec.environments.<environment>.promote_from
Type: string. Optional.
Another environment whose releases this one receives with piquelctl env promote, instead of building. It excludes branch, commit and sync, and can’t lead back to this environment.
spec.environments.<environment>.rollback
Type: "automatic" or "manual". Optional.
What happens when a rollout fails: automatic restores the environment’s last successful deployment, manual leaves it degraded until someone acts. By default automatic for promoted environments and manual for the others.
spec.environments.<environment>.sync
Type: boolean. Optional.
Whether pushes to the environment’s branch deploy it while spec.manifest.sync is on. Off when unset. true needs spec.manifest.
spec.environments.<environment>.variables.<variable>
Type: boolean, integer or template. Optional.
The environment’s value of the variable <variable>. It replaces the [spec.variables] default, or declares a variable without one.
spec.environments.<environment>.visibility
Type: "public" or "private". Default: "public".
The strictest visibility the environment’s routes get. public restricts nothing; private keeps every route on the tailnet.
[[spec.exports]] table
A service of this application that other applications may reach over a private link, as <service>.<application>.
spec.exports[].applications
Type: array of strings. Required.
Applications whose environments may import the service: at least one, at most 64, each listed once.
spec.exports[].previews
Type: boolean. Default: false.
Whether previews of those applications may import the service too.
spec.exports[].service
Type: string. Required.
Service of this application to export, at most once.
[[spec.imports]] table
A service of another application this application reaches over a private link, as <service>.<application>.
spec.imports[].application
Type: string. Required.
Application exporting the service. It may be this application.
spec.imports[].environment
Type: template. Optional.
Environment of that application to reach. By default, the one named like the importing environment. It may reference variables, so previews can reach e.g. staging.
spec.imports[].service
Type: string. Required.
Service that application exports, imported at most once.
[[spec.jobs]] table
A container that runs to completion during each deployment, such as a database migration.
spec.jobs[].command
Type: array of templates. Required.
Command the job runs, instead of its service’s command and arguments. It can’t be empty.
spec.jobs[].environment.<name>
Type: template. Optional.
The environment variable <name> of the job’s container only, in addition to its service’s. A name the service also sets is an error.
spec.jobs[].name
Type: string. Required.
Name of the job, unique in the application.
spec.jobs[].run
Type: "before-rollout". Required.
When the job runs. before-rollout runs it after every source is prepared, before the services roll out.
spec.jobs[].secrets
Type: array of tables. Optional.
Secrets only the job’s container mounts, in addition to its service’s. A target the service already uses is an error.
spec.jobs[].service
Type: string. Required.
Service whose image, environment, secrets, volumes, resource limits and network the job reuses. The job also waits for the service’s depends_on.
spec.jobs[].stop_service
Type: boolean. Default: false.
Whether the job’s service stops before the job runs, once the job’s startup dependencies are ready, so its previous version never runs against what the job changes. The service starts again with the rollout, or with the previous deployment if a job fails.
spec.jobs[].timeout_seconds
Type: integer of at most 4294967295. Default: 300.
Seconds the job may run before the deployment fails, from 1 to 86,400.
spec.jobs[].volume_access
Type: "read-only" or "exclusive". Default: "read-only".
How the job mounts its service’s volumes. read-only mounts every volume read-only, so the job runs beside the services. exclusive keeps the writable volumes writable, and stops every service mounting them while the job runs.
[[spec.jobs.secrets]] table
A secret mounted as a file. A name spec.secrets declares mounts the environment’s generated value; any other name mounts a value from the application’s secret store.
spec.jobs[].secrets[].name
Type: template. Required.
Name of the secret. It may reference variables, so each environment can mount its own stored secret, e.g. ${{ vars.stripe_key }}.
spec.jobs[].secrets[].target
Type: string. Required.
Absolute path of the file under /run/secrets/, unique in the service.
[spec.manifest] table
The Git repository and file each deployment reads the manifest from.
spec.manifest.path
Type: string. Required.
Path of the TOML or JSON manifest file, relative to the repository root.
spec.manifest.repository
Type: table. Required.
The repository holding the manifest, and the branch environments deploy by default.
spec.manifest.sync
Type: table. Default: { mode = "off" }.
Whether pushes to the repository deploy environments and previews.
[spec.manifest.repository] table
A Git repository and the revision to check out. Git uses the host’s credentials.
spec.manifest.repository.branch
Type: string. Required.
Branch whose head is checked out when no commit is set.
spec.manifest.repository.commit
Type: string. Optional.
Full commit hash to check out instead of the branch’s head.
spec.manifest.repository.url
Type: string. Required.
Clone URL or local path of the repository. It can’t contain credentials.
[spec.manifest.sync] table
Whether pushes to the manifest repository deploy. It applies to every preview, and to every environment that opted in and follows a branch without a pinned commit.
spec.manifest.sync.mode
Type: "off", "poll" or "webhook". Required.
"off": Deploy only when asked."poll": List the repository’s branch heads everyinterval_seconds."webhook": List the branch heads when GitHub reports a push.
spec.manifest.sync.interval_seconds
Type: integer of at most 4294967295. Only with mode = "poll". Default: 300.
Seconds between listings, from 60 to 86,400.
[spec.previews] table
Settings shared by every preview.
spec.previews.variables.<variable>
Type: boolean, integer or template. Optional.
The previews’ value of the variable <variable>. It replaces the [spec.variables] default, or declares a variable without one.
spec.previews.visibility
Type: "public" or "private". Default: "private".
The strictest visibility preview routes get. private keeps every route on the tailnet; public restricts nothing.
[[spec.routes]] table
An HTTP route: requests for a hostname go to a service, or get a redirect. A route sets either service and port, or redirect.
spec.routes[].hostname
Type: template. Required.
Hostname the route serves, such as notes.example.com, unique in the application. A wildcard such as *.example.com serves every name one label below example.com that no exact route claims.
spec.routes[].name
Type: string. Optional.
Name that selects the route in every environment and preview, e.g. piquelctl env url --route web. It is unique in the application and can’t reference variables.
spec.routes[].port
Type: integer from 1 to 65535. Optional.
Port the service serves HTTP on, from 1 to 65535. Needs service.
spec.routes[].redirect
Type: table. Optional.
Redirect the gateway answers with, instead of a service.
spec.routes[].service
Type: string. Optional.
Service of this application that receives the requests. Needs port.
spec.routes[].visibility
Type: "public" or "private". Default: "private".
Who may connect: public for the internet, or private for the tailnet only. The environment’s or the previews’ visibility can make it stricter, never looser.
[spec.routes.redirect] table
A redirect the gateway answers with.
spec.routes[].redirect.preserve_path
Type: boolean. Default: true.
Whether to append the request’s path and query to to.
spec.routes[].redirect.status
Type: 301, 302, 303, 307 or 308. Default: 308.
HTTP status of the redirect.
spec.routes[].redirect.to
Type: template. Required.
Absolute http or https URL to redirect to, with a lowercase hostname and no query or fragment. It can’t target a hostname the route serves.
[[spec.secrets]] table
A secret whose value piqueld generates for each environment when one of its deployments first needs it. Later deployments and manifest edits keep that value; piquelctl env secret regenerate replaces it. A value is never shared with another environment.
spec.secrets[].generate
Type: table. Required.
How piqueld generates the value.
spec.secrets[].name
Type: string. Required.
Name of the secret, unique in the application. It can’t reference variables.
[spec.secrets.generate] table
How piqueld generates a secret’s value.
spec.secrets[].generate.type
Type: "random" or "rsa". Required.
"random": Random bytes from the operating system, encoded as text."rsa": An RSA private key, in PKCS#8 PEM.
spec.secrets[].generate.bits
Type: integer of at most 65535. Required with type = "rsa".
Size of the key in bits: 2048, 3072 or 4096.
spec.secrets[].generate.bytes
Type: integer of at most 65535. Required with type = "random".
Number of random bytes before encoding, from 16 to 512.
spec.secrets[].generate.encoding
Type: "hex" or "base64url". Only with type = "random". Default: "hex".
Text encoding of the bytes: lowercase hex, or unpadded base64url.
[[spec.services]] table
A service: containers running one image, kept at their replica count.
spec.services[].arguments
Type: array of templates. Optional.
Arguments that replace the image’s default arguments, at most 128 elements of 4,096 bytes each.
spec.services[].command
Type: array of templates. Optional.
Command that replaces the image’s entrypoint, at most 128 elements of 4,096 bytes each. When empty, the image’s entrypoint runs.
spec.services[].depends_on
Type: array of strings. Optional.
Services of this application that must be running and healthy before this one rolls out, each listed once.
spec.services[].environment.<name>
Type: template. Optional.
The environment variable <name> of the service’s containers. Names use letters, digits and _, don’t start with a digit, and are at most 255 bytes. Values are at most 65,536 bytes. At most 256 variables; PIQUELD_INGRESS_PROXIES is reserved.
spec.services[].files
Type: array of tables. Optional.
Read-only files mounted into the containers, at most 32. Their contents are never rendered with variables. An application’s files total at most 2 MiB.
spec.services[].healthcheck
Type: table. Optional.
How Docker checks that a container is healthy. Rollouts and the services depending on this one wait until it passes.
spec.services[].mounts
Type: array of tables. Optional.
Volumes mounted into the containers, at most 32.
spec.services[].name
Type: string. Required.
Name of the service, unique in the application. The application’s other services reach it by this name.
spec.services[].receives_telemetry
Type: boolean. Default: false.
Whether the service receives the daemon’s traces, metrics and logs, on a socket in /run/piqueld/telemetry, once its environment is granted telemetry. At most one service of an application receives telemetry, with one replica.
spec.services[].replicas
Type: integer of at most 65535 or typed template. Default: 1.
Number of containers, from 1 to 100.
spec.services[].resources
Type: table. Optional.
CPU and memory limits of each container.
spec.services[].rollout
Type: table. Optional.
How Docker replaces the service’s containers on each deployment.
spec.services[].secrets
Type: array of tables. Optional.
Secrets mounted as files, at most 64.
spec.services[].source
Type: table. Required.
Where the service’s image comes from: a prebuilt image, or a Git build.
[[spec.services.files]] table
A read-only file mounted into a service’s containers, from exactly one source: path in the manifest’s repository, or inline content. Its content can’t be empty, and is at most 500 KiB.
spec.services[].files[].content
Type: string. Required unless path is set.
The file’s content, inline.
spec.services[].files[].mode
Type: file mode. Default: "0444".
Octal permissions, from "0000" to "0777". The file is owned by root.
spec.services[].files[].path
Type: string. Required unless content is set.
Path of a UTF-8 text file in the manifest’s repository, relative to its root, read at the commit the manifest was read from. Only repository-backed applications can use it.
spec.services[].files[].target
Type: string. Required.
Absolute path of the file in the container, unique among the service’s mount, secret and file targets. It can’t be in /run/secrets or /run/piqueld.
[spec.services.healthcheck] table
How Docker checks that a service’s containers are healthy.
spec.services[].healthcheck.type
Type: "http" or "command". Required.
"http": Send an HTTPGETto a port of the container. A 2xx or 3xx status passes. The image needs nothing for it."command": Run a command in the container, without a shell. Exit code 0 passes.
spec.services[].healthcheck.command
Type: array of templates. Required with type = "command".
Command and arguments to run. It can’t be empty.
spec.services[].healthcheck.interval_seconds
Type: integer of at most 4294967295 or typed template. Default: 10.
Seconds between checks, from 1 to 3,600.
spec.services[].healthcheck.path
Type: template. Only with type = "http". Default: "/health".
Absolute HTTP path to request.
spec.services[].healthcheck.port
Type: integer of at most 65535 or typed template. Required with type = "http".
Container port to request, from 1 to 65535.
spec.services[].healthcheck.retries
Type: integer of at most 4294967295 or typed template. Default: 3.
Consecutive failed checks that make a container unhealthy, from 1 to 100.
spec.services[].healthcheck.start_period_seconds
Type: integer of at most 4294967295 or typed template. Default: 0.
Seconds after a container starts during which failed checks don’t count, up to 3,600.
spec.services[].healthcheck.timeout_seconds
Type: integer of at most 4294967295 or typed template. Default: 3.
Seconds a check may take before it fails, from 1 to the interval.
[[spec.services.mounts]] table
A volume mounted into a service’s containers.
spec.services[].mounts[].read_only
Type: boolean. Default: false.
Whether the containers mount the volume read-only. A writable mount makes rollouts stop the old container before starting its replacement.
spec.services[].mounts[].target
Type: string. Required.
Absolute path of the mount in the container, unique in the service. It can’t be /run/piqueld/probe or /run/piqueld/telemetry, or a path inside them.
spec.services[].mounts[].volume
Type: string. Required.
Name of a volume in spec.volumes.
[spec.services.resources] table
CPU and memory limits of each of a service’s containers. Set at least one.
spec.services[].resources.cpu_millis
Type: integer of at most 4294967295 or typed template. Optional.
CPU limit in thousandths of a CPU, from 1 to 1,048,576: 500 is half a CPU.
spec.services[].resources.memory_bytes
Type: integer of at most 18446744073709551615 or typed template. Optional.
Memory limit in bytes, from 1 to 9,223,372,036,854,775,807.
[spec.services.rollout] table
How Docker replaces a service’s containers during a deployment, one at a time. An empty block keeps the defaults.
spec.services[].rollout.monitor_seconds
Type: integer of at most 4294967295 or typed template. Optional.
Seconds Docker watches each new container for failure before it replaces the next one, from 1 to 3,600. 30 when unset.
spec.services[].rollout.order
Type: "stop-first", "start-first" or typed template. Optional.
stop-first stops the old container before starting its replacement, with a short downtime. start-first starts the replacement first, so both briefly run side by side. When unset, stop-first if the service mounts a volume writable or receives telemetry, start-first otherwise.
[[spec.services.secrets]] table
A secret mounted as a file. A name spec.secrets declares mounts the environment’s generated value; any other name mounts a value from the application’s secret store.
spec.services[].secrets[].name
Type: template. Required.
Name of the secret. It may reference variables, so each environment can mount its own stored secret, e.g. ${{ vars.stripe_key }}.
spec.services[].secrets[].target
Type: string. Required.
Absolute path of the file under /run/secrets/, unique in the service.
[spec.services.source] table
Where a service’s image comes from.
spec.services[].source.type
Type: "image" or "git". Required.
"image": Pull a prebuilt image from a registry."git": Build the image from a Git repository.
spec.services[].source.build
Type: table. Required with type = "git".
How to build the image.
spec.services[].source.image
Type: template. Required with type = "image".
Image reference, such as ghcr.io/example/notes:1.4.0, with an optional tag or digest. It can’t contain a URL scheme or credentials.
spec.services[].source.repository
Type: "self" or table. Required with type = "git".
Repository to build: "self" for the manifest’s own repository, at the commit the manifest was read from, or a table naming another one. "self" needs spec.manifest.
[spec.services.source.build] table
How to build a Git source’s image.
spec.services[].source.build.type
Type: "docker". Required.
"docker": Build the image with Docker Buildx, from a Dockerfile.
spec.services[].source.build.args.<name>
Type: template. Optional.
The value of the build argument <name>, passed with --build-arg. Docker records it in the image’s metadata, so pass sensitive values as secrets instead. Build arguments total at most 256 KiB.
spec.services[].source.build.context
Type: template. Default: ".".
Build context directory, relative to the repository root.
spec.services[].source.build.dockerfile
Type: template. Required.
Path of the Dockerfile, relative to the repository root.
spec.services[].source.build.target
Type: template. Optional.
Stage of a multi-stage Dockerfile to build. By default, the final stage.
[spec.services.source.repository] table
A Git repository and the revision to check out. Git uses the host’s credentials.
spec.services[].source.repository.branch
Type: string. Required.
Branch whose head is checked out when no commit is set.
spec.services[].source.repository.commit
Type: string. Optional.
Full commit hash to check out instead of the branch’s head.
spec.services[].source.repository.url
Type: string. Required.
Clone URL or local path of the repository. It can’t contain credentials.
[[spec.volumes]] table
A named volume the services mount. Its data is kept across deployments, and when the application is deleted. A preview’s volumes are deleted with the preview.
spec.volumes[].name
Type: string. Required.
Name of the volume, unique in the application.
Value types
File mode
Type: string.
Octal file permissions from 0000 to 0777, written as text such as "0444" or "644".
Template
Type: string.
Text that may contain ${{ namespace.name }} references, with optional whitespace inside the braces. $${{ writes a literal ${{; ${VAR} and $VAR are ordinary text, left for shells and applications to expand.
"${{ vars.domain }}" -> the value of `domain`
"api.${{vars.domain}}" -> "api." followed by the value of `domain`
"$${{ vars.domain }}" -> "${{ vars.domain }}", literally
Typed template
Type: string.
A template in a setting of another type, such as an integer: text containing a ${{ reference. A template that is exactly one reference takes the variable’s own value, which must have the setting’s type; strings are never parsed into numbers. For example, with replicas = "${{ vars.replicas }}", the variable replicas must be the integer 2, not the string "2".