How to use c4

This section describes the basics of how to use Exasol Deployment Tool (c4) to create and manage Exasol deployments.

Introduction

For information about how to install c4, see Install c4.

To run c4 commands, enter <path_to_c4_binary>/c4 <command> in a Linux terminal.

If you add the path to the c4 binary to your PATH variable, you do not have to prefix the c4 commands with the path. For information about how to modify PATH, refer to the documentation for your Linux distribution.

In the following examples, the c4 commands are run without a path prefix.

To view the general help in c4, use c4 --help. To get help for a specific command, use c4 <command> --help.

Configuration parameters

Configuration parameters for c4 can be specified in a configuration file and/or on the command line when creating a deployment. For general information about the c4 configuration parameters, see Parameters in c4.

For information about the parameters required for AWS deployment, see Configure c4 for AWS.

Create a deployment

To deploy Exasol on AWS, use c4 aws play. For more information, see Deploy Exasol on AWS.

Monitor deployments

To see all your current deployments, use c4 ps. 

$ c4 ps
      
      N  PLAY_ID   NODE  MEDIUM  INSTANCE     EXTERNAL_IP     INTERNAL_IP  STAGE  STATE      UPTIME    TTL
  ┌─  1  3a4a7d8d  10    awscf   c5d.large    203.0.113.10    10.0.0.10    c      running    04:35:15  +∞
  │   1  3a4a7d8d  11    awscf   c5d.2xlarge  203.0.113.11    10.0.0.11    d      running    04:35:16  +∞
  │   1  3a4a7d8d  12    awscf   c5d.2xlarge  203.0.113.12    10.0.0.11    d      running    04:35:16  +∞
  └─  1  3a4a7d8d  13    awscf   c5d.2xlarge  203.0.113.13    10.0.0.13    d      running    04:35:15  +∞

By default, c4 ps shows the deployments in the region specified in the CCC_AWS_REGION parameter. To quickly view deployments in other regions, you can override the configuration parameter by specifying a different region on the command line. For example: CCC_AWS_REGION=eu-central-1 c4 ps will show the deployments that are running in the eu-central-1 AWS region.

The following information is displayed for each node and deployment:

Column Description
N The number of the deployment in the current c4 ps table.
PLAY_ID Unique identifier for the deployment
NODE Node ID (if available)
MEDIUM The medium that was used to create the deployment (awscf = AWS CloudFormation).
INSTANCE Instance type for the node
EXTERNAL_IP External IP address
INTERNAL_IP Internal IP address
STAGE The current deployment stage of the node, see Deployment stage
STATE The current state of the node, see Node state
UPTIME Time lapsed since the node was created
TTL Time for the deployment to live (+∞ if unlimited/TTL unset)

During creation and/or startup, each node goes through the following deployment stages:

Deployment stage Description
a/a1 Cloud instance creation is in progress. No services are reachable at this stage.
b/b1 Host is booting up. The node can be accessed via SSH and the c4 service is running.
c EXAClusterOS (COS) services are running and reachable.
d Database is running and reachable.

When a node is created it will be in one of the following states:

Node state Description
creating Node is being created.
pending Node is preparing to enter the running state.
running Node is running at the indicated stage, see Deployment stage
stopped Node is shut down and cannot be used.
rollingback Node creation failed and is rolling back.
succeeded

The previous deployment operation succeeded.

NOTE: This node state does not indicate that the node is running, it only means that the last operation succeeded. In most cases, this node state indicates that node creation failed and was successfully rolled back.

failed The previous deployment operation failed.

The deployment is finished when all the database nodes have reached stage d and are in the running state. Since the database is not running on the access node, this node (if used) will remain at stage c.

Troubleshooting c4 ps

In some cases c4 ps may time out while waiting for an instance to respond during the deployment process. This can for example be the case if there is a large geographical distance between the system running c4 ps and the instances. If the instance does not respond within the timeout period, c4 ps will consider the instance to be unreachable and report it as being in deployment stage a, even if the instance has booted up and services are running on the node.

You can increase the time limit for c4 ps to wait for instances to respond by setting a higher value in the CCC_USER_PS_REMOTE_TIMEOUT parameter in the c4 configuration. The default value is 3000 ms. For example, to set the timeout to 10 seconds:

CCC_USER_PS_REMOTE_TIMEOUT=10000

For more information on how to set configuration parameters in c4, see Parameters in c4.

For more details about the c4 ps command, use c4 ps --help.

Connect to a deployment

To connect to a deployment, use c4 connect -t <NUM>[.<NODE>][/<SUBSYSTEM>] where <NUM> is the deployment number N shown in c4 ps, <NODE> is the node ID NODE, and <SUBSYSTEM> is the subsystem to connect to. The subsystems are explained in the following table.

  • If you do not specify a node, c4 will connect to the first active node in the cluster.

  • If you do not specify a subsystem, c4 will connect to the database if it is online.

Subsystem Description Examples
/cos Connect to EXAClusterOS on the target

c4 connect -t 1/cos

c4 connect -t 1.12/cos

/host Connect to the host Linux OS on the target

c4 connect -t 1/host

c4 connect -t 1.12/host

/db

Connect to the database on the target (using a built-in SQL client)

c4 connect -t 1

c4 connect -t 1/db

c4 connect -t 1.12/db

To disconnect, use Control+D.

For more details about the c4 connect command, use c4 connect --help.

Connecting to a target during an ongoing deployment process will show the deployment logs. This can be valuable for troubleshooting.

The built-in SQL client in c4 always runs in autocommit mode.

Refresh MFA token

If your organization uses MFA, you can use c4 aws token -f to refresh your token if needed. 

$ c4 aws token -f
Enter TOTP for device arn:aws:iam::12345678910:mfa/FirstnameLastname: 123456
Session token acquired - it expires on Fri, 20 Jan 2023 15:08:18 CET

Start nodes

If the access node is offline, you can use c4 to start nodes.

To start all nodes of a deployment, use c4 up <PLAY_ID>. You can also specify only starting certain nodes in the deployment with the --nodes option. For example, c4 up --nodes 12 f7fdff8e starts node 12 in deployment f7fdff8e. This command can be used to start all nodes when the database access node is offline.

c4 up is the equivalent of starting EC2 instances in the AWS console. The database is not started with this command. For information on how to start the database, see Start a Database

Stop nodes

To stop all nodes of a deployment, use c4 down <PLAY_ID>. You can also specify only stopping certain nodes in the deployment with the --nodes option. For example, c4 down --nodes 12 f7fdff8e stops node 12 in deployment f7fdff8e.

To prevent a risk of data loss, always stop the database before using the c4 down command.

c4 down will not safely shut down the database and may leave the database in a corrupted state. It is the equivalent of stopping EC2 instances in the AWS console. For this reason you should always stop the database before using this command. For information on how to safely shut down a database or cluster, see Stop a Database or Stop a Cluster.

Remove a deployment

To remove a deployment, use c4 rm <PLAY_ID>. 

$ c4 rm f7fdff8e

The c4 rm command will destroy the deployment without any possible recovery.