Configuration Validation
The official Docker images include the ‘validate.py’ script, that let’s you validate your SCS configuration (for example inside a GIT repository) without secrets present.
1 Running validate.py
Like with the normal server, you only need to set the SCS_CONFIG_DIR
variable to the directory containing your ‘scs-configuration.yaml’. Optionally, you can add a ‘scs-validate.yaml’ configuration file to this directory, that defines configuration options for the validation script (See section 2 below)
The script is meant to be run from inside the official SCS docker container, to which you’ve either mounted your configuration using Docker volumes or bind-mounts, or from which you’ve build an image that includes your configuration.
An example of running the validation script in case of the latter, can be found in the GitHub Workflow for the example-configuration repository.
2 scs-validate.yaml Configuration File
An example of the contents of a ‘scs-validate.yaml’ file is provided below:
endpoints: # See section 1 below
/configs/cluster_name: false
/configs/custer_name_redirect:
request:
method: GET
response:
status: 301
headers:
Location: /configs/cluster_name
text: 'validate against this'
/configs/test.json:
response:
json:
validate: true
against: true
this: true
object: true
/configs/test.yaml:
response:
yaml:
validate: true
against: true
this: true
object: true
/configs/*.yml:
response:
format: yaml
headers:
Content-Type: application/x-yaml
scs_configuration: # See section 2 below
extensions:
constructors:
- name: scs.yaml.SCSSimpleValueConstructor
options:
tag: '!cloud-dependent-tag'
value: A default value to return for this tag
handle_errors: false
allow_secrets: false
The full schema for this file can be found here.
Since all properties in this file are optional, validate.py can also be run if this file is omitted. It will then use the default settings from the schema.
The handle_errors
property defines if internal errors should be handled or raised. In case you want to test if specific endpoints returns a 500 status code , set this to ‘true’.
Set allow_secrets
to true, in case the configuration you’re testing includes secrets. Note that this is not advised, and therefore this is set to ‘false’ by default.
2.1 Endpoints
The endpoints
property allows you to define test/validation configurations for one or more endpoints. Just like with the ‘from_paths’ of scs-users.yaml, wildcards can be used to define endpoints. Note that if ‘endpoints’ is omitted from the configuration, or if some endpoints are not defined under ‘endpoints’, these are validated using the default configuration (GET request; Response status code < 400). If you don’t want to validate an endpoint, you need to specifically disable it, by setting ‘false’ instead of an object.
In case an endpoint both matches a specific url in this configuration, as well as a pattern with a wildcard, both configurations are used, but settings in the longer pattern/url (more specfic) override settings in the shorter pattern/url(less specific). In the above example, /configs/test.yaml
matches both the general pattern /configs/*.yml
as well as the specific pattern /configs/test.yaml
. This means (1) the yaml format is validated (general pattern), (2) the Content-Type response header is validated (general pattern) and (3) the contents are compared to the object given for the ‘yaml:’ key (specific pattern).
2.2 SCS Configuration
The scs_configuration
property allows you to override parts of ‘scs-configuration.yaml’ during validation. The following changes are applied by default:
- Logs are directed to stdout
- The auth blueprint is disabled.
- The built-in
!scs-secret
constructor is replaced, to generate random strings (So secrets are not required at validation time)
You can also use this property, as illustrated in the example, to override custom YAML tag constructors, for example when you’re using a cloud-dependent constructor in your configuration.