CFD Direct

The Architects of OpenFOAM

CFDDFC on AWS: Launch an Instance with the CLI

Running CFDDFC with the CFDDFC CLI

  1. The CFDDFC command line interface (CLI)
  2. Install the CFDDFC CLI
  3. Configure the CFDDFC CLI
  4. Launch an Instance
  5. Run on an Instance
  6. Browser Desktop (Web CFDDFC)
  7. Launch a Cluster
  8. Terminate an Instance
[ AWS Setup | Launch with the Console | Launch with the CLI ]

Problem with these instructions? Please send a CFDDFC Support Query.

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 -h (-help or help) option.  A shorter menu of options is provided with the -u (-usage or 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. 12.34.56.789
                               "small": 12.34.56.0/24 (match first 3 numbers)
                               "medium": 12.34.0.0/16 (match first 2 numbers)
                               "large": 12.0.0.0/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
                           11: CFDDFC 11.0 (default)
                           10: CFDDFC 10.0
                           9: CFDDFC 9.1
                           8: CFDDFC 8.2
                           7: CFDDFC 7.2
                           6: CFDDFC 6.2 (deprecated)
                           5: CFDDFC 5.3 (deprecated)
                           lunar:   Ubuntu 23.04
                           jammy:   Ubuntu 22.04 LTS
                           focal:   Ubuntu 20.04 LTS
                           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
 -w | -web                 install "Web CFDDFC" providing the web-browser desktop
 -x | -role <name>         specify a role (instance profile) to attach to the instance
 -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 -cores (-c) option, 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 -cores 2

CFDDFC Product and Remote Desktop

The CFDDFC CLI launches the “Classic” CFDDFC by default on instances with x86 processors. For instances with Arm-based processors, CFDDFC (Arm) is launched automatically. If the user wishes to launch Web CFDDFC, to provide the browser desktop, the -web (-w) option must be used, e.g. 

cfddfc launch -cores 2 -web

The instance requires an attached role (instance policy), configured for the free license for the desktop. When launching with the -web option, CFDDFC tries to identify a suitable role to attach according to: 1) a role specified using the -role (-x) option; 2) else, a role with the default name CFDDFC-Web; 3), else, a role which appears to be configured for the purpose and which is confirmed by the user.

Common options

Common alternative options are listed below.

  • access: permit access from any IP address with the -any (-a) option.
  • instance type: instead of specifying number of physical cores, an particular EC2 instance can be be specified with the -instance (-i) option; instance types can be conveniently listed by “-instance list”.
  • pricing: the user can launch an instance On-Demand with “-type demand”.
  • storage: the user can specify their own volume size with the -volume (-v) option.
  • version/image: specify the image name with convenient options for CFDDFC versions and Ubuntu images with the -image-name (-n) option.

Launch Process

When the 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.

Managing Instances

The user can manage instances with the following commands.

  • list: list all the current CFDDFC instances, with ID directories in  ~/.cfddfc.
  • attach: attach an existing instance to another OpenFOAM case, i.e. store the instance ID in a local .cfddfc file.
  • detach: detach an instance from an OpenFOAM case, i.e. delete a local .cfddfc  file that stores an instance ID.

Next Step : Run on an Instance