architect.yml

This document describes the full specification of the architect.yml configuration file. The top level of your architect.yml should be a ComponentSpec.

We’ve published a formal definition of this specification here: Architect JSONSchema.

For users of Visual Studio Code, check out the Architect extension!

If you’re using an IDE with intellisense backed by SchemaStore, then you may already see syntax highlighting when editing any file named architect.yml.

Note: all references to the Dict<T> type below refer to a key-value map where the keys are strings and the values are of type T.

ComponentSpec

The top level object of the architect.yml; defines a deployable Architect Component.

Field (*=required)TypeDescriptionMisc
name*stringGlobally unique friendly reference to the component. must contain only lower alphanumeric and single hyphens in the middle; max length 32Must match: Regex
descriptionstringA human-readable description of the component. This will be rendered when potential consumers view the component so that they know what it should be used for.
keywordsArray<string>Additional search terms to be used when the component is indexed so that others can find it more easily.
authorstringThe name or handle of the author of the component as a developer contact.
homepagestringThe url that serves as the informational homepage of the component (i.e. a github repo).
secretsDict<string>A map of named, configurable fields for the component. If a component contains properties that differ across environments (i.e. environment variables), you’ll want to capture them as secrets. Specifying a primitive value here will set the default secret value. For more detailed configuration, specify a SecretDefinitionSpecKeyRegex, ValueRegex,
outputsDict<string>A map of named, configurable outputs for the component. Outputs allow components to expose configuration details that should be shared with consumers, like API keys or notification topic names.KeyRegex, ValueRegex,
databasesDict<string>A database represents a stateful service powered by one of several supported database engines.KeyRegex, ValueRegex,
servicesDict<string>A Service represents a non-exiting runtime (e.g. daemons, servers, etc.). Each service is independently deployable and scalable. Services are 1:1 with a docker image.KeyRegex, ValueRegex,
tasksDict<string>A set of named recurring and/or exiting runtimes (e.g. crons, schedulers, triggered jobs) included with the component. Each task will run on its specified schedule and/or be triggerable via the Architect CLI. Tasks are 1:1 with a docker image.KeyRegex, ValueRegex,
dependenciesDict<string>A key-value set of dependencies and their respective tags. Reference each dependency by component name (e.g. cloud: latest)KeyRegex, ValueRegex,
interfacesDict<string>A set of named gateways that broker access to the services inside the component. All network traffic within a component is locked down to the component itself, unless included in this interfaces block. An interface represents a front-door to your component, granting access to upstream callers.KeyRegex, ValueRegex, Deprecated
artifact_imagestring-Deprecated

ServiceSpec

A runtimes (e.g. daemons, servers, etc.). Each service is independently deployable and scalable. Services are 1:1 with a docker image.

Field (*=required)TypeDescriptionMisc
enabledbooleanDetermines if the service should be running.default: true
debugPartial<ServiceSpec>A partial object that is deep-merged into the spec on local deployments. Useful to mount developer volumes or set other local-development configuration. Think of this as a “local override” block.
interfacesDict<string>A set of named interfaces to expose service functionality over the network to other services within the same component. A string or number represents the TCP port that the service is listening on. For more detailed configuration, specify a full ServiceInterfaceSpec object.KeyRegex, ValueRegex,
liveness_probeLivenessProbeSpec
volumesDict<string>A set of named volumes to be mounted at deploy-time. Take advantage of volumes to store data that should be shared between running containers or that should persist beyond the lifetime of a container.KeyRegex, ValueRegex,
replicasinteger | ExpressionA static number of replicas of a service to be deployed. For scaling configuration, see scaling field.
scalingScalingSpec
deployDeploySpec
termination_grace_periodstring | ExpressionA period of time between a service being passed a SIGINT and a SIGTERM when it’s scheduled to be replaced or terminated. Only used for remote deployments.default: 30s
descriptionstringHuman readable description
imagestring | ExpressionThe docker image that serves as the unit of runtime. This field is disjunctive with build (only one of image or build can be set)
commandArray<string> | string | ExpressionThe docker startup command. Use this if you need to override or parameterize or parameterize the docker image command.
entrypointArray<string> | string | ExpressionThe docker entrypoint for the container. Use this if you need to override or parameterize the docker image entrypoint.
languagestringThe dominant programming language used; this is for informational purposes only.
environmentDict<string>A set of key-value pairs or secret definitions that describes environment variables and their values.KeyRegex, ValueRegex, More
buildBuildSpec
cpunumber | ExpressionThe cpu required to run a service or a taskMore
memorystring | ExpressionThe memory required to run a service or a task.More
depends_onArray<string>An array of service names for those services in the component that are pre-requisites to deploy. Used at deploy-time to build a deploy order across services and tasks.
labelsDict<string>A simple key-value annotation store; useful to organize, categorize, scope, and select services and tasks.KeyRegex, ValueRegex, More
reserved_namestringA specific service name which will override the service name specified in the component.Must match: Regex

SecretDefinitionSpec

Components can define configurable secrets that can be used to enrich the contained services with environment-specific information (i.e. environment variables).

Field (*=required)TypeDescriptionMisc
requiredbooleanDenotes whether the secret is required.
descriptionstringA human-friendly description of the secret.
defaultArray<any> | boolean | number | object | string | null | ExpressionSets a default value for the secret if one is not provided

ComponentInterfaceSpec

Component Interfaces are the primary means by which components advertise their resolvable addresses to others. Interfaces are the only means by which other components can communicate with your component.

Field (*=required)TypeDescriptionMisc
ingressIngressSpec
descriptionstringA human-readable description of the component. This will be rendered when potential consumers view the interface so that they know what it should be used for.
hoststringThe host that the component interface should forward to.
portnumber | ExpressionThe port that the component interface should forward to.
protocolstring | ExpressionThe protocol by which the component interface can be connected to.
usernamestring | ExpressionThe Basic Auth username by which a component interface can be connected to.
passwordstring | ExpressionThe Basic Auth password by which a component interface can be connected to.
url*string | ExpressionThe url that the component interface should forward to.
stickyboolean | ExpressionIf this interface is made into an external ingress, sticky=true will denote the gateway should use sticky sessions if more than one replica is running.

TaskSpec

A Task represents a recurring and/or exiting runtime (e.g. crons, schedulers, triggered jobs). Each task will run on its specified schedule and/or be triggerable via the Architect CLI. Tasks are 1:1 with a docker image.

Field (*=required)TypeDescriptionMisc
debugPartial<TaskSpec>A partial object that is deep-merged into the spec on local deployments. Useful to mount developer volumes or set other local-development configuration. Think of this as a “local override” block.
schedulestring | ExpressionA cron expression by which this task will be scheduled. Leave blank to deploy a task that never runs unless triggered from the CLI.
descriptionstringHuman readable description
imagestring | ExpressionThe docker image that serves as the unit of runtime. This field is disjunctive with build (only one of image or build can be set)
commandArray<string> | string | ExpressionThe docker startup command. Use this if you need to override or parameterize or parameterize the docker image command.
entrypointArray<string> | string | ExpressionThe docker entrypoint for the container. Use this if you need to override or parameterize the docker image entrypoint.
languagestringThe dominant programming language used; this is for informational purposes only.
environmentDict<string>A set of key-value pairs or secret definitions that describes environment variables and their values.KeyRegex, ValueRegex, More
buildBuildSpec
cpunumber | ExpressionThe cpu required to run a service or a taskMore
memorystring | ExpressionThe memory required to run a service or a task.More
depends_onArray<string>An array of service names for those services in the component that are pre-requisites to deploy. Used at deploy-time to build a deploy order across services and tasks.
labelsDict<string>A simple key-value annotation store; useful to organize, categorize, scope, and select services and tasks.KeyRegex, ValueRegex, More
reserved_namestringA specific service name which will override the service name specified in the component.Must match: Regex

DatabaseSpec

Component databases let you quickly spin up a database for your service

Field (*=required)TypeDescriptionMisc
descriptionstringHuman readable description
type*string | ExpressionThe type engine and version of database software needed for data storage.
connection_stringstring | null | ExpressionThe connection uri of an existing database to use instead of provisioning a new one

LivenessProbeSpec

Configuration for service health checks. Architect uses health checks are used for load balancing and rolling updates.

Field (*=required)TypeDescriptionMisc
success_thresholdnumber | ExpressionThe number of times to retry a health check before the container is considered healthy.default: 1
failure_thresholdnumber | ExpressionThe number of times to retry a failed health check before the container is considered unhealthy.default: 3
timeoutstring | ExpressionThe time period to wait for a health check to succeed before it is considered a failure. You may specify any value between: 2s and 60sdefault: 5s
intervalstring | ExpressionThe time period in seconds between each health check execution. You may specify any value between: 5s and 300sdefault: 30s
initial_delaystring | ExpressionDelays the check from running for the specified amount of timedefault: 0s
pathstring | Expression[Deprecated: use command instead.] Path for the http check executable. Path should be absolute (e.g. /health). If path is set, port also must be set. This field is disjunctive with command (only one of path or command can be set).Deprecated
commandArray<string> | stringCommand that runs the http check. This field is disjunctive with path and port (only one of command or path/port can be set).
portnumber | Expression[Deprecated: use command instead.] Port that the http check will run against. If port is set, path also must be set. This field is disjunctive with command (only one of port or command can be set).Deprecated

VolumeSpec

Architect can mount volumes onto your services and tasks to store data that should be shared between running containers or that should persist beyond the lifetime of a container.

Field (*=required)TypeDescriptionMisc
mount_pathstring | ExpressionDirectory at which the volume will be mounted inside the container.
host_pathstring | ExpressionA directory on the host machine to sync with the mount_path on the docker image. This field is only relevant inside the debug block for local deployments. This field is disjunctive with key (only one of host_path or key can be set).
keystring | ExpressionA reference to the underlying volume on the deployment cluster of choice. The docker-compose volume name, the name of the Kubernetes PersistentVolumeClaim, or the EFS ID of an AWS volume. This field is disjunctive with host_path (only one of key or host_path can be set).More
descriptionstringHuman-readable description of volume
readonlyboolean | ExpressionMarks the volume as readonly.

BuildSpec

An object containing the details necessary for Architect to build the service via Docker. Whenever a service that specifies a build field is registered with Architect, the CLI will trigger a docker build and replace the build field with a resolvable image.

Field (*=required)TypeDescriptionMisc
contextstring | ExpressionThe path to the directory containing the source code relative to the architect.yml file.
buildpackbooleanOption to use buildpack to build an image.
argsDict<string>Build args to be passed into docker build.KeyRegex, ValueRegex,
dockerfilestring | ExpressionThe path to the Dockerfile relative to the build.contextdefault: Dockerfile
targetstring | ExpressionThe stage to build in the Dockerfile

IngressSpec

An ingress exposes an interface to external network traffic through an architect-deployed gateway.

Field (*=required)TypeDescriptionMisc
enabledbooleanMarks the interface as an ingress.
subdomainstring | ExpressionThe subdomain that will be used if the interface is exposed externally. Use subdomain: @ to target the base domain.
pathstring | ExpressionThe path of the interface used for path based routing
ip_whitelistArray<string | string> | ExpressionIP addresses that are allowed to access the interface
privateboolean | ExpressionMarks the ingress as private behind Architect authentication

ScalingMetricsSpec

Scaling metrics define the upper bound of resource consumption before spinning up an additional replica.

Field (*=required)TypeDescriptionMisc
cpuinteger | ExpressionThe cpu usage required to trigger scaling.More
memoryinteger | ExpressionThe memory usage required to trigger scaling.More

ScalingSpec

Configuration that dictates the scaling behavior of a service.

Field (*=required)TypeDescriptionMisc
min_replicas*integer | ExpressionThe target minimum number of service replicas.
max_replicas*integer | ExpressionThe target maximum number of service replicas.
metrics*ScalingMetricsSpec

KubernetesDeploySpec

Configuration that dictates the kubernetes deploy overrides.

Field (*=required)TypeDescriptionMisc
deployment*

DeploySpec

Configuration that dictates the deploy overrides.

Field (*=required)TypeDescriptionMisc
kubernetes*KubernetesDeploySpec

ServiceInterfaceSpec

A service interface exposes service functionality over the network to other services within the same component. If you would like to expose services on the network to external components, see the ComponentInterfaceSpec

Field (*=required)TypeDescriptionMisc
descriptionstring | ExpressionA human-readable description of the interface.
hostnull | string | ExpressionThe host address of an existing service to use instead of provisioning a new one. Setting this field effectively overrides any deployment of this service and directs all traffic to the given host.
port*number | ExpressionPort on which the service is listening for traffic.
protocolstring | ExpressionProtocol that the interface responds todefault: http
usernamenull | string | ExpressionA Basic Auth username required to access the interface
passwordnull | string | ExpressionA Basic Auth password required to access the interface
pathstring | ExpressionThe path of the interface
urlstring | ExpressionThe url of an existing service to use instead of provisioning a new one. Setting this field effectively overrides any deployment of this service and directs all traffic to the given url.
stickyboolean | ExpressionDenotes that if this interface is made external, the gateway should use sticky sessions
ingressIngressSpec

OutputDefinitionSpec

Components can define output fields that can be used to share configuration with consuming components.

Field (*=required)TypeDescriptionMisc
descriptionstringA human-friendly description of the output field.
value*Value of the output to be passed to upstream consumers