Parameters in c4

This section describes how configuration parameters are structured and defined in c4. For an explanation of how to set the specific c4 parameters for an AWS deployment, see Configure c4 for AWS.

Parameter Structure

The c4 deployment tool has a large number of configurable parameters. Most of these parameters do not need to be modified for everyday usage and can be left at their default values. The default values can be overridden persistently using local configuration files, and/or specifically for each deployment by including parameters on the command line when creating the deployment.

The parameters are organized into modules that describe what they modify or in what context they are used. Some common modules are AWS, PLAY, and USER. Parameter names are always upper case and start with CCC_<MODULE>_. For example:

Parameter Description
CCC_USER_EMAIL Email address to be used for deployment tagging
CCC_PLAY_ACCESS_NODE Boolean for including an access node in the deployment. If this option is unset or set to false an access node will not be deployed and the REST API cannot be used to manage the instance.
CCC_AWS_REGION AWS region where deployments must be done by default

To learn more about the available parameter options, use c4 config --help-on <module>:all.

Parameter Types

Each parameter has a defined type that it accepts for the value. This type is automatically validated when a parameter value is changed. The available types are:

Type Format
string Text or numbers. If the string contains spaces, it should be enclosed in quotation marks.
int Number (integer)
bool true or false
list

A list of strings.

List values in environment variables must be specified as space-separated strings with quotes for values with spaces. For example CCC_MODULE_PARAM='A "B C"'.

List values in the CLI must be specified by repeating the parameter name for each element. For example --param=A --param='B C' or --param={a,"B C"}

Parameter Formats

Configuration parameters can be specified in a configuration file using shell, JSON, or YAML format, as environment parameters, or as command-line options. Parameter names must be formatted differently depending on where they are specified:

Location Format
Shell config file Use full parameter name in UPPER CASE
JSON config file Exclude CCC_<MODULE> prefix, use lower case
YAML config file Exclude CCC_<MODULE> prefix, use lower case
Environment Use full parameter name in UPPER CASE
Command-line option (absolute)

Replace _ (underscore) with - (dash), use lower case
Command-line option (relative) Exclude CCC_<MODULE> prefix, replace _ (underscore) with - (dash), use lower case

For example:

Location Parameter name
Shell config file CCC_AWS_REGION
JSON config file region in the aws subsection
YAML config file region in the aws subsection
Environment CCC_AWS_REGION
Command-line option (absolute) --ccc-aws-region
Command-line option (relative) --region after the aws module

The difference between absolute and relative options is where in the command the parameter is specified. For example, to specify the AWS region with the relative option, the parameter --region must be written after aws in the c4 command. The absolute parameter --ccc-aws-region can be specified anywhere in the command. See the following examples showing the difference in the usage:

Relative parameter

c4 aws --region eu-central-1 play -n 2 -T @exasol-8.8.0

Absolute parameter

c4 aws play --ccc-aws-region eu-central-1 -n 2 -T @exasol-8.8.0 

How To Set Parameters

The following list describes where and how c4 parameters can be specified. The list is ordered from general to specific, meaning that parameters specified in locations at the top of the list will be overridden by values specified further down. For example, a command-line parameter value will always override the value specified in the user configuration file for the same parameter.

  1. The user configuration file is located in $HOME/.ccc and can be specified in either shell, YAML, or JSON format. The default filename is config.

    • $HOME/.ccc/config

    • $HOME/.ccc/config.yaml

    • $HOME/.ccc/config.json

    Example of a configuration file in shell format:

    $ cat $HOME/.ccc/config
    CCC_USER_EMAIL=firstname.lastname@exasol.com
    CCC_USER_FULLNAME='Firstname Lastname'
    CCC_AWS_PROFILE=default
    CCC_AWS_REGION=eu-west-1

    To update the configuration file, open the file using a text editor and add a new line using the one of the supported formats. Afterwards, save the file. The configuration is updated immediately and can be confirmed with c4 config --validate.

    The parameter values specified in the user configuration file will be used by default in every c4 statement unless another value is specified in one of the locations specified below.

  2. You can define parameters in a file in shell, YAML, or JSON format and load this file into c4 using CCC_CONFIG on the command line. The parameter values specified in this file will override the default values and values set in the user configuration file.

    Parameters for a specific module must be added within the module they configure.

    The following is an example YAML file that specifies the instance type of the database nodes and the database name:

    aws:
      instance_type: c5d.2xlarge
    play:
      database_name: my_db

    When running a command, specify CCC_CONFIG and the name of the configuration file. For example:

    $ CCC_CONFIG=myconfig.yaml c4 aws play @exasol-8.8.0

     

  3. You can specify configuration parameters as environment variables before a c4 command. For example:

    CCC_AWS_REGION=eu-west-1 c4 ps

    Parameter values set as environment variables will override default values and values set in configuration files.

  4. Parameter values can be specified on the command line as part of a c4 command. This is useful if you want to specify parameters that are only used for one command and should not be persisted.

    Relative parameters for a specific module must be added immediately after the module name in the command. For example, when creating a deployment, you can specify the database name (--database-name) and the instance types of the database nodes (--instance-type). The parameter --database-name is a configuration of the play module, and --instance-type is a configuration of the aws module. Therefore, the parameters must be listed in the following order:

    c4 aws --instance-type c5d.2xlarge play --database-name my_db -N 2 -T @exasol-8.8.0

    Alternatively, you can reference the absolute parameter names and list them anywhere in the c4 command. For example:

    c4 aws play -N 2 -T --ccc-aws-instance-type c5d.2xlarge --ccc-play-database-name my_db @exasol-8.8.0

    Parameter values set on the command line will override default values and any other configurations, but are not persisted.