Running CFDDFC with the CFDDFC CLI
- The CFDDFC command line interface (CLI)
- Install the CFDDFC CLI
- Configure the CFDDFC CLI
- Launch an Instance
- Run on an Instance
- Launch a Cluster
- Terminate an Instance
Launching an Instance
The CFDDFC CLI (
cfddfc) is designed to enable users to run OpenFOAM workloads conveniently in the cloud on AWS. In this example we will run the
pitzDaily tutorial case in OpenFOAM using
cfddfc. If the user has a local installation of OpenFOAM, they could change to the “
run” directory, copy the case directory from the OpenFOAM distribution, and go into the case directory, e.g. by
run cp -r $FOAM_TUTORIALS/incompressible/simpleFoam/pitzDaily . cd pitzDaily
Help and Options
The user can now launch an instance of CFDDFC on AWS with “
cfddfc launch”. For any command a full help menu is available running with the
help) option. A shorter menu of options is provided with the
usage) options. For example the user could run
cfddfc launch -u Usage: cfddfc launch [OPTIONS] options: -a | -anywhere open SSH access from any IP address; by default, access is restricted to only the user's IP address -c | -cores <cores> number of cores, min 1, max 32, default 4 -d | -dry-run build launch specification but exit before launch -e | -efa use the Elastic Fabric Adapter networking (v7.0 only) -h | -help | help print full help -i | -instance <type> specify the instance type; type "list" for options, default is "c4.2xlarge" -j | -ip-range <range> limit range of IPs from which instance will accept login attempts. <range> options: "host" (default): launch IP, e.g. 188.8.131.529 "small": 184.108.40.206/24 (match first 3 numbers) "medium": 220.127.116.11/16 (match first 2 numbers) "large": 18.104.22.168/8 (match first number) "all": (-anywhere option) 0.0.0.0/0 (no match) -k | -key <key> specify instance using its 8 digit key, e.g. A1b2C3D4 -l | -label <label> add a label to the instance -n | -image-name <name> name/version of image 9: CFDDFC 9.0 (default) 8: CFDDFC 8.2 7: CFDDFC 7.2 6: CFDDFC 6.2 5: CFDDFC 5.3 hirsute: Ubuntu 21.04 hirsute focal: Ubuntu 20.04 LTS focal bionic: Ubuntu 18.04 LTS bionic amazon2: Amazon Linux 2 -p | -profile <profile> AWS credentials in ~/.aws/credentials, defaults to "default" -t | -type <price_type> specify type of pricing: spot (default) or demand -r | -region <region> specify different region to the profile default -u | -usage | usage usage listing with options -v | -volume <size_GB> size of volume in GB, min 8, max 1000, default 20 -y | -yes confirm yes to all prompts -z | -zone-id specify availability zone ID, e.g. a, b, c, etc
A user running for the first time will likely to choose the following options.
- profile: use their default profile that includes their preferred region.
- access: accept the default behaviour that permits login from the user’s IP address only.
- number of physical cores: specify with the
-coption, allowing the script choose a suitable EC2 instance type
- pricing: use the default option that uses EC2 spot instances which substantially reduces cost of CFD,
- storage: use the default option that allocates 5 GB per core (minimum 20 GB).
To launch an instance with 2 physical cores with default pricing, storage, profile, region and access, the user can simply run:
cfddfc launch -c 2
Common alternative options are listed below.
- access: permit access from any IP address with the
- instance type: instead of specifying number of physical cores, an particular EC2 instance can be be specified with the
-ioption; instance types can be conveniently listed by “
- pricing: the user can launch an instance On-Demand with “
- storage: the user can specify their own volume size with the
- version/image: specify the image name with convenient options for CFDDFC versions and Ubuntu images.
launch script is run, it creates an local 8 character ID (e.g.
aB1cD2eF) for the instance. The instance configuration and SSH private key, required to connect to the instance, is stored in a directory
~/.cfddfc/aB1cD2eF. When launching within an OpenFOAM case directory, the ID is also stored in a .
cfddfc file within the case directory, to “attach” the instance to the case. If anything fails during the launch process, e.g. network connection is broken, the launch can be resumed simply by running
launch again. Instance details cannot be modified by re-running
launch with different options, but security access is updated if the local IP address changes, or the user opens access from all IP addresses with the
-a option. Note that network access, once opened, is not subsequently restricted.
Testing the Instance
At the end of a successful launch, a message is printed in the terminal that tells the user to run
cfddfc test to test the SSH connection to the instance. The user should run that command to test the connection.
The user can manage instances with the following commands.
list: list all the current CFDDFC instances, with ID directories in
attach: attach an existing instance to another OpenFOAM case, i.e. store the instance ID in a local .
detach: detach an instance from an OpenFOAM case, i.e. delete a local .
cfddfcfile that stores an instance ID.