osdocs392 bootstrap gather draft

_topic_map.yml

@@ -101,6 +101,8 @@ Topics:
   Topics:
   - Name: Installing a cluster on vSphere
     File: installing-vsphere
+- Name: Gathering installation logs
+  File: installing-gather-logs
 - Name: Installation configuration
   Dir: install_config
   Topics:

installing/installing-gather-logs.adoc

@@ -0,0 +1,17 @@
+[id="installing-gather-logs"]
+= Gathering installation logs
+include::modules/common-attributes.adoc[]
+:context: installing-troubleshooting
+
+toc::[]
+
+To assist in troubleshooting a failed {product-title} installation, you can
+gather logs from the bootstrap and control plane, or master, machines.
+
+.Prerequisites
+
+* You attempted to install a {product-title} cluster, and installation failed.
+* You provided an SSH key to the installation program, and that key is in your
+running `ssh-agent` process.
+
+include::modules/installation-bootstrap-gather.adoc[leveloffset=+1]

installing/installing_aws/installing-aws-customizations.adoc

@@ -21,6 +21,8 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-provide-credentials.adoc[leveloffset=+1]
 
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
 include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
 include::modules/installation-initializing.adoc[leveloffset=+1]

installing/installing_aws/installing-aws-default.adoc

@@ -21,6 +21,8 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-provide-credentials.adoc[leveloffset=+1]
 
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
 include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
 include::modules/installation-launching-installer.adoc[leveloffset=+1]

installing/installing_aws/installing-aws-network-customizations.adoc

@@ -31,6 +31,8 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-provide-credentials.adoc[leveloffset=+1]
 
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
 include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
 include::modules/installation-initializing.adoc[leveloffset=+1]

installing/installing_aws_user_infra/installing-aws-user-infra.adoc

@@ -33,6 +33,8 @@ include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
 include::modules/installation-provide-credentials.adoc[leveloffset=+1]
 
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
 include::modules/installation-generate-aws-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-extracting-infraid.adoc[leveloffset=+1]

installing/installing_bare_metal/installing-bare-metal.adoc

@@ -24,6 +24,8 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
 include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
 include::modules/cli-install.adoc[leveloffset=+1]

installing/installing_vsphere/installing-vsphere.adoc

@@ -24,6 +24,8 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
 include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
 include::modules/installation-initializing-manual.adoc[leveloffset=+1]

modules/installation-aws-config-yaml.adoc

@@ -89,3 +89,10 @@ control plane pool is used.
 storage type as `io1` and set `iops` to `2000`.
 <5> You can optionally provide the `sshKey` value that you use to access the
 machines in your cluster.
++
+[NOTE]
+====
+For production {product-title} clusters on which you want to perform installation
+debugging or disaster recovery, you must provide an SSH key that your `ssh-agent`
+process uses to the installer.
+====

modules/installation-bare-metal-config-yaml.adoc

@@ -58,3 +58,10 @@ one IP address pool.
 provided by the included authorities, including Quay.io, which serves the
 container images for {product-title} components.
 <10> The default SSH key for the `core` user.
++
+[NOTE]
+====
+For production {product-title} clusters on which you want to perform installation
+debugging or disaster recovery, you must provide an SSH key that your `ssh-agent`
+process uses to the installer.
+====

modules/installation-bootstrap-gather.adoc

@@ -0,0 +1,102 @@
+// Module included in the following assemblies:
+//
+// *installing/installing-gather-logs.adoc
+
+[id="installation-bootstrap-gather_{context}"]
+= Gathering logs from a failed installation
+
+If you gave an SSH key to your installer, you can gather data about your failed
+installation.
+
+[NOTE]
+====
+You use a different command to gather logs about an unsuccessful installation
+than to gather logs from a running cluster. If you need to gather logs from a
+running cluster, use the `oc adm must-gather` command.
+====
+
+.Prerequisites
+
+* Your {product-title} installation failed before the bootstrap process
+finished. The bootstrap node must be running and accessible through SSH.
+* The `ssh-agent` process is active on your computer, and you provided both the
+`ssh-agent` process and the installer the same SSH key.
+* If you tried to install a cluster on infrastructure that you provisioned, you
+must have the fully-qualified domain names of the control plane, or master,
+machines.
+
+.Procedure
+
+. Generate the commands that are required to obtain the installation logs from
+the bootstrap and control plane machines:
++
+--
+** If you used installer-provisioned infrastructure, run the following command:
++
+----
+$ ./openshift-install gather bootstrap --dir=<directory> <1>
+----
+<1> `installation_directory` is the directory you stored the {product-title}
+definition files that the installation program creates.
++
+For installer-provisioned infrastructure, the installation program stores
+information about the cluster, so you do not specify the host names or IP
+addresses
+
+** If you used infrastructure that you provisioned yourself, run the following
+command:
++
+----
+$ ./openshift-install gather bootstrap --dir=<directory> \ <1>
+    --bootstrap <bootstrap_address> \ <2>
+    --master "<master_address> <master_address> <master_address>" <3>
+----
+<1> `installation_directory` is the directory you stored the {product-title}
+definition files that the installation program creates.
+<2> `<bootstrap_address>` is the fully-qualified domain name or IP address of
+the cluster's bootstrap machine.
+<3> `<master_address>` is the fully-qualified domain name or IP address of a
+control plane, or master, machine in your cluster. Specify a space-delimited
+list that contains all the control plane machines in your cluster.
+--
++
+The command output resembles the following example:
++
+----
+INFO Use the following commands to gather logs from the cluster
+INFO ssh -A core@<bootstrap_address> '/usr/local/bin/installer-gather.sh <master_address> <master_address> <master_address>'
+INFO scp core@<bootstrap_address>:~/log-bundle.tar.gz .
+----
++
+You use both commands that are displayed to gather and download the logs.
+
+. Gather logs from the bootstrap and master machines:
++
+----
+$ ssh -A core@<bootstrap_address> '/usr/local/bin/installer-gather.sh <master_address> <master_address> <master_address>'
+----
++
+You SSH into the bootstrap machine and run the gather tool, which is designed to
+collect as much data as possible from the bootstrap and control plane machines
+in your cluster and compress all of the gathered files.
++
+[NOTE]
+====
+It is normal to see errors in the command output. If the command output
+displays the instructions to download the compressed log files,
+`log-bundle.tar.gz`, then the command succeeded.
+====
+
+. Download the compressed file that contains the logs:
++
+----
+$ scp core@<bootstrap_address>:~/log-bundle.tar.gz . <1>
+----
+<1> `<bootstrap_address>` is the fully-qualified domain name or IP address of the bootstrap
+machine.
++
+The command to download the log files is included at the end of the gather
+command output.
++
+If you open a Red Hat support case about your installation failure, include
+the compressed logs in the case.

modules/installation-configuration-parameters.adoc

@@ -74,13 +74,19 @@ container images for {product-title} components.
 
 
 .Optional AWS platform parameters
-[cols=".^2,.^3,.^3a",options="header"]
+[cols=".^2,.^3a,.^3a",options="header"]
 |====
 |Parameter|Description|Values
 
 |`sshKey`
 |The SSH key to use to access your cluster machines.
-|A valid public SSH key.
+[NOTE]
+====
+For production {product-title} clusters on which you want to perform installation
+debugging or disaster recovery, you must provide an SSH key that your `ssh-agent`
+process uses to the installer.
+====
+|A valid, local public SSH key that you added to the `ssh-agent` process.
 
 |`compute.platform.aws.rootVolume.iops`
 |The Input/Output Operations Per Second (IOPS) that is reserved for the root volume.

modules/installation-generate-aws-user-infra.adoc

@@ -34,6 +34,13 @@ $ ./openshift-install create install-config --dir=<installation_directory> <1>
 files that the installation program creates.
 .. At the prompts, provide the configuration details for your cloud:
 ... Optionally, select an SSH key to use to access your cluster machines.
++
+[NOTE]
+====
+For production {product-title} clusters on which you want to perform installation
+debugging or disaster recovery, you must provide an SSH key that your `ssh-agent`
+process uses to the installer.
+====
 ... Select AWS as the platform to target.
 ... Select the AWS region to deploy the cluster to.
 ... Select the base domain for the Route53 service that you configured for your cluster.

modules/installation-initializing.adoc

@@ -25,6 +25,13 @@ $ ./openshift-install create install-config --dir=<installation_directory> <1>
 files that the installation program creates.
 .. At the prompts, provide the configuration details for your cloud:
 ... Optionally, select an SSH key to use to access your cluster machines.
++
+[NOTE]
+====
+For production {product-title} clusters on which you want to perform installation
+debugging or disaster recovery, you must provide an SSH key that your `ssh-agent`
+process uses to the installer.
+====
 ... Select AWS as the platform to target.
 ... Select the AWS region to deploy the cluster to.
 ... Select the base domain for the Route53 service that you configured for your cluster.

modules/installation-launching-installer.adoc

@@ -43,6 +43,13 @@ files that the installation program creates.
 Provide values at the prompts:
 
 .. Optionally, select an SSH key to use to access your cluster machines.
++
+[NOTE]
+====
+For production {product-title} clusters on which you want to perform installation
+debugging or disaster recovery, you must provide an SSH key that your `ssh-agent`
+process uses to the installer.
+====
 .. Select AWS as the platform to target.
 .. Select the AWS region to deploy the cluster to.
 .. Select the base domain for the Route53 service that you configured for your cluster.

modules/installation-provide-credentials.adoc

@@ -60,16 +60,4 @@ configured. If an error displays, configure your credentials again.
 ----
 $ export AWS_PROFILE=<profile_name> <1>
 ----
-<1> Enter the `<profile_name>` that you specified.
-
-. Optionally, create an SSH key to use to access machines in your cluster. You
-can use this key to SSH into the master nodes as the user `core`. When you
-deploy the cluster, the key is added to the `core` user's
-`~/.ssh/authorized_keys` list.
-+
-[NOTE]
-====
-Use a local key, not one that you configured with platform-specific approaches
-such as
-link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[AWS key pairs].
-====
+<1> Enter the `<profile_name>` that you specified.

modules/installation-vsphere-config-yaml.adoc

@@ -46,4 +46,11 @@ in vSphere.
 <9> The pull secret that allows you to authenticate with the services that are
 provided by the included authorities, including Quay.io, which serves the
 container images for {product-title} components.
-<10> The default SSH key for the `core` user in {op-system-first}.
+<10> The default SSH key for the `core` user in {op-system-first}.
++
+[NOTE]
+====
+For production {product-title} clusters on which you want to perform installation
+debugging or disaster recovery, you must provide an SSH key that your `ssh-agent`
+process uses to the installer.
+====

modules/ssh-agent-using.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-default.adoc
+// * installing/installing_aws/installing-aws-customizations.adoc
+// * installing/installing_aws/installing-aws-network-customizations.adoc
+// * installing/installing_aws_upi/installing-aws-upi.adoc
+// * installing/installing_bare_metal/installing-bare-metal.adoc
+// * installing/installing_vsphere/installing-vsphere.adoc
+
+[id="ssh-agent-using_{context}"]
+= Generating an SSH private key and adding it to the agent
+
+For production {product-title} clusters on which you want to perform installation
+debugging or disaster recovery, you must provide an SSH key that your `ssh-agent`
+process uses to the installer.
+
+You can use this key to SSH into the master nodes as the user `core`. When you
+deploy the cluster, the key is added to the `core` user's
+`~/.ssh/authorized_keys` list.
+
+[NOTE]
+====
+You must use a local key, not one that you configured with platform-specific
+approaches such as
+link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[AWS key pairs].
+====
+
+.Procedure
+
+. If you do not have an SSH key that is configured for password-less authentication
+on your computer, create one.
+For example, on a computer that uses a Linux operating system, run the
+following command:
++
+----
+$ ssh-keygen -t rsa -b 4096 \
+    -f <path>/<file_name>
+
+    ssh-keygen -t rsa -b 4096 -N '' \
+        -f ~/.ssh/new_rsa  <1>
+----
+<1> Specify the path and file name, such as `~/.ssh/id_rsa`, of the SSH key.
++
+Running this command generates an SSH key that does not require a password in
+the location that you specified.
+
+. Start the `ssh-agent` process as a background task:
++
+----
+$ eval "$(ssh-agent -s)"
+
+Agent pid 31874
+----
+
+. Add your SSH private key to the `ssh-agent`:
++
+----
+$ ssh-add <path>/<file_name> <1>
+
+Identity added: /home/<you>/.ssh/new_rsa (<computer_name>)
+----
+<1> Specify the path and file name for your SSH private key, such as `~/.ssh/id_rsa`
+
+
+.Next steps
+
+When you install {product-title}, provide the SSH public key to the installer.
+If you install a cluster on infrastructure that you provision, you must provide
+this key to your cluster's machines.