doc update suggestions about ocp4-upi-powervs

[ltccci]

@mkumatag: The label(s) kind/doc cannot be applied, because the repository doesn't have them

In response to this:

/kind doc

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[bpradipt]

• Clarify how to tell if you're using a multi-zone capable region:

ibmcloud_zone : (Required) The zone of an IBM Cloud region where you want to create Power System resources. This value is required only when you want to work with a resource in a multizone-capable region.
from https://github.com/ocp-power-automation/ocp4-upi-powervs/blob/release-4.5/docs/quickstart.md#setup-ibm-cloud-powervs-variables

We are not doing multizone for OCP

[clnperez]

• Add a link to https://cloud.ibm.com/docs/power-iaas?topic=power-iaas-creating-power-virtual-server#creating-power-virtual-server from https://github.com/ocp-power-automation/ocp4-upi-powervs/blob/release-4.5/docs/quickstart.md#setup-ibm-cloud-powervs-variables so users can find region names

Edit - marking done. A cli command was added to pull these.

[clnperez]

• Clarify how to tell if you're using a multi-zone capable region:

ibmcloud_zone : (Required) The zone of an IBM Cloud region where you want to create Power System resources. This value is required only when you want to work with a resource in a multizone-capable region.
from https://github.com/ocp-power-automation/ocp4-upi-powervs/blob/release-4.5/docs/quickstart.md#setup-ibm-cloud-powervs-variables

Edit: arking done. Mention of multizone-capable region removed, so that confusion is gone.

[clnperez]

• remove the word cloud from the following description: service_instance_id : (Required) The cloud instance ID of your account. You can get the ID from instance name by using IBM Cloud CLI command: ibmcloud resource service-instance <Name> | grep GUID (This one is just because AFAIK, there's no such thing as a cloud instance in the official documentation, so I think this is unclear.)

edit: not needed. see #65 (comment)

[clnperez]

• For the installer binary tarballs

openshift_install_tarball : (Required) HTTP URL for OpenShift install tarball.
openshift_client_tarball : (Required) HTTP URL for OpenShift client (oc) tarball.

provide a bit more detail such as:

• Do these need to be of the architecture you're installing from (e.g. x86 or Darwin if on my laptop), or the one you're installing to (because this seems to be using RHEL's helpernode repo).
• Provide an example, or just link to the default in the helpernode repo: https://github.com/RedHatOfficial/ocp4-helpernode/blob/ceed6e6326e23e2ce89a3bb213309bc9fb8e9b15/docs/examples/vars-nightlies.yaml#L50-L51
• Also -- why are these commented out completely in vars.tf? Are they not actually required?

Edit: marking done. ppc64le example links and new wording added that clarifies these should be power binaries.

[yussufsh]

* [ ]  remove the word `cloud` from the following description: `service_instance_id : (Required) The cloud instance ID of your account. You can get the ID from instance name by using IBM Cloud CLI command: ibmcloud resource service-instance <Name> | grep GUID`  (This one is just because AFAIK, there's no such thing as a `cloud instance` in the official documentation, so I think this is unclear.)

The descriptions are partially taken from https://cloud.ibm.com/docs/terraform?topic=terraform-power-vsi.

* Do these need to be of the architecture you're installing _from_ (e.g. x86 or Darwin if on my laptop), or the one you're installing _to_ (because this seems to be using RHEL's helpernode repo).

This has to be Power and used for configuring the bastion/helper node. Automation does no change on the client machine (TF terminal).

* Provide an example, or just link to the default in the helpernode repo

This is marked as required, so even if you do not provide any value here the latest ocp version will be used (including pre-release).

* Also -- why are these commented out completely in `vars.tf`? Are they not actually required?

This is required to be populated. Default is provided in https://github.com/ocp-power-automation/ocp4-upi-powervs/blob/master/variables.tf#L239-L245. We removed it from var.tfvars because we have to update it everytime in two places for every version change.

[mkumatag]

/kind doc

[clnperez]

Thanks @yussufsh! Adding all this clarification to the doc will be helpful for users.

[clnperez]

• Add a link to https://cloud.ibm.com/docs/power-iaas-cli-plugin?topic=power-iaas-cli-plugin-power-iaas-cli-reference from https://github.com/ocp-power-automation/ocp4-upi-powervs/blob/release-4.5/docs/quickstart.md#setup-ibm-cloud-powervs-variables so users can find service_instance_id, etc.
  followup: Is there a better way to do this than ibmcloud pi service-list | grep <your_service_name_here> | cut -f 8 -d : ? Is that documented anywhere that we could link to?

Edit: marking done. how-to added with cut command.

[clnperez]

Removing WIP. That's all I've got for now. Thanks!

[clnperez]

@mkumatag @bpradipt who should this be assigned to?

[mkumatag]

@mkumatag @bpradipt who should this be assigned to?

/shrug

[clnperez]

• Put a note in the Cluster Access section that explains how to find the external IP of the bastion node (by scrolling down to the Public networks section under Network Interfaces). I was looking for that at the top section where it lists IPs, assuming that was all the IPs.

Edit: marking done. Terraform command added for retrieving the public IP.

[bpradipt]

I'll make the changes..

[bpradipt]

• Put a note in the Cluster Access section that explains how to find the external IP of the bastion node (by scrolling down to the Public networks section under Network Interfaces). I was looking for that at the top section where it lists IPs, assuming that was all the IPs.

This will be printed as part of the Terraform output and can be retrieved via terraform output as well.

[clnperez]

This will be printed as part of the Terraform output and can be retrieved via terraform output as well.

Ah, missed that with all the other messages scrolling by. Would be nice to add that as a note in addition then, thanks!

[clnperez]

Here's what I see in that old log (ip details removed by me but they're there), in case this is helpful for the doc:

module.prepare.null_resource.bastion_register[0] (remote-exec): Connecting to remote host via SSH...                                                                                                                                          
module.prepare.null_resource.bastion_register[0] (remote-exec):   Host: 192.168.<subnet_removed>.200                                                                                                                                                        
module.prepare.null_resource.bastion_register[0] (remote-exec):   User: root                                                                                                                                                                  
module.prepare.null_resource.bastion_register[0] (remote-exec):   Password: false                                                                                                                                                             
module.prepare.null_resource.bastion_register[0] (remote-exec):   Private key: true                                                                                                                                                           
module.prepare.null_resource.bastion_register[0] (remote-exec):   Certificate: false                                                                                                                                                          
module.prepare.null_resource.bastion_register[0] (remote-exec):   SSH Agent: false                                                                                                                                                            
module.prepare.null_resource.bastion_register[0] (remote-exec):   Checking Host Key: false                                                                                                                                                    
module.prepare.null_resource.bastion_register[0] (remote-exec): Using configured bastion host...                                                                                                                                              
module.prepare.null_resource.bastion_register[0] (remote-exec):   Host: <external_ip_removed>                                                                                                                                                        
module.prepare.null_resource.bastion_register[0] (remote-exec):   User: root                                                                                                                                                                  
module.prepare.null_resource.bastion_register[0] (remote-exec):   Password: false
module.prepare.null_resource.bastion_register[0] (remote-exec):   Private key: true
module.prepare.null_resource.bastion_register[0] (remote-exec):   Certificate: false
module.prepare.null_resource.bastion_register[0] (remote-exec):   SSH Agent: false
module.prepare.null_resource.bastion_register[0] (remote-exec):   Checking Host Key: false

[bpradipt]

Once the deploy completes it'll be shown as the output. This is just progress data

[clnperez]

In this case the deploy is not completing, so I'm troubleshooting by ssh'ing in to the bastion.

[bpradipt]

@clnperez I have updated the docs significantly based on your feedback. Thanks

[clnperez]

@bpradipt changes are great! Closing this. Thanks.