Configure

The Request Manager (RM) and Job Runner (JR) binaries are configured with a YAML config file and environment variables. Configuration values are loaded in this order:

1. Built-in defaults
2. Config file
3. Environment variables

The built-in defaults are only sufficient to run a local development instance. You can compile the binaries and run them without any options, using only the built-in default configs.

For a production deploy, you must provide a YAML config file or environment variables to configure Spin Cycle to your infrastructure. These are the most important config values:

The RM and JR log the final config on startup.

Config File

Specifying

You can specify a config file when starting the RM and JR:

$ request-manager /etc/spincycle/rm-config.yaml

The RM reads /etc/spincycle/rm-config.yaml and fails to start if it does not exist or is invalid.

Else, by default, the RM and JR read config/<ENVIRONMENT>.yaml if environment variable ENVIRONMENT is set and equal to “development”, “staging”, or “production”. For example:

$ export ENVIRONMENT=production
$ request-manager

The RM reads config/production.yaml (relative to the current working directory). Unlike an explicit config file, an implicit config file does not need to exist. If it does not exist, built-in defaults or environment values are used.

Format

The config file is YAML with multiple sections: server, mysql, specs, etc. The config package documents each section. Note: struct field and YAML field names are different. YAML field names are lower-case and snake_case. Here is a partial example:

---
server:
  addr: 10.0.0.50:32308
  tls:
    cert_file: /secret/mycorp.crt
    key_file:  /secret/mycorp.key
    ca_file:   /secret/mycorp.ca
mysql:
  dsn: "spincycle@tcp(spin-mysql.local:3306)/spincycle_production"
specs:
  dir: /data/app/spin-rm/specs/
jr_client:
  url: https://spincycle-jr.mycorp.local:32307

Environment Variables

Most config options have a corresponding environment variable, like SPINCYCLE_RM_CLIENT_URL for rm_client.url. Exceptions are noted.

Take a config option, change . to _, upper-case everything, and add SPINCYCLE_ prefix.

Request Manager

auth.admin_roles: Callers with one of these roles are admins (allowed all ops) for all requests. (No environment variable.)

auth.strict: Strict requires all requests to have ACLs, else callers are denied unless they have an admin role. Strict is disabled by default which, with the default auth plugin, allows all callers (no auth). (No environment variable.)

jr_client.url: URL that Request Manager uses to connect to any Job Runner. If TLS enabled on JR, use “https” and configure TLS. In production, this is usually a load balancer address in front of N-many JR instances.

jr_client.tls: Enable TLS when RM connects to any JR at jr_client.url. See common TLS section below.

mysql.dsn: DSN specifying connection to MySQL. The DSN must specify the database, for example: /spincycle_production. Do use tls DSN parameter, specify the TLS config and Spin Cycle will add the tls DSN parameter automatically.

mysql.tls: Enable TLS connection to MySQL. See common TLS section below.

server.addr: Network address:port to listen on. To listen on all interfaces on the default port, specify “:32308”.

server.tls: Enable TLS for clients (users) and when JR connects to RM. See common TLS section below.

specs.dir: Directory containing all request spec files. Spin Cycle assumes all files in and under the specs directory ending with .yaml (case-insensitive) are spec files. The default is “specs/”, relative to current working dir.

Job Runner

rm_client.url: URL that Job Runner uses to connect to any Request Manager. If TLS enabled on RM, use “https” and configure TLS. In production, this is usually a load balancer address in front of N-many RM instances.

rm_client.tls: Enable TLS when JR connects to any RM at rm_client.url. See common TLS section below.

server.addr: Network address:port to listen on and to report to RM. This must be the address of the specific JR instance that RM can connect to. Do not use a load balancer address.

server.tls: Enable TLS for incoming connections from RM. See common TLS section below.

TLS

Several sections have a TLS section: server, jr_client, rm_client, and mysql. The TLS config at each section is separate, so there are potentially four different TLS configs.

To enable TLS, all three files for a section must be specified. For example, to enable mysql.tls, you must specify mysql.tls.cert_file, mysql.tls.key_file, and mysql.tls.ca_file.

tls.cert_file: Certificate key file

tls.key_file: Private key file

tls.ca_file: Certificate Authority file