Installing and upgrading 1.2.1 (#868)

* Updated appliance deployment procedure for 1.2.1.

* Added new steps for install and upgrade

* Updated upgrade script name

* Tested fresh OVA deployment with 1.2.1 RC3.

* Updated when to perform procedure to register with ext. PSC

* Updating upgrade procedure for 1.2.1 RC3

* Adding placeholder upgrade troubleshooting doc

* Addressing comments from Anchal

* Fixed link to post-upgrade tasks

* Eliminating repetition

docs/user_doc/SUMMARY.md

@@ -60,6 +60,8 @@
      * [Data Migration](vic_vsphere_admin/upgrade_data.md) 
      * [Pre-Upgrade Tasks](vic_vsphere_admin/pre_upgrade_tasks.md)
      * [Upgrade the Appliance](vic_vsphere_admin/upgrade_appliance.md)
+         * [Post-Upgrade Tasks](vic_vsphere_admin/post_upgrade_tasks.md)
+         * [Troubleshoot Appliance Upgrade](vic_vsphere_admin/troubleshoot_appliance_upgrade.md)
      * [Upgrade VCHs](vic_vsphere_admin/upgrade_vch.md)
          * [VCH Upgrade Options](vic_vsphere_admin/upgrade_vch_options.md)
      * [Upgrade Plug-In on Windows](vic_vsphere_admin/upgrade_h5_plugin_windows.md)

docs/user_doc/vic_vsphere_admin/SUMMARY.md

@@ -49,6 +49,8 @@
      * [Data Migration](upgrade_data.md) 
      * [Pre-Upgrade Tasks](pre_upgrade_tasks.md)
      * [Upgrade the Appliance](upgrade_appliance.md)
+         * [Post-Upgrade Tasks](post_upgrade_tasks.md)
+         * [Troubleshoot Appliance Upgrade](vic_vsphere_admin/troubleshoot_appliance_upgrade.md)
      * [Upgrade VCHs](upgrade_vch.md)
          * [VCH Upgrade Options](upgrade_vch_options.md)
      * [Upgrade Plug-In on Windows](upgrade_h5_plugin_windows.md)

docs/user_doc/vic_vsphere_admin/deploy_vic_appliance.md

@@ -2,6 +2,7 @@
 
 You install vSphere Integrated Containers by deploying a virtual appliance. The appliance runs the vSphere Integrated Containers Registry and vSphere Integrated Containers Management Portal services, and publishes the downloads of the vSphere Integrated Containers Engine binaries. 
 
+**NOTE**: This topic reflects changes to the deployment procedure that were introduced in vSphere Integrated Containers 1.2.1. Do not attempt to deploy version 1.2.0.
 
 **Prerequisites**
 
@@ -36,7 +37,7 @@ You install vSphere Integrated Containers by deploying a virtual appliance. The
 
     Setting the root password for the appliance is mandatory. 
 
-    **IMPORTANT**: You require SSH access to the vSphere Integrated Containers appliance to perform upgrades. You can also use SSH access in exceptional cases that you cannot handle through standard remote management or CLI tools. Other than for upgrade, only use SSH access to the appliance under the guidance of VMware GSS.
+    **IMPORTANT**: You require SSH access to the vSphere Integrated Containers appliance to perform upgrades. You can also use SSH access in exceptional cases that you cannot handle through standard remote management or CLI tools. Only use SSH to access the appliance when instructed to do so in the documentation, or under the guidance of VMware GSS.
 
 5. Expand **Networking Properties** and optionally configure a static IP address for the appliance VM. 
 
@@ -47,13 +48,13 @@ You install vSphere Integrated Containers by deploying a virtual appliance. The
 6. Expand **Registry Configuration** to configure the deployment of vSphere Integrated Containers Registry. 
 
     - In the **Registry Port** text box, optionally change the port on which to publish the vSphere Integrated Containers Registry service.
-    - In the **Notary Port** text box, optionally change the port on which to publish the Docker Notary service for vSphere Integrated Containers Registry.
+    - In the **Notary Port** text box, optionally change the port on which to publish the Docker Content Trust service for vSphere Integrated Containers Registry.
     - Optionally check the **Garbage Collection** check box to enable garbage collection on the registry when the appliance reboots. 
 
 7. Expand **Management Portal Configuration** to configure the deployment of vSphere Integrated Containers Management Portal. 
 
     - In the **Management Portal Port** text box, optionally change the port on which to publish the vSphere Integrated Containers Management Portal service.
-    - To use custom certificates to authenticate connections to vSphere Integrated Containers Management Portal, optionally paste the content of the appropriate certificate and key files in the **SSL Cert** and **SSL Cert Key** text boxes. 
+    - To use custom certificates to authenticate connections to vSphere Integrated Containers Management Portal, optionally paste the content of the appropriate certificate, key, and Certificate Authority (CA) files in the **SSL Cert**, **SSL Cert Key**, and **CA Cert** text boxes. 
 
         **IMPORTANT**: Provide the TLS private key as a PEM-encoded PKCS#8-formatted file.
 
@@ -84,10 +85,15 @@ You install vSphere Integrated Containers by deploying a virtual appliance. The
 
     The network status shows whether the network settings that you provided during the deployment match the settings with which the appliance is running. If there are mismatches, power off the appliance and select **Edit Settings** > **vApp Options** to correct the network settings.
 
-11. In a browser, go to  http://<i>vic_appliance_address</i> and enter the address and single sign-on credentials of the vCenter Server instance on which you deployed the appliance.
+11. In a browser, go to  http://<i>vic_appliance_address</i> and when prompted, enter the connection details for the vCenter Server instance on which you deployed the appliance.
+
+     - The address and single sign-on credentials of vCenter Server.
+     - If vCenter Server is managed by an external Platform Services Controller, enter the FQDN and administrator domain for the Platform Services Controller. If vCenter Server is managed by an embedded Platform Services Controller, leave the External PSC text boxes empty.
 
     **IMPORTANT**: The installation process requires the single sign-on credentials to register vSphere Integrated Containers Management Portal and Registry with the Platform Services Controller and to tag the appliance VM for use in Docker content trust. The vSphere Integrated Containers Management Portal and Registry services cannot start if you do not complete this step.
 
+12. Click **Continue** to initialize the appliance.
+
 **Result**
 
 - You see the vSphere Integrated Containers Getting Started page at http://<i>vic_appliance_address</i>. The Getting Started page includes links to the vSphere Integrated Containers Management Portal, the Demo VCH Installer Wizard, the download for the vSphere Integrated Containers Engine bundle, and to documentation.
@@ -99,8 +105,8 @@ You install vSphere Integrated Containers by deploying a virtual appliance. The
 
 Access the different vSphere Integrated Containers components from the  vSphere Integrated Containers Getting Started page at  http://<i>vic_appliance_address</i>.
 
-- Click the link to go to the **vSphere Integrated Containers Management Portal**. For information about how to use vSphere Integrated Containers Management Portal, see [View and Manage VCHs, Add Registries, and Provision Containers Through the Management Portal](../vic_cloud_admin/vchs_and_mgmt_portal.md).
-- Scroll down to **Infrastructure deployment tools** and click the link to go to the **Demo VCH Installer Wizard**. For information about how to use the interactive VCH installer, see [Deploy a Virtual Container Host Interactively](deploy_demo_vch.md).
+- Click the link to go to the **vSphere Integrated Containers Management Portal**. For information about how to use vSphere Integrated Containers Management Portal, see [Configure and Manage vSphere Integrated Containers](../vic_cloud_admin/).
+- Scroll down to **Infrastructure deployment tools** and click the link to go to the **Demo VCH Installer Wizard**. For information about how to use the interactive demo VCH installer, see [Deploy a Virtual Container Host Interactively](deploy_demo_vch.md).
 - Scroll down to **Infrastructure deployment tools** and click the link to **download the vSphere Integrated Containers Engine bundle**. The vSphere Integrated Containers Engine bundle allows you to perform the following tasks:
 
    - Use `vic-machine` to configure the firewalls on all ESXi hosts to permit VCH deployment. For information about how to configure the firewalls on ESXi hosts, see [Open the Required Ports on ESXi Hosts](open_ports_on_hosts.md).
@@ -109,4 +115,5 @@ Access the different vSphere Integrated Containers components from the  vSphere
 
 - To remove security warnings when you connect to the Getting Started page or management portal, see [Obtain the Thumbprints and CA Files of the vSphere Integrated Containers Appliance Certificates](obtain_appliance_certs.md) and [Verify and Trust vSphere Integrated Containers Appliance Certificates](../vic_cloud_admin/trust_vic_certs.md).
 - If you see a certificate error when you attempt to go to http://<i>vic_appliance_address</i>, see [Browser Rejects Certificates with `ERR_CERT_INVALID` Error](ts_cert_error.md).
-- If necessary, you can reconfigure the appliance after deployment by editing the settings of the appliance VM. For information about reconfiguring the appliance, see [Reconfigure the vSphere Integrated Containers Appliance](reconfigure_appliance.md). 
+
+- If necessary, you can reconfigure the appliance after deployment by editing the settings of the appliance VM. For information about reconfiguring the appliance, see [Reconfigure the vSphere Integrated Containers Appliance](reconfigure_appliance.md).   

docs/user_doc/vic_vsphere_admin/post_upgrade_tasks.md

@@ -0,0 +1,11 @@
+# Tasks to Perform After Upgrading the vSphere Integrated Containers Appliance #
+
+Due to changes in the data model, user identity management, and the merging of the user interfaces for vSphere Integrated Containers Registry and Management Portal in version 1.2.x, you must perform some manual tasks after you upgrade the vSphere Integrated Containers appliance. 
+
+- Import users from the Platform Services Controller into vSphere Integrated Containers Management Portal. For information about users and roles in this version of vSphere Integrated Containers, see the following topics:
+
+  - [User Authentication](../vic_overview/introduction.md#authentication)
+  - [Add Cloud Administrators](../vic_cloud_admin/add_cloud_admins.md)
+  - [Add Viewers, Developers, or DevOps Administrators to Projects](../vic_cloud_admin/add_users.md)
+- If, in version 1.1.x of the appliance, you manually added the vSphere Integrated Containers Registry instance to vSphere Integrated Containers Management Portal, and if the address of the appliance changed during the upgrade, two instances of vSphere Integrated Containers Registry appear in the **Administration** > **Registries** > **Source Registries** view in the new version. The registry named `default-vic-registry` is the new registry instance that is running in the new appliance, that is automatically registered with the management portal. Data from the registry that was running in the previous appliance has migrated to this instance. A registry instance with the name and address from the old, and now defunct, appliance is present in the list of registries. Delete this instance from the list.
+- If you added the same virtual container host (VCH) to more than one placement zone in vSphere Integrated Containers Management Portal 1.1.x, multiple instances of that VCH appear in the **Home** > **Infrastructure** > **Container Hosts** view in the new version. Delete the duplicates. 

docs/user_doc/vic_vsphere_admin/troubleshoot_appliance_upgrade.md

@@ -0,0 +1,3 @@
+# Troubleshooting vSphere Integrated Containers Appliance Upgrade #
+
+Placeholder

docs/user_doc/vic_vsphere_admin/ts_register_psc_fails.md

@@ -8,10 +8,15 @@ When you enter the vCenter Server credentials at the login prompt on the vSphere
 
 ## Cause ##
 
-Your vSphere environment uses an external Platform Services Controller instance that is not embedded in the vCenter Server instance to which you deployed the appliance.
+- You are deploying vSphere Integrated Containers 1.2.0.
+- Your vSphere environment uses an external Platform Services Controller instance that is not embedded in the vCenter Server instance to which you deployed the appliance. 
 
 ## Solution ##
 
+If you are performing a fresh installation of vSphere Integrated Containers, download and deploy version 1.2.1 or later. vSphere Integrated Containers 1.2.1 allows you to register the appliance with an external Platform Services Controller.
+
+If an attempt to upgrade vSphere Integrated Containers 1.1.x to version 1.2.0 failed because vCenter Server is managed by an external Platform Services Controller, perform the following procedure. 
+
 1. Use SSH to connect to the appliance VM as `root` user, using the password that you specified during the OVA deployment.
 
     <pre>ssh root@<i>vic_appliance_address</i></pre>

docs/user_doc/vic_vsphere_admin/upgrade_appliance.md

@@ -4,6 +4,8 @@ If you deployed a 1.1.x version of the vSphere Integrated Containers appliance,
 
 Upgrading the vSphere Integrated Containers appliance upgrades vSphere Integrated Containers Registry and vSphere Integrated Containers Management Portal. For information about the vSphere Integrated Containers Registry and Management Portal data that migrates during upgrade, see [Data That Migrates During vSphere Integrated Containers Appliance Upgrade](upgrade_data.md).
 
+**NOTE**: This topic reflects changes to the upgrade procedure that were introduced in vSphere Integrated Containers 1.2.1. Do not attempt to upgrade to version 1.2.0.
+
 **Prerequisites**
 
 - You have completed the pre-upgrade tasks listed in [Tasks to Perform Before Upgrading the vSphere Integrated Containers Appliance](pre_upgrade_tasks.md).
@@ -48,32 +50,37 @@ Upgrading the vSphere Integrated Containers appliance upgrades vSphere Integrate
 
     <pre>$ ssh root@<i>new_vic_appliance_address</i></pre>
 
+    When prompted for the password, enter the appliance password that you specified when you deployed the new version of the appliance. 
+
 11. Navigate to the upgrade script and run it. 
 
     <pre>$ cd /etc/vmware/upgrade</pre>
-    <pre>$ ./upgrade_1.1_to_1.2.sh</i></pre>
+    <pre>$ ./upgrade.sh</i></pre>
+
+     As the script runs, respond to the prompts to provide the following information: 
 
-     When prompted, enter the address of the vCenter Server instance on which you deployed the new appliance and the Single Sign-On credentials of a vSphere administrator account. The script requires these credentials to register the new version of vSphere Integrated Containers with the VMware Platform Services Controller.
+     1. Enter the address of the vCenter Server instance on which you deployed the new appliance.
+     2. Enter the Single Sign-On user name and password of a vSphere administrator account. The script requires these credentials to register the new version of vSphere Integrated Containers with the VMware Platform Services Controller.
+     3. If vCenter Server is managed by an external Platform Services Controller, enter the FQDN of the Platform Services Controller. If vCenter Server is managed by an embedded Platform Services Controller, press Enter without entering anything.
+     4. If vCenter Server is managed by an external Platform Services Controller, enter the administrator domain for the Platform Services Controller. If vCenter Server is managed by an embedded Platform Services Controller, press Enter without entering anything.
+     5. Verify that the upgrade script has detected your upgrade path correctly.  
+
+         If the upgrade script detects that you are performing an upgrade from 1.1.x to 1.2.y, it migrates 1.1.x data to the new data model for 1.2.y. If it detects an upgrade from 1.2.x to 1.2.y, the data model is the same, so no data migration is required. 
+
+       - If the script detects your upgrade path correctly, enter `y` to proceed with the upgrade.
+       - If the upgrade script detects the upgrade path incorrectly, for example if it asks you to proceed with an upgrade from 1.1.x to 1.2.y when you are upgrading 1.2.x to 1.2.y, enter `n` to abort the upgrade and follow the procedure in [Troubleshooting vSphere Integrated Containers Appliance Upgrade](troubleshoot_appliance_upgrade.md).
 
-11. Go to http://<i>vic_appliance_address</i>, click the link to **Go to the vSphere Integrated Containers Management Portal**, and use vCenter Server Single Sign-On credentials to log in.
+11. When you see confirmation that the upgrade has completed successfully, go to http://<i>vic_appliance_address</i>, click the link to **Go to the vSphere Integrated Containers Management Portal**, and use vCenter Server Single Sign-On credentials to log in.
 
      - In the **Home** tab of the vSphere Integrated Containers Management Portal, check that all existing applications, containers, networks, volumes, and virtual container hosts have migrated successfully.
      - In the **Administration** tab, check that projects, registries, repositories, and replication configurations have migrated successfully.
-
-        **IMPORTANT**: If you added the vSphere Integrated Containers Registry instance from the previous appliance to the previous version of the vSphere Integrated Containers Management Portal,  and if the address of the appliance changed during the upgrade, two instances of vSphere Integrated Containers Registry appear in the **Administration** > **Registries** > **Source Registries** view. The registry named `default-vic-registry` is the registry instance that is running in the new appliance. Data from the registry that was running in the previous appliance has migrated to this instance. A registry instance with the name and address from the old, and now defunct, appliance is present in the list of registries. Delete this instance from the list.
-
-
+12. When you have confirmed that the upgrade succeeded, delete the appliance VM for the previous version from the vCenter Server inventory.
 
 **What to Do Next**
 
-- Delete the previous version of the appliance from the vCenter Server inventory.
 - If, in the previous version, you configured vSphere Integrated Containers Registry instances as replication endpoints, upgrade those registry instances. Replication of images from the 1.2.x registry instance to the 1.1.x replication endpoint still functions, but it is recommended that you upgrade the target registry.
-- Add users to the upgraded vSphere Integrated Containers instance. For information about users in this version of vSphere Integrated Containers, see the following topics:
-
-  - [User Authentication](../vic_overview/introduction.md#authentication)
-  - [Add Cloud Administrators](../vic_cloud_admin/add_cloud_admins.md)
-  - [Add Viewers, Developers, or DevOps Administrators to Projects](../vic_cloud_admin/add_users.md)
-- Download the vSphere Integrated Containers Engine bundle and upgrade VCHs. For information about upgrading VCHs, see [Upgrade Virtual Container Hosts](upgrade_vch.md).
+- Due to changes in the data model, user identity management, and the merging of the user interfaces for vSphere Integrated Containers Registry and Management Portal in version 1.2.x, you must perform some manual tasks after you upgrade the appliance. For information about post-upgrade tasks, see [Tasks to Perform After Upgrading the vSphere Integrated Containers Appliance](post_upgrade_tasks.md).  
+- Download the vSphere Integrated Containers Engine bundle and upgrade  your VCHs. For information about upgrading VCHs, see [Upgrade Virtual Container Hosts](upgrade_vch.md).
 - Upgrade the vSphere Integrated Containers plug-in for the HTML5 vSphere Client. For information about upgrading the vSphere Client plug-in, see 
 
    - [Upgrade the HTML5 vSphere Client Plug-In on vCenter Server for Windows](upgrade_h5_plugin_windows.md)