Metadata-Version: 2.1
Name: qcloud_setup
Version: 1.0.0
Summary: Q-Cloud setup utility for cluster administrators
Home-page: https://q-chem.com
Author: Andrew Gilbert
Author-email: "Q-Chem Inc." <support@q-chem.com>
License: Confidential property of Q-Chem, Inc.
        Copyright (c) 1993 by Q-Chem, Inc. (unpublished)
        All rights reserved.
        
        The above copyright notice is intended as a precaution against
        inadvertent publication and does not imply publication or any
        waiver of confidentiality. The year included in the foregoing 
        notice is the year of creation. This software product contains
        proprietary, confidential information and trade secrets of
        Q-Chem, Inc. and its licensors. No use may be made of this
        software except according to written agreement with Q-Chem, Inc.
        
Project-URL: Homepage, https://q-chem.com
Keywords: qcloud,qchem,q-cloud,q-chem
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt

-----------------------------------------------------------------------

<h1 align="center"> Q-Cloud Administrator Documentation </h1>

-----------------------------------------------------------------------


## Introduction

Q-Cloud is a framework that allows users to easily launch elastic compute
clusters on AWS and run Q-Chem calculations on them.  

Q-Cloud clusters are built around three separate AWS service stacks with the
following names and purposes:
1. _qcloud-users_: This stack is optional and controls access to the cluster.  It
   launches a Cognito service which manages users, passwords and access tokens.
2. _qcloud-api-gateway_: This stack provides the REST endpoints for submitting jobs to
   the cluster and for accessing the results from calculations.  
3. _qcloud-cluster_: This is the actual compute cluster and consists of a head node
   (which can be just a t2.micro instance) running a SLURM workload manager.
   The head node is responsible for launching the compute instances which run
   the Q-Chem calculations.  The head node runs for the lifetime of the
   cluster, but the compute nodes run on-demand and automatically terminate
   when there are no jobs in the queue.

The cluster administrator will need to have a valid AWS account in order to
launch a cluster, however, users of the cluster can be configured separately
and do not require an AWS account. See the Adding users section below for
further details on setting up users.

**Note:** Charges apply to many AWS services.  See the Costs section for
further details and information on how to minimise the running costs of the
cluster.


## AWS User and Credentials

It is recommended that you create a separate qcloud user to manage the cluster:

1. Open your web browser and log into the [AWS console](https://signin.aws.amazon.com/).  
2. Ensure you are in the correct region (this is displayed in the the top right
   of the console).
3. In the search box type IAM and select the first hit.
4. Select 'Users' in the left hand panel under Access Management and click the
   'Add users' button.
5. Enter the name of the Q-Cloud administrator (e.g. qcloud) and click 'Next'.
6. An IAM policy to manage permissions will be created later, so in the 'Set
   Permissions' panel, just click 'Next'.
7. Click 'Create user'.

The new user will require an access key for authentication:

1. In the IAM panel click on the qcloud user name in the list of users.
2. Select the 'Security credentials' tab and scroll down to the 'Access keys'
   section and click the 'Create access key' button.
3. Select the 'Local code' option in the 'Access key best practices &
   alternatives' panel and click 'Next'.
4. Enter a description for the key and click 'Create access key'.
5. Make a note of both the access key and the secret access key.  You will not
   have another opportunity to see the secret key, so if you misplace it you
   will need to deactivate the key and generate a new one.

We will now add IAM permissions to the user via a custom policy.  The policy is 
most easily created via CloudFormation and the template file can be generated with:
```
qcloud_setup --gen-policy
```
This will create the file iam-policy.yaml in the working directory.

1. In the AWS console, search for CloudFormation and click the first hit. 
   Select 'Stacks' in the left hand panel.
2. Click the 'Create stack' and select 'With new resources' from the drop-down menu.
3. Choose the 'Upload a template file' option and the click the 'Choose file' button.
4. Navigate to your working directory and select the just created iam-policy.yaml file.  Click 'Next'
5. Enter a stack name (e.g. Q-CloudIamPolicy) and click 'Next'.
6. For the 'Configure stack options' page, click 'Next'.
7. For the 'Review Q-CloudIamPolicy' tick the acknowledge box and click 'Submit'.

The policy should be ready within a minute at which point you will see 
CREATE\_COMPLETE under the stack names.  We must now attach the newly created policy
to the qcloud user.

1. Return to the IAM console and navigate to Users &#8594; qcloud.
2. In the 'Permissions policies' section, click the 'Add permissions' button.
3. Select the 'Attach policies directly' option at the top and search for
   Q-CloudIamPolicy.  Select the Q-CloudIamPolicy just created and click
   'Next'.
4. Click 'Add permissions' on the Review page.


## Prequisites

The Q-Cloud infrastructure requires you to have python (v3.7 or later)
installed.  You can install the package, along with its dependencies, using the
following:
```
python3 -m pip install --index-url https://jubilee.q-chem.com/qcpip  qcloud_setup
```
Ensure plcuster is on your path by typing the following:
```
which pcluster
```
If it is not, you will need to find the pcluster script within your python
environment and add its location to your path.

Additionally, Node.js is required and can be installed via:
```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
. ~/.nvm/nvm.sh
nvm install --lts
```

In order that qcloud\_setup can access AWS resources, you will neeed to add the 
previously created access keys.  Navigate to the directory containing the Q-Cloud 
download and type the following:
```
qcloud_setup  --configure-aws
```

Enter the AWS region, access key and secret key that you noted down earlier.  The 
region entered(e.g. us-east-1) will determine the location of the resources.


## Cluster Configuration
Cluster configuration files are generated with the command: 
```
qcloud_setup --configure
```
This takes the user through an interactive setup process which produces a
configuration file with the name *qcloud-cluster.config* which can be viewed
before launching the cluster.  Do not modify the contents of the configuration
file as it may cause subsequent steps in the setup to fail.

By default the name of the cluster is 'qcloud', but this can be changed using
the `--name <cluster_name>` option.  This allows for multiple clusters to run
at the same time, if required.  Note that if a non-default name is specified
then this name must be passed using the `--name` option to subsequent commands
(e.g. `--launch`) in order that they operate on the correct cluster.

The options specified in the configuration process are discussed in detail below.

#### 1) AWS Credentials

These should have been configured previously and, if so, are automatically
detected.  Make sure you are using a profile with the Q-CloudIamPolicies
attached, such as the  qlcoud user created above.  If you have more than one
profile, you can select between them using the `--profile <profile_name>`
option.  The selected profile will determine the region in which the cluster is
launched.  

A new SSH key pair will be created and the private key will be saved in the
qcloud\_\<region\>\_keypair.pem file.  You can copy this key file to the location
of your other key files (e.g. the ~/.ssh directory), if desired.  Do not lose
this private key as you will be unable to connect to the head node without it.


#### 2) VPC setup

The Q-Cloud cluster runs inside a Virtual Private Cloud (VPC) and it is
recommended that a new VPC be created for running the Q-Cloud cluster.
However, because there is a limit on the number of VPCs per AWS account, this may
not be possible for some users. Please select whichever of the following 
options is best for your case:

- Default: This option will use your default VPC and both the head node and
  compute clusters will be in a public subnet (not recommended).
- Use existing: If available.  The setup script will look for a previously
  configured Q-Cloud VPC.  This will have both public (for the head node) 
  and private (compute nodes) subnets configured.
- Create new: This will create a new VPC with public and private subnets.  
  The availability zone of the subnets does not matter.


#### 3) Compute instance types

The costs shown are indicative only and are for running each instance. They
do not include storage or network costs.

#### 4) Maximum compute nodes
This determines the maximum number of compute instances that can run concurrently. 
If more jobs are submitted than this value, they will be queued until the resources
become available.

This value should be set to the same number as the number of seats purchased as
part of your license.


#### 5) Job files
This is the space allocated for the jobs volume which is attached to the head
node and shared between compute instances.  This volume is used for output
files only and can be quite small.  Output files are automatically deleted
after they have been copied to the S3 bucket.

#### 6) Scratch files

This determines the scratch volume size per instance. As an indicative cost,
100Gb costs around $10/month.


## Launching a cluster
Once a configuration file has been generated, the service stacks can be
launched with the following:
```
qcloud_setup  --launch 
```
Cognito is used to manage user access to the REST API. 

The launch option updates the configuration file with the placeholder values.

**Note:** Progress of the stack launch is printed to the terminal and will take
several minutes.

Once launched, you will need to send the following information to Q-Chem to obtain 
your license activation key:

- Elastic IP address 
- Order number
- Name 
- University / Institution

Once you have your activation key you can install it as follows:
```
qcloud_setup  --activation-key XXXX-XXXX-XXXX-XXXX-XXXX
```
This command requires access to the SSH key generated during the configuration
step, which should be either in the current directory or in your home directory
under ~/.ssh.



## Adding users
Before submitting jobs, a user will need to be added to the Cognito user pool:
```
qcloud_setup --adduser <user_name> --email <email_address>
```
Alternatively, you can add multiple users from a file:
```
qcloud_setup --addusers <file_name>
```
where the file\_name consists of a list of user names and email addresses with the 
format:
```
elmo     elmo@gmail.com
bigbird  bigbird@gmail.com
...
```

A message will be sent to the user's email address with their user name and a
temporary password, which will need to be changed when first attempting to
submit a job.

Note that the number of users able to be added each day is set to 50 due to
email limits in the Cognito service.  If you need to add more than this you
will need to configure Cognito with the Simple Email Service' (SES) and add 
a validated administrator email.

The cluster administrator will need to provide the server details to each 
user which can be obtained by running the command:
```
qcloud_setup --userinfo
AwsRegion                        us-east-1
CognitoUserPoolId                us-east-1_KbkatQIpW
CognitoAppClientId               2mgcn0o6fk7kboq7jnqs6bd6ee
ApiGatewayId                     fkkfolduo4
```
Cluster users will need to install and configure the command line interface (CLI):
```
python3 -m pip install --trusted-host 44.211.208.71 --index-url http://44.211.208.71:8080 qcloud_user
```
this will install the qcloud command into their python environment and this can be configured
by running the following command and entering the appropriate values:
```
qcloud --configure
```
The first time a user interacts with the cluster they will need to enter the temporary
password emailed to them before resetting their password.

See the README.md file distributed with the qcloud_user module for further
details on interacting with the server.




## Suspending a Cluster

It is possible to shut down the cluster head node and restart it at a later
time in order to minimise the running costs.  If you plan to restart the
cluster, make sure you keep a copy of the configuration and license files.

Use the `--suspend` option to delete only the cluster stack.  You will be prompted
if you want to delete the stack, type 'y' to confirm.

```
qcloud_setup --suspend
Delete stack qcloud-cluster? [y/N] y
```
This terminates the head node, but leaves the API gateway and Cognito stacks
running, using minimal resources.  Once the cluster has been deleted, the
results of previous jobs can still be accessed via the API gateway as these are
archived in an S3 bucket.  You will, of course, be unable to submit further
jobs until the cluster has been restarted.

To re-launch the cluster, issue the following command in the same directory as
the configuration and license files:

```
qcloud_setup  --launch --install-license <license_file>
```
The `--install-license` option automatically updates the license file with the private IP
of the new host.

**Note:** In order to restart a cluster, you must have configured the cluster to
use an elastic IP (EIP) address allocated to your AWS account. This EIP must be
available for reuse when re-launching the cluster, otherwise the Q-Chem license
will no longer be valid.

If you need to update the EIP of your host, please contact our support team at 
support@q-chem.com for assistance.


## Teminating a cluster
Before terminating a cluster, ensure there are no jobs running in the queue and
that you have downloaded the results of any calculations you wish to keep.  The
following command will  delete the cluster:
```
qcloud_setup --delete
```
You will be asked whether you want to delete each of the 3 stacks, 
and you should type 'y' for each.

To clean up all the resources allocated to the cluster, be sure to release the
elastic IP address and clean out any files created in the S3 bucket.


## Other options

Additional options for the setup script can be printed via:

```
qcloud_setup  --help
qcloud_setup  --info
qcloud_setup  --list
```

You can also open an ssh connection to the head node using the following:

```
qcloud_setup  --shell
```


## Costs

If you will not be submitting jobs for an extended period of time, be sure to suspend
or terminate the cluster.

AWS charges $0.005/hr for reserving an EIP that is not associated with an instance.

Approximate EBS storage costs: 10Gb $1/month

S3 storage

EIP costs


## Troubleshooting

- When launching the cluster, if you receive permission problems associated
  with lambda functions, check to ensure that the IAM policy (QCloudIamPolicy) has been
  created in the same region as the cluster.

- When submitting jobs, a job ID should be returned. This is a random
  sequence of 12 alphanumeric characters associated with your job.  If you do
  not see a job ID, it is possible the submit function has not been updated
  with the instance ID of the head node.  Re-run the launch command to trigger
  this update:
```
qcloud_setup --launch
```

- If you encounter any problems not covered here, please contact our support team at 
  support@q-chem.com for assistance. 

