doc: add "Moving from CfnCluster to AWS ParallelCluster" section

Signed-off-by: Enrico Usai <[email protected]>

Author: Enrico Usai

docs/source/getting_started.rst

@@ -16,13 +16,14 @@ You can build higher level workflows, such as a Genomics portal that automates t
 Installing AWS ParallelCluster
 ==============================
 
-The current working version is aws-parallelcluster-|version|. The CLI is written in Python and uses BOTO for AWS actions. You can install the CLI with the following commands, depending on your OS.
+The current working version is aws-parallelcluster-|version|. The CLI is written in Python and uses BOTO for AWS actions.
+You can install the CLI with the following commands, depending on your OS.
 
 Linux/OSX
 ---------
 ::
 
-   $ sudo pip install aws-parallelcluster
+    $ sudo pip install aws-parallelcluster
 
 Windows
 -------
@@ -39,7 +40,7 @@ Now it should be possible to run the following within a command prompt window:
 
 ::
 
-   C:\> pip install aws-parallelcluster
+    C:\> pip install aws-parallelcluster
 
 Upgrading
 ---------
@@ -61,20 +62,22 @@ Once installed you will need to setup some initial config. The easiest way to do
 
     $ pcluster configure
 
-This configure wizard will prompt you for everything you need to create your cluster.  You will first be prompted for your cluster template name, which is the logical name of the template you will create a cluster from.
+This configure wizard will prompt you for everything you need to create your cluster.
+You will first be prompted for your cluster template name, which is the logical name of the template you will create a cluster from.
 
 ::
 
         Cluster Template [mycluster]:
 
-Next, you will be prompted for your AWS Access & Secret Keys.  Enter the keys for an IAM user with administrative privileges.  These can also be read from your environment variables or the  aws CLI config.
+Next, you will be prompted for your AWS Access & Secret Keys.  Enter the keys for an IAM user with administrative privileges.
+These can also be read from your environment variables or the  aws CLI config.
 
 ::
 
         AWS Access Key ID []:
         AWS Secret Access Key ID []:
 
-Now, you will be presented with a list of valid AWS region identifiers.  Choose the region in which you'd like your cluster to run.
+Now, you will be presented with a list of valid AWS region identifiers. Choose the region in which you'd like your cluster to run.
 
 ::
 
@@ -98,7 +101,8 @@ Choose a descriptive name for your VPC. Typically, this will something like :cod
 
         VPC Name [myvpc]:
 
-Next, you will need to choose a keypair that already exists in EC2 in order to log into your master instance.  If you do not already have a keypair, refer to the EC2 documentation on `EC2 Key Pairs <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html>`_.
+Next, you will need to choose a keypair that already exists in EC2 in order to log into your master instance.
+If you do not already have a keypair, refer to the EC2 documentation on `EC2 Key Pairs <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html>`_.
 
 ::
 
@@ -128,12 +132,83 @@ Finally, choose the subnet in which you'd like your master server to run in.
         Master Subnet ID []:
 
 
-Next, a simple cluster launches into a VPC and uses an existing subnet which supports public IP's i.e. the route table for the subnet is :code:`0.0.0.0/0 => igw-xxxxxx`. The VPC must have :code:`DNS Resolution = yes` and :code:`DNS Hostnames = yes`. It should also have DHCP options with the correct :code:`domain-name` for the region, as defined in the docs: `VPC DHCP Options <http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_DHCP_Options.html>`_.
+Next, a simple cluster launches into a VPC and uses an existing subnet which supports public IP's i.e. the route table for the subnet is :code:`0.0.0.0/0 => igw-xxxxxx`.
+The VPC must have :code:`DNS Resolution = yes` and :code:`DNS Hostnames = yes`.
+It should also have DHCP options with the correct :code:`domain-name` for the region, as defined in the docs: `VPC DHCP Options <http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_DHCP_Options.html>`_.
 
 Once all of those settings contain valid values, you can launch the cluster by running the create command:
 
 ::
 
-	$ pcluster create mycluster
+    $ pcluster create mycluster
+
+Once the cluster reaches the "CREATE_COMPLETE" status, you can connect using your normal SSH client/settings.
+For more details on connecting to EC2 instances, check the `EC2 User Guide <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-connect-to-instance-linux.html#using-ssh-client>`_.
+
+
+Moving from CfnCluster to AWS ParallelCluster
+=============================================
+
+AWS ParallelCluster is an enhanced and productized version of CfnCluster.
+
+If you are a previous CfnCluster's user, we encourage you to start using and creating new clusters only with AWS ParallelCluster.
+Although you can still use CfnCluster, it will no longer be developed.
+
+The main differences between CfnCluster and AWS ParallelCluster are listed below.
+
+|
+
+**AWS ParallelCluster CLI manages a different set of clusters**
+
+Clusters created by :code:`cfncluster` CLI cannot be managed with :code:`pcluster` CLI.
+The following commands will no longer work on clusters created by CfnCluster::
+
+     pcluster list
+     pcluster update cluster_name
+     pcluster start cluster_name
+     pcluster status cluster_name
+
+You need to use the :code:`cfncluster` CLI to manage your old clusters.
+
+If you need an old CfnCluster package to manage your old clusters, we recommend to install and use it
+from a `Python Virtual Environment <https://docs.python.org/3/tutorial/venv.html>`_.
+
+|
+
+**Distinct IAM Custom Policies**
+
+Custom IAM Policies, previously used for CfnCluster cluster creation, cannot be used with AWS ParallelCluster.
+If you require custom policies you need to create the new ones by following :ref:`IAM in AWS ParallelCluster <iam>` guide.
+
+|
+
+**Different configuration files**
+
+The AWS ParallelCluster configuration file resides in the :code:`~/.parallelcluster` folder, unlike the CfnCluster one that was created in the :code:`~/.cfncluster` folder.
+
+You can still use your existing configuration file but this needs to be moved from :code:`~/.cfncluster/config` to :code:`~/.parallelcluster/config`.
+
+If you use the :code:`extra_json` configuration parameter, it has be changed as described below:
+
+:code:`extra_json = { "cfncluster" : { } }`
+
+has been changed to
+
+:code:`extra_json = { "cluster" : { } }`
+
+|
+
+**Ganglia disabled by default**
+
+Ganglia is disabled by default.
+You can enable it by setting the :code:`extra_json` parameter as described below:
+
+:code:`extra_json = { "cluster" : { ganglia_enabled = 'yes' } }`
+
+and changing the Master SG to allow connections to port 80.
+The :code:`parallelcluster-<CLUSTER_NAME>-MasterSecurityGroup-<xxx>` Security Group has to be modified by
+`adding a new Security Group Rule <https://docs.aws.amazon.com/en_us/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule>`_
+to allow Inbound connection to the port 80 from your Public IP.
+
+
 
-Once the cluster reaches the "CREATE_COMPLETE" status, you can connect using your normal SSH client/settings. For more details on connecting to EC2 instances, check the `EC2 User Guide <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-connect-to-instance-linux.html#using-ssh-client>`_.

docs/source/iam.rst

@@ -316,7 +316,7 @@ ParallelClusterUserPolicy
                   "iam:SimulatePrincipalPolicy"
               ],
               "Effect": "Allow",
-              "Resource": "arn:aws:iam::<AWS ACCOUNT ID>:role/<CFNCLUSTER EC2 ROLE NAME>"
+              "Resource": "arn:aws:iam::<AWS ACCOUNT ID>:role/<PARALLELCLUSTER EC2 ROLE NAME>"
           },
           {
               "Sid": "IAMCreateInstanceProfile",