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 List values in the CLI must be specified by repeating the parameter name for each element. For example |
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 |
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
Absolute parameter
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.
-
User Configuration File
The user configuration file is located in
$HOME/.ccc
and can be specified in either shell, YAML, or JSON format. The default filename isconfig
.-
$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-1To 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.
-
-
Command Configuration File
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:
When running a command, specify
CCC_CONFIG
and the name of the configuration file. For example: -
Command-line Parameters
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 theplay
module, and--instance-type
is a configuration of theaws
module. Therefore, the parameters must be listed in the following order: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.