Back: 4. Remote Desktop | CFDDFC on AWSNext: 6. Data Storage

Contents

  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. 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 -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
 -h | -help | help         print full help
 -i | -instance <type>     specify the instance type; type "list" for options,
                           default is "c4.2xlarge"
 -n | -image-name <name>   name/version of image
                           5: CFDDFC 5.2 (default)
                           4: CFDDFC 4.2
                           xenial: Ubuntu 16.04 LTS xenial
 -k | -key <key>           specify instance using its 8 digit key, e.g. A1b2C3D4
 -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

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 -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 -c 2

Common alternative options are listed below.

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

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

Back: 4. Remote Desktop | CFDDFC on AWS | Next: 6. Data Storage