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/