Services
Each service described in an architect.yml
file will automatically be deployed
to its own horizontally scaling replica with load balancing seamlessly between
instances.
name: my-component
services:
my-api:
build:
context: ./path/to/docker/build/context
dockerfile: ./relative/to/context/Dockerfile
command: npm start
entrypoint: entrypoint override for dockerfile ENTRYPOINT
environment:
DB_ADDR: rds.amazonwebservices.com/db-name
DB_USER: postgres
DB_PASS: password
interfaces:
public:
port: 8080
protocol: http
admin: 8081
labels:
architect.io/environment: dev
architect.io/service: api
liveness_probe:
command: curl --fail localhost:8080/health
replicas: 2
cpu: 1
memory: 512mb
# Local configuration for my-api service
debug:
command: npm run dev
volumes:
src:
host_path: ./src/
mount_path: /usr/app/src/
Configuration options
build
(optional) 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.
build:
# The path to the directory containing the source code relative to the architect.yml file
context: ./
# The path to the Dockerfile relative to the build.context (default: Dockerfile)
dockerfile: Dockerfile
image
fieldUsing buildpack
Buildpack is currently in alpha. While the feature should be stable, it may be changed or removed without prior notice. As such we do not recommend using this feature in any automated pipelines. During this time we greatly appreciate any feedback as we continue to finalize the implementation. You can reach us at support@architect.io. If a
Dockerfile
is not found in the directory in which thecontext
field is set, the CLI by default will trigger a Cloud Native Buildpacks builder to build an image of the service. A builder is an image that detects and converts source code into a runnable container image.
If the application contains a Dockerfile
but a builder should be used instead, set the field buildpack
to true
.
build:
# The path to the directory containing the source code relative to the architect.yml file
context: ./
# Use buildpack to build the service
buildpack: true
Architect buildpack
is in its early development stage and is currently an experimental feature. The version of the builder image is heroku/buildpacks:20
. This builder version only supports languages such as Java, Go, Node.js, PHP, Python, Ruby, Scala, and Typescript. Learn more about Heroku’s builder.
Depending on the language that the application is written in, there might be some requirements in order to build successfully. For example, if an application is written in Java, only these supported Java versions can be used. After selecting a Java version, a system.properties
might be required at the root of the application for the builder to use the correct Java runtime version.
For more information on the language support of Heroku, please refer to Heroku language support.
image
fieldimage
image (optional) A string referencing the address of an existing docker image that powers this service.
build
fieldcommand
(optional) A string or string[] specifying the command to be used to start up
the service inside the container. If no value is specified, the default CMD
from the associated image will be used.
entrypoint
(optional) A string or string[] specifying the entrypoint to be used to start up
the service inside the container. If no value is specified, the default
ENTRYPOINT
from the associated image will be used.
interfaces
A dictionary containing a set of named interfaces that the service listens for requests on. Each interface must at minimum specify the port it is listening for requests on.
interfaces:
public:
# (required) Port that the service is listening for traffic on
port: 8080
# (optional) Protocol that the interface responds to (default: http)
protocol: http
# (optional) The host address of an existing service to use instead of provisioning a new one
host: rds.amazonwebservices.com
# (optional) A basic auth username required to access the interface
username: ${{ secrets.API_USERNAME }}
# (optional) A basic auth password required to access the interface
password: ${{ secrets.API_PASSWORD }}
# (optional) Specific path that the service is listening on
path: /api
# (optional) Ingress rules
ingress:
subdomain: api
# (optional) Specific path that the service is listening on externally
path: /
To learn about how to expose your services see ingress rules.
Since many services use http for traffic, interfaces also support a simple short-hand for specifying the service port:
interfaces:
public: 8080
Overriding service hosts
Architect supports overriding a service with the URL of an external host. When this is done, the service will not be created by Architect, but all of the interpolated values of the service will continue to be produced. This is a common pattern in cases where a user wants Architect to manage everything for local development, but wants to reference a managed service such as a database instance for staging or production. For example, the service below represents a Postgres database service that can be either managed by Architect or effectively an external reference:
---
secrets:
postgres_host:
required: false
---
services:
api-db:
image: postgres:11
interfaces:
postgres:
host: ${{ secrets.postgres_host }}
port: 5432
protocol: postgresql
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: architect
POSTGRES_DB: architect_postgres_db
The secret postgres_host
will determine whether or not the service will be
provisioned by Architect. If postgres_host
is not set, Architect will
provision the api-db
service and create a postgres:11
container. If the
postgres_host
secret is set, image: postgres:11
will be ignored and the
container will not be provisioned by Architect. Any interpolated values that
include the api-db
service will produce the correct output in either instance
with the difference being that ${{ services.api-db.interfaces.postgres.host }}
and ${{ services.api-db.interfaces.postgres.url }}
will change based on the
host
of the interface. Note that if a service has multiple interfaces and you
would like to reference an external service, all of the Architect service’s
interfaces must specify the host
override.
Cusomt SSL Certificates (EXPERIMENTAL)
By default the Architect platform will provision SSL certificates for your website using Let’s Encrypt. However, sometimes you may wish to provide your own SSL certificates. To do this we you can specify them as part of the service.
---
secrets:
api_crt:
required: true
api_key:
required: true
api_ca:
required: true
---
services:
api-db:
image: postgres:11
interfaces:
entrypoint:
port: 8080
ingress:
subdomain: entrypoint
tls:
crt: '${{ secrets.api_crt }}'
key: '${{ secrets.api_key }}'
ca: '${{ secrets.api_ca }}'
The tls
subsection of the ingress allows you to specify an SSL certificate. The crt
field is the signed certificate and the key
is the private key used to encrypt the data from the server. The ca
field is an optional field. When set this will override the which CA root certificate will be used to authenticate connections with the server. Primarly this should only be set when trying to limit which connections should be allowed to this server.
(NOTE): While you do specify a custom SSL certificate on an ingress, the certificate will be used for all matching domain names. So if you have a wild card certificate, then all domains that match the wildcard will use the same certificate.
labels
Dictionary of string keys and values that can be used to organize and categorize (scope and select) the service.
Syntax and character set Labels are key/value pairs. Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 63 characters in total, followed by a slash (/).
Valid label value: must be 63 characters or less (can be empty), unless empty, must begin and end with an alphanumeric character ([a-z0-9A-Z]), could contain dashes (-), underscores (_), dots (.), and alphanumerics between.
liveness_probe
This configuration is essentially the health check for the service. It’s important to specify so that traffic isn’t load balanced to unhealthy services. Critical for rolling updates to function properly.
liveness_probe:
# (required) Command that will be run to check application health
command: curl --fail localhost:8080/health
# (deprecated, optional) Port that the http check will run against
port: 8080
# (deprecated, optional) Path for the http check
path: /health
# (optional, defaults to 0s) Delays the check from running for the specified amount of time
initial_delay: 0s
# (optional, defaults to 30s) The time period in seconds between each health check execution. You may specify between 5 and 300 seconds.
interval: 30s
# (optional, defaults to 5s) The time period in seconds to wait for a health check to succeed before it is considered a failure. You may specify between 2 and 60 seconds.
timeout: 5s
# (optional, defaults to 1) The number of times to retry a health check before the container is considered healthy.
success_threshold: 1
# (optional, defaults to 1) The number of times to retry a failed health check before the container is considered unhealthy. You may specify between 1 and 10 retries.
failure_threshold: 1
environment
A key-value store of environment variables to be injected into the service runtime.
environment:
NODE_ENV: dev
STRIPE_API_KEY: abc-123
volumes
(optional) A dictionary containing a set of named volumes that the service will request and mount to each service instance. Architect can take advantage of volumes to store data that should be shared between running containers or that should persist beyond the lifetime of a container.
Local configuration
If you would like to use the local filesystem as a volume or a docker-compose
volume, use the options below in the debug block of your service:
volumes:
my-volume-name:
# Directory at which the volume will be mounted inside the container
mount_path: /usr/app/images
# (optional) Human-readable description of volume
description: Description of my volume
# (optional) A directory on the host machine to sync with the mount_path on the docker image.
# This is primarily used for local debugging
host_path: ./relative/to/architect.yml
# (optional) The name of a `docker-compose` volume that has already been created on the host machine.
key: my-compose-volume-name
cpu & memory
cpu
: a whole number or decimal that represents the vCPUs allocated to the
service when it runs.
cpu: 1
memory
: a string that represents the memory allocated to the service when it
runs.
memory: 2GB
depends_on
depends_on
takes an array of references to other services within the
component. These dictate startup order: at deployment time, services will not be
started until any of their listed dependents have already started.
services:
app: # here, app will not start until my-api and db have started
depends_on:
- my-api
- db
interfaces:
postgres: 5432
my-api: # here, my-api will not start until db has started
depends_on:
- db
interfaces:
admin: 8081
db:
interfaces:
postgres: 5432
replicas
(optional) The number of replicas the service should have when it’s deployed. This number will apply across environments unless overridden by an environment-specific setting.
replicas: 4
Local development
When developing your service locally you may want to mount volumes or alter the command that is used in remote environments. Learn more about how to specify with local configuration.