docs/libvirt-howto: add faq & troubleshooting #297

steveej · 2018-09-20T20:55:58Z

This also improves the general structure a bit to decrease the likelihood of confusion.

Potentially conflicts with doc changes in #296.

Fixes #311.

Documentation/dev/libvirt-howto.md

wking

Hooray, docs :). A few nits inline.

wking · 2018-09-20T22:12:47Z

Documentation/dev/libvirt-howto.md

@@ -1,33 +1,31 @@
-# Libvirt howto
+# Libvirt HOWTO

 Tectonic has limited support for installing a Libvirt cluster. This is useful especially


Are we ok with dropping "limited" now?

We could say that we support libvirt on Linux

wking · 2018-09-20T22:13:42Z

Documentation/dev/libvirt-howto.md


 *By default, the installer will download the latest RHCOS image every time it is invoked. This may be problematic for users who create a large number of clusters or who have limited network bandwidth. The installer allows a local image to be used instead.*

 Download the latest RHCOS image (you will need access to the Red Hat internal build systems):

 ```sh
-wget http://aos-ostree.rhev-ci-vms.eng.rdu2.redhat.com/rhcos/images/cloud/latest/rhcos-qemu.qcow2.gz
-gunzip rhcos-qemu.qcow2.gz
+curl http://aos-ostree.rhev-ci-vms.eng.rdu2.redhat.com/rhcos/images/cloud/latest/rhcos-qemu.qcow2.gz  | gunzip > rhcos-qemu.qcow2.gz


You want to drop the .gz suffix from the final filename.

You also want a single space before the pipe (you currently have two).

wking · 2018-09-20T22:16:56Z

Documentation/dev/libvirt-howto.md

+
+    For this example:
+
+    ```sh echo server=/tt.testing/192.168.124.1 | sudo tee /etc/NetworkManager/dnsmasq.d/tectonic.conf ```


This doesn't render correctly (you can see the sh). What you want is a traditional fenced block with four-space indents:

Tell dnsmasq...

For this example:

echo server=/tt.testing/192.168.124.1 | sudo tee /etc/NetworkManager/dnsmasq.d/tectonic.conf

Ah, I misread that command to invoke sh, thanks!

wking · 2018-09-20T22:18:21Z

Documentation/dev/libvirt-howto.md

    1. We need to manually remap ports that the loadbalancer would
    2. Only the first server (e.g. master) is actually used. If you want to reach another, you have to manually update the domain name.
+
+## Troubleshooting
+If following the above steps hasn't quite worked please review this section for well known issues.


"... hasn't quite worked, please..." (with a comma).

wking · 2018-09-20T22:20:11Z

Documentation/dev/libvirt-howto.md

+
+### Github Issue Tracker
+You might find other reports of your problem in the [Issues tab for this repository][issues_libvirt] where we ask you to provide any additional information.
+If you're issue is not reported, please do.


"you're" -> "your"

wking · 2018-09-20T22:21:44Z

Documentation/dev/libvirt-howto.md

+
+[bugzilla_libvirt_race]: https://bugzilla.redhat.com/show_bug.cgi?id=1576464
+[tfprovider_libvirt_race]:
+https://github.com/dmacvicar/terraform-provider-libvirt/issues/402#issuecomment-419500064


nit: I'd rather have the URL on the same line as the reference, but GitHub seems to render this correctly, so I'm ok with you deciding to wrap it like this if you feel strongly ;).

wking · 2018-09-20T22:23:21Z

Documentation/dev/libvirt-howto.md

+[libvirt_selinux_issues]: https://github.com/dmacvicar/terraform-provider-libvirt/issues/142#issuecomment-409040151
+[brokenmacosissue201]: https://github.com/openshift/installer/issues/201
+[arch_firewall_superuser]:https://superuser.com/questions/1063240/libvirt-failed-to-initialize-a-valid-firewall-backend
+


Why the blank line?

nit: I like collating these entries by anchor (e.g. highlight them all and use sort-lines in Emacs ;), because then I don't have to think about where to insert new references.

very helpful, thanks

crawford · 2018-09-21T17:44:45Z

Why are e2e tests running on this PR? It's entirely documentation.

steveej · 2018-09-21T19:07:46Z

Why are e2e tests running on this PR? It's entirely documentation.

I had the same thought when I created this PR. @sallyom can you answer that?

abhinavdahiya · 2018-09-21T19:19:06Z

@crawford @steveej ci/prow/e2e-aws — Skipped ci/prow/e2e-aws-smoke — Skipped they don't seem to be running

mrogers950 · 2018-09-21T21:00:57Z

Documentation/dev/libvirt-howto.md


 *By default, the installer will download the latest RHCOS image every time it is invoked. This may be problematic for users who create a large number of clusters or who have limited network bandwidth. The installer allows a local image to be used instead.*

 Download the latest RHCOS image (you will need access to the Red Hat internal build systems):

 ```sh
-wget http://aos-ostree.rhev-ci-vms.eng.rdu2.redhat.com/rhcos/images/cloud/latest/rhcos-qemu.qcow2.gz
-gunzip rhcos-qemu.qcow2.gz
+curl http://aos-ostree.rhev-ci-vms.eng.rdu2.redhat.com/rhcos/images/cloud/latest/rhcos-qemu.qcow2.gz | gunzip > rhcos-qemu.qcow2
 ```


There was a step in @sjenning first screencast instructing how to set enforcing=0 in the qcow image with virt-edit, if that's still necessary we should add that here.

I was about to test it again with that image but the URL doesn't work anymore. Has it changed?

works for me.. are you still on the vpn?

I don't remember being on the VPN for getting that image. Is there a public mirror?

Is there a public mirror?

No, although I don't know what the reasoning is.

There was a step in @sjenning first screencast instructing how to set enforcing=0 in the qcow image with virt-edit, if that's still necessary we should add that here.

It is not necessary anymore

Documentation/dev/libvirt-howto.md

russellb · 2018-09-25T16:04:37Z

Documentation/dev/libvirt-howto.md


 The Kubernetes [cluster-api](https://github.com/kubernetes-sigs/cluster-api)
 components drive deployment of worker machines.  The libvirt cluster-api
 provider will run inside the local cluster, and will need to connect back to
 the libvirt instance on the host machine to deploy workers.

 In order for this to work, you'll need to enable TCP connections for libvirt.
+
+##### Configure libvirtd.conf


did you meant to be at level 4 instead of 5 here?

russellb · 2018-09-25T16:07:17Z

Documentation/dev/libvirt-howto.md

  -j ACCEPT -m comment --comment "Allow insecure libvirt clients"
 ```

+If your uncertain about the libvirt *default* subnet you should be able to see its address using the command `
+ip -4 a show dev virbr0`.


Another command to note would be $ virsh --connect qemu:///system net-dumpxml default to see how the default network has been configured

bparees · 2018-09-25T17:56:57Z

Documentation/dev/libvirt-howto.md

@@ -125,37 +133,40 @@ include the `--permanent` to the commands that add-source and add-port.
    6. Set the `pullSecret` to your JSON pull secret.
    7. (Optional) Change the `image` to the file URL of the operating system image you downloaded (e.g. `file:///home/user/Downloads/rhcos.qcow`). This will allow the installer to re-use that image instead of having to download it every time.


put my content from https://github.com/openshift/installer/pull/323/files in here please. it's all still entirely relevant.

Done, thanks!

bparees · 2018-09-25T18:51:00Z

can you add something about tearing down the cluster?

bparees · 2018-09-25T19:00:43Z

Documentation/dev/libvirt-howto.md

@@ -123,39 +129,45 @@ include the `--permanent` to the commands that add-source and add-port.
    4. Set the `name` (e.g. test1)
    5. Look at the `podCIDR` and `serviceCIDR` fields in the `networking` section. Make sure they don't conflict with anything important.
    6. Set the `pullSecret` to your JSON pull secret.


needs doc on where to get this file. Also @derekwaynecarr showed me it's easier to point to a path than to try to inline the file:
pullSecretPath: "/home/bparees/git/gocode/src/github.com/openshift/installer/files/config.json"

(the reason i say we need doc on where to get this file is i was told not to get it from coreos.com (and i ran into problems trying to do so).

pullSecretPath: "/home/bparees/git/gocode/src/github.com/openshift/installer/files/config.json"

This is deprecated. Once we get the new installer and #320, you'll be able to use OPENSHIFT_INSTALL_PULL_SECRET="$(cat path/to/your/secret)".

bparees · 2018-09-25T19:02:29Z

can you add something about tearing down the cluster?

nm, i see it's there (tectonic destroy)

steveej · 2018-09-26T16:09:09Z

I'm not sure what we're waiting for here. Did I leave any comments unaddressed?

ashcrow · 2018-09-26T20:38:33Z

@crawford do the updates look good?

wking · 2018-09-26T21:09:20Z

docs/dev/libvirt-howto.md

+FATA[0019] failed to run Terraform: exit status 1
+```
+
+it is likely that your install configuration contains three backslashes after the protocol (i.e. `qemu+tcp:///...), when it should only be two.


Nit, missing a trailing backtick here.

All of his requested changes have been addressed.

Since we're instructing to use 192.168.122.1 for the libvirt URI, which is apparently what's used by the clusterapi-controller to talk to libvirt, the firewall has to match, otherwise it looks likt this in the logs: ``` E0924 21:26:08.925983 1 controller.go:115] Error checking existance of machine instance for machine object worker-fdtdg; Failed to build libvirt client: virError(Code=38, Domain=7, Message='unable to connect to server at '192.168.122.1:16509': Connection timed out') ```

wking · 2018-09-26T21:17:09Z

/lgtm

steveej · 2018-09-26T21:18:03Z

/lgtm

You're gonna have to go again, fixed another typo

wking · 2018-09-26T21:26:00Z

/lgtm

openshift-ci-robot · 2018-09-26T21:26:07Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: steveeJ, wking

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [steveeJ,wking]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

openshift-ci-robot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Sep 20, 2018

openshift-ci-robot requested review from abhinavdahiya and crawford September 20, 2018 20:56

openshift-ci-robot added approved Indicates a PR has been approved by an approver from all required OWNERS files. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Sep 20, 2018

crawford previously requested changes Sep 20, 2018

View reviewed changes

Documentation/dev/libvirt-howto.md Outdated Show resolved Hide resolved

Documentation/dev/libvirt-howto.md Outdated Show resolved Hide resolved

Documentation/dev/libvirt-howto.md Outdated Show resolved Hide resolved

wking reviewed Sep 20, 2018

View reviewed changes

mrogers950 reviewed Sep 21, 2018

View reviewed changes

russellb mentioned this pull request Sep 24, 2018

docs/libvirt: Add dependency installation. #315

Merged

wking reviewed Sep 24, 2018

View reviewed changes

Documentation/dev/libvirt-howto.md Outdated Show resolved Hide resolved

russellb reviewed Sep 25, 2018

View reviewed changes

wking mentioned this pull request Sep 25, 2018

add notes about changing libvirt ips #323

Closed

bparees reviewed Sep 25, 2018

View reviewed changes

wking reviewed Sep 26, 2018

View reviewed changes

steveej added 2 commits September 26, 2018 23:10

docs/libvirt-howto: structure and misc improvement

4a4e662

docs/libvirt-howto: add faq & troubleshooting

ffd5eee

steveej added 3 commits September 26, 2018 23:12

docs/dev/libvirt: mention error for wrong URI format

98d1a1d

docs/dev/libvirt: mention error for missing file:/// in image

7550824

openshift-ci-robot assigned wking Sep 26, 2018

openshift-ci-robot added lgtm Indicates that a PR is ready to be merged. and removed lgtm Indicates that a PR is ready to be merged. labels Sep 26, 2018

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Sep 26, 2018

openshift-merge-robot merged commit 22f8f5f into openshift:master Sep 26, 2018

steveej deleted the docs-libvirt-troubleshooting branch September 26, 2018 22:17


		For this example:

		```sh echo server=/tt.testing/192.168.124.1 \| sudo tee /etc/NetworkManager/dnsmasq.d/tectonic.conf ```

		@@ -125,37 +133,40 @@ include the `--permanent` to the commands that add-source and add-port.
		6. Set the `pullSecret` to your JSON pull secret.
		7. (Optional) Change the `image` to the file URL of the operating system image you downloaded (e.g. `file:///home/user/Downloads/rhcos.qcow`). This will allow the installer to re-use that image instead of having to download it every time.

docs/libvirt-howto: add faq & troubleshooting #297

docs/libvirt-howto: add faq & troubleshooting #297

Conversation

steveej commented Sep 20, 2018 • edited Loading

wking left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

crawford commented Sep 21, 2018

steveej commented Sep 21, 2018

abhinavdahiya commented Sep 21, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bparees commented Sep 25, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bparees commented Sep 25, 2018

steveej commented Sep 26, 2018

ashcrow commented Sep 26, 2018

Choose a reason for hiding this comment

wking commented Sep 26, 2018

steveej commented Sep 26, 2018

wking commented Sep 26, 2018

openshift-ci-robot commented Sep 26, 2018

steveej commented Sep 20, 2018 •

edited

Loading

abhinavdahiya commented Sep 21, 2018 •

edited

Loading