Parameters in c4

This section describes how configuration parameters in Exasol Deployment Tool (c4) are structured and defined.

Parameter Structure

The c4 deployment tool has a large number of configurable parameters. The majority of these parameters can be left at their default values for most deployment scenarios, and many apply only to a specific deployment platform. Some parameters must however be explicitly set in order to create a deployment. The required parameters for AWS deployments are described in Deploy Exasol on AWS.

You can set configuration values persistently using local configuration files that are loaded when you create the deployment. You can also define configuration values specifically for each deployment by loading a custom configuration file and/or setting parameters on the command line. For more details, see Setting Parameters.

The configuration parameters are organized into modules that indicate in which context they are applied, such as USER or PLAY. Parameter names start with CCC_<MODULE>_ to clearly indicate which context the belong in.

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.
CCC_AWS_REGION AWS region where deployments must be done by default

Get info about parameters

To view all the available parameters in c4, use the command c4 config -F. This command returns a complete list of all parameters and their current values, including parameters that are not relevant for your deployment platform.

To learn more about specific parameters, use c4 config -K <string>, where <string> is the full or partial name of a parameter (case-insensitive).

For example, to get a description of all parameters in the CCC_PLAY module, use c4 config -K ccc_play. To get all parameters that contain “key” in their names, use c4 config -K key. 

c4 config -K ccc_play
Found 93 results for query `ccc_play`:

    CCC_PLAY_DIR (string)

      Location of play directories (playgrounds).

      Default value : /home/username/.ccc/play
      Current value : [empty]
      JSON/YAML name: play.dir

    CCC_PLAY_DATADISK_DEFAULT_SIZE (int)

      Default size of the data disk used for play images (in GB).

      Default value : 16
      Current value : [empty]
      JSON/YAML name: play.datadisk_default_size
      
      ...

To learn more about how to use the config command, use c4 config --help.

Setting Parameters

Configuration parameter values can be set in configuration files using shell, JSON, or YAML format. The configuration file config located in the installation directory will be loaded by default. You can also specify a configuration file to be loaded by adding the path to the file on the command line when you create the deployment. Individual parameters can also be set on the command line as environment variables before the command or as command-line options.

Options on the command line can be absolute or relative. An absolute option can be specified anywhere in the command. A relative option must be preceded by the module name. The module name can be followed by multiple (relative) options, see examples below.

When creating a deployment, the parameter values are loaded in the following order of precedence:

  1. User configuration file
  2. Configuration file loaded on the command line
  3. Environment variables
  4. Command-line parameters

For example, a parameter value set in an environment variable will override the value for the same parameter specified in a configuration file, but will be overridden by a value set on the command line.

Parameter Formats

Parameters are formatted differently depending on where they are specified:

Location Format Example
Shell config file Use the full parameter name in UPPERCASE. CCC_PLAY_DATABASE_NAME=my_db
JSON or YAML config file

Exclude the CCC_<MODULE> prefix, use lowercase.

Must be placed in a subsection for the corresponding module.

 
play:
 database_name: my_db
Environment variable Use the full parameter name in UPPERCASE. CCC_PLAY_DATABASE_NAME=my_db
Command-line option (absolute)

Replace _ (underscore) with - (dash), use lowercase.

 c4 play --ccc-play-database-name my_db ...
Command-line option (relative)

Exclude the CCC_<MODULE> prefix, replace _ (underscore) with - (dash), use lowercase.

Must be preceded by the module name.

 c4 play --database-name my_db --db-password j8IUgef7_IJz9 ...

Parameter Data Types

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

Type Format Example
string Can contain text or numbers. If the string contains spaces, it must be enclosed in quotation marks.

CCC_PLAY_ADMIN_PASSWORD=df0g98j_98Xc

CCC_USER_FULLNAME=”Alice User”

int Number (integer) CCC_PLAY_DB_PORT=8563
bool true or false CCC_PLAY_ACCESS_NODE=true
list

A list of strings.

When specified in environment variables, list values must be entered as space-separated strings. Values that contain spaces must be enclosed in quotation marks.
For example: CCC_MODULE_PARAM='A "B C"'

When defined on the command line, list values must be specified by repeating the parameter name for each element.
For example: --param=A --param='B C' or --param={a,"B C"}

  

Examples

  1. The user configuration file is located in $HOME/.ccc and can use 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.

    To confirm that the configuration is valid, use 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 a corresponding subsection of the file. For example, the following YAML file specifies the instance type of the database nodes and the database name and password:

    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.22.0

     

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

    CCC_AWS_REGION=eu-west-1 c4 ps

  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.22.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.22.0