cro-yml
The .cro.yml File
Purpose
The .cro.yml
file is stored in the root directory of a service. It provides
some metadata about the service that is used in combination with the cro
development tool (both the CLI and the web version). It is intended that, if
used, the file is committed to version control.
The .cro.yml
file is only used by the cro
development tool. It is not
required for the correct operation of the service, and need not be included
when the service is deployed (the .dockerignore
generated when stubbing the
service excludes it from the container).
Basic Information
The .cro.yml
file should be a dictionary at the top level. It must include:
The key
cro
with a value of1
. This will allow for versioning of the file as Cro evolves.The key
id
, followed by an ID for the service. The value may contain the letters A..Z and a..z, the digits 0..9, the underscore (_
), the dash (-
) and the forward slash ('/'). This will be used to identify the service when using the CLI (such as incro run service-id
).The key
entrypoint
, which is the Raku source file that should be run to start the service. It should be specified relative to the.cro.yml
file. This will be used by thecro
development tool to start the service.
It may optionally include:
The key
name
, which provides a human-friendly name for the service. This will be displayed in the web UI. If not provided, theid
will be used in its place.
For example:
cro: 1
id: flashcard-backend
name: Flashcards Backend
entrypoint: service.raku
Endpoints
An endpoint is something exposed by a service for services or applications to connect to. Most often, it's a network port. The stub services produced by Cro do not hard-code a port number, but instead take it from an environment variable.
Endpoints are specified as a list under the endpoints
key. For example, a
service that accepts both HTTP and HTTPS would look as follows:
endpoints:
- id: http
name: HTTP (Insecure)
protocol: http
host-env: FLASHCARD_BACKEND_HTTP_HOST
port-env: FLASHCARD_BACKEND_HTTP_PORT
- id: https
name: HTTP (Secure)
protocol: https
host-env: FLASHCARD_BACKEND_HTTPS_HOST
port-env: FLASHCARD_BACKEND_HTTPS_PORT
The id
is used to identify the endpoint in commands and when referencing it
from other services. The name
is for display in the user interface; it is
optional and will default to the id
. The protocol
describes the protocol
that the endpoint speaks; this is used when stubbing code to call the service
from another service. Protocols include:
https
- HTTP/1.1 and/or HTTP/2.0 secure (negotiated using ALPN)http
- HTTP/1.1 insecurehttp2
- HTTP/2.0 insecure (starts HTTP/2 by prior knowledge)wss
- web socket securews
- web socket insecurezeromq/rep
- ZeroMQREP
(generated client would be aREQ
)zeromq/pub
- ZeroMQPUB
(generated client would be aSUB
)
It is allowed to write multiple protocols with a comma. This is mostly useful
when an endpoint handles both HTTP and web sockets (securely as https,wss
or
insecurely as http,ws
).
The host-env
and port-env
fields name environment variables that will be
populated with the host and port that the endpoint should be hosted on.
Links
The links
section describes which other Cro services this one references. It
is used for cro run
and cro trace
(or running/tracing the services in the
web interface) to inject environment variables indicating the host and port of
the other endpoints. The environment variables can then instead be supplied by
configuration management, Kubernetes, and so forth when deploying the service.
A links
section might look like:
links:
- service: flashcard-backend
endpoint: https
host-env: FLASHCARD_BACKEND_HTTPS_HOST
port-env: FLASHCARD_BACKEND_HTTPS_PORT
- service: users
endpoint: https
host-env: USERS_HTTPS_HOST
port-env: USERS_HTTPS_PORT
Where service
is the ID of the service (defined by id
in its .cro.yml
),
endpoint
is the ID of the endpoint (from the target service's .cro.yml
's
endpoints
section), and env
is the environment variable specifying the
host and port in the form host:port
.
Environment
Services will usually need other resources, such as database connections,
addresses of non-Cro services, and (development fake) security credentials. It
may be convenient to inject these using the environment. The env
section
provides a way to set environment variables that will be passed to the
service. This is a handy way to store development configuration and cut down
a little of the setup work needed when other developers want to get the
services running.
env:
- name: FLASH_DATABASE
value: test-database.internal:6555
- name: JWT_SECRET
value: my-dev-not-so-secret
Controlling automatic restarts
By default, cro run
and cro web
will automatically restart the service
when a file changes in any directory beneath where the .cro.yml
is located.
All hidden files and directories are ignored by default (those starting with a
.
, for example .precomp/
and .git/
directories).
To add extra directories to ignore, create an ignore
section with a list of
patterns in the .cro.yml
file. These are processed like .gitignore
. For
example:
ignore:
- node_modules/