Document the Initialize Appliance button

[stuclem]

Per #586, I finally understand what this button is for. If #586 gets fixed, then we document when to use it.

If #586 doesn't get fixed, we must document that users must never click it, ever.

[anchal-agrawal]

@stuclem I'm working on #586 to ensure that the Admiral UI doesn't break for 1.2. I'll provide a doc note for this issue once #586 is fixed.

[anchal-agrawal]

Proposed doc for 1.2:

---

The RE-INITIALIZE THE VSPHERE INTEGRATED CONTAINER APPLIANCE button at the bottom of the Getting Started page accepts vCenter credentials and performs two tasks:

• Tags the OVA VM for use in content trust
• Performs PSC registration

In a typical use case, once the OVA appliance is powered on from the vSphere UI, the admin visits the Getting Started page at port 9443, where they enter vCenter credentials. Then, the OVA performs the two tasks above automatically to complete initialization. If this step is successful, the Getting Started page loads with a success alert at the top. Using the Re-initialize button is not needed in this case.

The RE-INITIALIZE THE VSPHERE INTEGRATED CONTAINER APPLIANCE button should be used in two scenarios:

• The initialization step isn't successful and the Getting Started page shows a red error alert instead of a green success alert.
• In some cases, the OVA VM may need to be re-tagged or the OVA may need to be registered with a new PSC instance.
  • To check if the OVA VM is missing its tag, right-click on the OVA VM in the vSphere UI -> Tags & Custom Attributes -> Remove Tag. If the ProductVM tag is missing from the list of tags, re-tagging may be needed.
  • If the OVA is to be registered with a different PSC than what was used initially, the following steps can be performed:
    • SSH to the OVA VM as root user and execute systemctl stop admiral.service. Then, ensure that the Admiral container (named vic-admiral) is removed. If it is still present, it should be removed with docker rm -f vic-admiral.
    • Execute rm /etc/vmware/psc/{admiral,engine,harbor}/psc-config.properties.
    • Press the RE-INITIALIZE THE VSPHERE INTEGRATED CONTAINER APPLIANCE button at the bottom of the Getting Started page and enter vCenter credentials.

---

@stuclem I'm working on verifying the above steps.

[stuclem]

@anchal-agrawal, great, thank you!

[stuclem]

I think that I'll put this in the troubleshooting section, rather than in the installation section. @anchal-agrawal does that seem appropriate to you?

[anchal-agrawal]

Verified that the above steps work for re-registering with PSC on the same vCenter, since I'm unaware of ways to move an OVA to a different vCenter or PSC instance. @andrewtchin and @lgayatri does #681 (comment) look ok?

[anchal-agrawal]

@stuclem I agree that this should be in the troubleshooting section. Passing the baton to you now!

[andrewtchin]

lgtm