From 5d187536b317af3f3b6beef8683bdf9e71ae3c6c Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 10:03:30 +0100 Subject: [PATCH 01/16] Add troubleshooting docs --- docs/source/user_guide/troubleshooting.md | 32 +++++++++++++++++++++++ qhub/stages/checks.py | 2 +- 2 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 docs/source/user_guide/troubleshooting.md diff --git a/docs/source/user_guide/troubleshooting.md b/docs/source/user_guide/troubleshooting.md new file mode 100644 index 0000000000..efb86bffeb --- /dev/null +++ b/docs/source/user_guide/troubleshooting.md @@ -0,0 +1,32 @@ +# Troubleshooting Guide + +## "DNS domain=`your_qhub_domain` record does not exist" + +### *Issue* +During your initial QHub deployment, at the end of "04-kubernetes-ingress" stage, you receive an output message stating that the DNS record for `your_qhub_domain` "appears not to exist, has recently been updated, or has yet to fully propogate." + +### *Reason for observed behavior* +As the output message mentions, this is likely the result of the non-deterministic behavior of DNS. + +Without going into a deep dive of what DNS is or how it works, the issue encountered here is that the when QHub tries to lookup the IP address associated with the DNS record, `your_qhub_domain`, nothing is returned. Unfortunately, this "lookup" is not as straight-forward as it sounds. To lookup the correct IP associated with this domain, many intermediate servers (root, TLD, and authorative nameservers) are checked, each with their own cache which was updated an unknown time ago (usually on the order of minutes but not always). + +For those who are interested to learn more about DNS, see [this CloudFlare article](https://www.cloudflare.com/learning/dns/what-is-dns/)). + +### *Troubleshooting* +Again, as the output message mentions, it will ask if you want it to retry this DNS lookup again after another wait period; this wait period keeps increasing after each retry. However, it is still possible that after waiting 15 or more minutes that the DNS still cannot be resolved. + +At this point, feel free to cancel the deployment and rerun the same deployment command again in an hour or two. Although not guaranteed, it is extremely likely that the DNS will resolve correctly after this prolonged wait period. + + +## A Conda-Store environment fails to build + +### *Issue* +One of the two (`dashboard` or `dask`) Conda-Store environments created during the initial QHub deployment fails to appear as options when logged into JupyterHub. + +If your user has access to Conda-Store, you can verify this by visiting `.com/conda-store` and having a look at the build status of the missing environment. + +### *Reason for observed behavior* +The reason for this issue is due to how these environments are simulataneously built. Under the hood, Conda-Store relies on Mamba/Conda to resolve and download the specific packages listed in the environment YAML. If they both environment builds try to download the same package with different versions, the build that started first will have their package overwritten by the second build. This causes the first build to fail. + +### *Troubleshooting* +To resolve this issue, navigate to `.com/conda-store`, find the environment build that failed and trigger it to re-build. diff --git a/qhub/stages/checks.py b/qhub/stages/checks.py index 995cf2321c..e2c7917a6d 100644 --- a/qhub/stages/checks.py +++ b/qhub/stages/checks.py @@ -81,7 +81,7 @@ def _attempt_tcp_connect(host, port, num_attempts=NUM_ATTEMPTS, timeout=TIMEOUT) s.settimeout(5) result = s.connect_ex((ip, port)) if result == 0: - print(f"Attempt {i+1} succedded to connect to tcp://{ip}:{port}") + print(f"Attempt {i+1} succeded to connect to tcp://{ip}:{port}") return True print(f"Attempt {i+1} failed to connect to tcp tcp://{ip}:{port}") except socket.gaierror: From b8ed0c77640dd27e1f340aa331a97d54cb2e2e9c Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 10:03:46 +0100 Subject: [PATCH 02/16] Fix vale errors in login.md --- docs/source/installation/login.md | 20 +++++++++++--------- tests/vale/styles/vocab.txt | 2 ++ 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index fabef987d2..a4fe325752 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -8,10 +8,10 @@ The `root` Keycloak user is only able to login and manage the Keycloak identity ## Change Keycloak root password -After the inital deployment, it is **highly** recommended that you change the Keycloak `root` user password as soon as you can. +After the initial deployment, it is **highly** recommended that you change the Keycloak `root` user password as soon as you can. > NOTE: From this point on, the `security.keycloak.initial_root_password` field in `qhub-config.yaml` has no effect. If you redeploy QHub it will not reset the password back to the old one (or anything else that might be in the field in your YAML file). We strongly recommend you delete this field. -To change the `root` user password, navigate to `https://myqhubsite.com/auth/admin/`, and login with the pasword provided. +To change the `root` user password, navigate to `https://myqhubsite.com/auth/admin/`, and login with the password provided. ![Root Login to Keycloak](../images/keycloak_master_login.png) @@ -39,7 +39,7 @@ To add a QHub user from the web console for Keycloak, visit NOTE: The root user alone is a member of the `master` realm. -The `qhub` realm should be selected by default. +The `qhub` realm is selected by default, we strongly recommend leaving it as is. Click 'Users' along the left-hand side of the page. @@ -47,7 +47,7 @@ Click the 'Add user' button and you will see the new user form: ![Keycloak add user tab screenshot - new user form ](../images/keycloak_add_users.png) -There are three fields, outlined above, which should be filled out. These are 'Username', 'Email', and 'Groups'. +Please fill out the three fields, outlined above. These are 'Username', 'Email', and 'Groups'. Depending on the authentication provider selected ('password', 'GitHub' or 'Auth0'), the values entered into the 'Username' field will differ slightly. The following table outlines those differences: @@ -55,15 +55,15 @@ Depending on the authentication provider selected ('password', 'GitHub' or 'Auth |---|---|---|---| | Username | *unique username* | *GitHub username* | *Email to login with* | -Once the 'Username' field has been updated, please add a valid email address in the 'Email' field. -> NOTE: Although not required, users may not be able to log into Graphana if this field is not properly set. +Once the 'Username' field is updated, please add a valid email address in the 'Email' field. +> NOTE: Although not required, users may not be able to log into Grafana if this field isn't properly set. Lastly, associate the user with one or more of the 'Groups'. Out of the box, QHub is deployed with the following groups: 'admin', 'analyst', and 'developer' (see below for more information about 'Groups'). Enter the name you would like for the user then click 'Save'. -Once the user has been created, you can set a password -> NOTE: not needed for GitHub/Auth0 based authentication. +Once the user is created, you can set a password. +> NOTE: Not needed for GitHub/Auth0 based authentication. ![Keycloak add user > credentials tab screenshot - set password](../images/keycloak_user_password.png) @@ -71,7 +71,9 @@ It's best to unset the 'Temporary' on/off button so the user won't be forced to ### Add user from command line -To make adding users easier for new QHub deployments, there is a QHub command that can help. It will only work if the initial_root_password for Keycloak has not yet been changed, so the value available in `qhub-config.yaml` is still correct. +To make adding users easier for new QHub deployments, there is a QHub command that can help. +> NOTE: If you changed the initial_root_password for Keycloak this method will not work. +> NOTE: This method is primarily used by developers as a quick workaround. Run: diff --git a/tests/vale/styles/vocab.txt b/tests/vale/styles/vocab.txt index e1fa00406e..4ddc142a3f 100644 --- a/tests/vale/styles/vocab.txt +++ b/tests/vale/styles/vocab.txt @@ -1,4 +1,5 @@ addons +admin Anand api apis @@ -43,6 +44,7 @@ eks EKS elasticsearch emacs +Email env gcp git From 5167521b340fb0a90a6e6374fcb5b244922b40a3 Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 10:17:52 +0100 Subject: [PATCH 03/16] Vale fixes --- docs/source/user_guide/troubleshooting.md | 14 +++++++------- qhub/stages/checks.py | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/user_guide/troubleshooting.md b/docs/source/user_guide/troubleshooting.md index efb86bffeb..a8850b8274 100644 --- a/docs/source/user_guide/troubleshooting.md +++ b/docs/source/user_guide/troubleshooting.md @@ -1,21 +1,21 @@ -# Troubleshooting Guide +# Troubleshooting guide ## "DNS domain=`your_qhub_domain` record does not exist" ### *Issue* -During your initial QHub deployment, at the end of "04-kubernetes-ingress" stage, you receive an output message stating that the DNS record for `your_qhub_domain` "appears not to exist, has recently been updated, or has yet to fully propogate." +During your initial QHub deployment, at the end of "04-kubernetes-ingress" stage, you receive an output message stating that the DNS record for `your_qhub_domain` "appears not to exist, has recently been updated, or has yet to fully propagate." ### *Reason for observed behavior* As the output message mentions, this is likely the result of the non-deterministic behavior of DNS. -Without going into a deep dive of what DNS is or how it works, the issue encountered here is that the when QHub tries to lookup the IP address associated with the DNS record, `your_qhub_domain`, nothing is returned. Unfortunately, this "lookup" is not as straight-forward as it sounds. To lookup the correct IP associated with this domain, many intermediate servers (root, TLD, and authorative nameservers) are checked, each with their own cache which was updated an unknown time ago (usually on the order of minutes but not always). +Without going into a deep dive of what DNS is or how it works, the issue encountered here is that the when QHub tries to lookup the IP address associated with the DNS record, `your_qhub_domain`, nothing is returned. Unfortunately, this "lookup" is not as straight-forward as it sounds. To lookup the correct IP associated with this domain, many intermediate servers (root, top level domain, and authoritative nameservers) are checked, each with their own cache which was updated an unknown time ago (usually on the order of minutes but not always). -For those who are interested to learn more about DNS, see [this CloudFlare article](https://www.cloudflare.com/learning/dns/what-is-dns/)). +For those interested to learn more about DNS, see [this CloudFlare article](https://www.cloudflare.com/learning/dns/what-is-dns)). ### *Troubleshooting* -Again, as the output message mentions, it will ask if you want it to retry this DNS lookup again after another wait period; this wait period keeps increasing after each retry. However, it is still possible that after waiting 15 or more minutes that the DNS still cannot be resolved. +Again, as the output message mentions, it will ask if you want it to retry this DNS lookup again after another wait period; this wait period keeps increasing after each retry. However, it's still possible that after waiting 15 or more minutes that the DNS still won't resolve. -At this point, feel free to cancel the deployment and rerun the same deployment command again in an hour or two. Although not guaranteed, it is extremely likely that the DNS will resolve correctly after this prolonged wait period. +At this point, feel free to cancel the deployment and rerun the same deployment command again in an hour or two. Although not guaranteed, it's extremely likely that the DNS will resolve correctly after this prolonged wait period. ## A Conda-Store environment fails to build @@ -26,7 +26,7 @@ One of the two (`dashboard` or `dask`) Conda-Store environments created during t If your user has access to Conda-Store, you can verify this by visiting `.com/conda-store` and having a look at the build status of the missing environment. ### *Reason for observed behavior* -The reason for this issue is due to how these environments are simulataneously built. Under the hood, Conda-Store relies on Mamba/Conda to resolve and download the specific packages listed in the environment YAML. If they both environment builds try to download the same package with different versions, the build that started first will have their package overwritten by the second build. This causes the first build to fail. +The reason for this issue is due to how these environments are simultaneously built. Under the hood, Conda-Store relies on Mamba/Conda to resolve and download the specific packages listed in the environment YAML. If they both environment builds try to download the same package with different versions, the build that started first will have their package overwritten by the second build. This causes the first build to fail. ### *Troubleshooting* To resolve this issue, navigate to `.com/conda-store`, find the environment build that failed and trigger it to re-build. diff --git a/qhub/stages/checks.py b/qhub/stages/checks.py index e2c7917a6d..20e0f70376 100644 --- a/qhub/stages/checks.py +++ b/qhub/stages/checks.py @@ -152,7 +152,7 @@ def _attempt_dns_lookup( if not disable_prompt: input( f"After attempting to poll the DNS, the record for domain={domain_name} appears not to exist, " - f"has recently been updated, or has yet to fully propogate. This non-deterministic behavior is likely due to " + f"has recently been updated, or has yet to fully propagate. This non-deterministic behavior is likely due to " f"DNS caching and will likely resolve itself in a few minutes.\n\n\tTo poll the DNS again in {sleeptime} seconds " f"[Press Enter].\n\n...otherwise kill the process and run the deployment again later..." ) From b213c997c097e3868128c686f65d783a46a19036 Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 10:26:05 +0100 Subject: [PATCH 04/16] Swap out DNS doc ref --- docs/source/user_guide/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/user_guide/troubleshooting.md b/docs/source/user_guide/troubleshooting.md index a8850b8274..9a94e63dcf 100644 --- a/docs/source/user_guide/troubleshooting.md +++ b/docs/source/user_guide/troubleshooting.md @@ -10,7 +10,7 @@ As the output message mentions, this is likely the result of the non-determinist Without going into a deep dive of what DNS is or how it works, the issue encountered here is that the when QHub tries to lookup the IP address associated with the DNS record, `your_qhub_domain`, nothing is returned. Unfortunately, this "lookup" is not as straight-forward as it sounds. To lookup the correct IP associated with this domain, many intermediate servers (root, top level domain, and authoritative nameservers) are checked, each with their own cache which was updated an unknown time ago (usually on the order of minutes but not always). -For those interested to learn more about DNS, see [this CloudFlare article](https://www.cloudflare.com/learning/dns/what-is-dns)). +For those interested to learn more about DNS, see [this CloudFlare article](https://howdns.works/)). ### *Troubleshooting* Again, as the output message mentions, it will ask if you want it to retry this DNS lookup again after another wait period; this wait period keeps increasing after each retry. However, it's still possible that after waiting 15 or more minutes that the DNS still won't resolve. From 62ef7db8fab1aafd1ccb7b5e9cb5f1e0557c099f Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Mar 2022 13:18:15 +0000 Subject: [PATCH 05/16] =?UTF-8?q?=F0=9F=93=9D=20=20Minor=20improvements=20?= =?UTF-8?q?to=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/source/installation/login.md | 20 +++++++++++--------- tests/vale/styles/vocab.txt | 1 + 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index a4fe325752..103200637c 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -11,21 +11,21 @@ The `root` Keycloak user is only able to login and manage the Keycloak identity After the initial deployment, it is **highly** recommended that you change the Keycloak `root` user password as soon as you can. > NOTE: From this point on, the `security.keycloak.initial_root_password` field in `qhub-config.yaml` has no effect. If you redeploy QHub it will not reset the password back to the old one (or anything else that might be in the field in your YAML file). We strongly recommend you delete this field. -To change the `root` user password, navigate to `https://myqhubsite.com/auth/admin/`, and login with the password provided. +1. To change the `root` user password, navigate to `https://myqhubsite.com/auth/admin/`, and login with the password provided. ![Root Login to Keycloak](../images/keycloak_master_login.png) -From there, click on the 'Root' dropdown in the top right of the screen, and select 'Manage account'. +2. From there, click on the 'Root' dropdown in the top right of the screen, and select 'Manage account'. -![Keycloak root user, manage account](../images/keycloak_root_user_manage_account.png) +![Keycloak root user page - manage account tab selected](../images/keycloak_root_user_manage_account.png) -Under 'Account Security' click 'Signing In'. +3. Under 'Account Security' click 'Signing In'. -![Keycloak root user, account security](../images/keycloak_root_user_account_security.png) +![Keycloak root user page - account security](../images/keycloak_root_user_account_security.png) -In the Password box, click the 'Update' button. This will guide you through entering your existing root password, and then creating a new password. +4. In the Password section, click the 'Update' button. This will guide you through entering your existing root password, and then creating a new password. -![Keycloak root user, update password](../images/keycloak_root_user_update_password.png) +![Keycloak root user page - account security, update password](../images/keycloak_root_user_update_password.png) ## Adding a QHub user @@ -37,6 +37,7 @@ You will need to add a QHub user in order to log in to your QHub platform. If yo To add a QHub user from the web console for Keycloak, visit . Log in using the username `root`, as shown above. All QHub users will be part of the `qhub` realm (a realm is a distinct identity provider and set of users in Keycloak). + > NOTE: The root user alone is a member of the `master` realm. The `qhub` realm is selected by default, we strongly recommend leaving it as is. @@ -82,13 +83,14 @@ qhub keycloak -c qhub-config.yaml adduser ``` This will create a user `` with the initial password provided. Omit the password completely if you are using GitHub or Auth0. + > NOTE: This will also add the user to 'analyst' group. ## Login to QHub -Your new user can now log into QHub proper (not Keycloak's admin console). +Your new user can now log into the main QHub dashboard (not Keycloak's admin console). -Visit `https://myqhubsite.com/` (or whatever domain you have chosen for your QHub). +Visit (or whatever domain you have chosen for your QHub). Click 'Sign in with Keycloak'. diff --git a/tests/vale/styles/vocab.txt b/tests/vale/styles/vocab.txt index 4ddc142a3f..947c929ce0 100644 --- a/tests/vale/styles/vocab.txt +++ b/tests/vale/styles/vocab.txt @@ -35,6 +35,7 @@ dev digital Dockerfile Dockerfiles +docstrings doctl ebs EBS From 31747661d697764ab0a02e80d08e067d78c452fd Mon Sep 17 00:00:00 2001 From: eskild <42120229+iameskild@users.noreply.github.com> Date: Thu, 3 Mar 2022 15:51:36 +0100 Subject: [PATCH 06/16] Update docs/source/installation/login.md Co-authored-by: Tania Allard --- docs/source/installation/login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index 103200637c..3e7b5c2137 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -13,7 +13,7 @@ After the initial deployment, it is **highly** recommended that you change the K 1. To change the `root` user password, navigate to `https://myqhubsite.com/auth/admin/`, and login with the password provided. -![Root Login to Keycloak](../images/keycloak_master_login.png) +![QhHub admin view - Root Login to Keycloak form](../images/keycloak_master_login.png) 2. From there, click on the 'Root' dropdown in the top right of the screen, and select 'Manage account'. From d0b5d21e280f660ba9d88bf925dda753ba3c630f Mon Sep 17 00:00:00 2001 From: eskild <42120229+iameskild@users.noreply.github.com> Date: Thu, 3 Mar 2022 15:54:29 +0100 Subject: [PATCH 07/16] Update docs/source/installation/login.md Co-authored-by: Tania Allard --- docs/source/installation/login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index 3e7b5c2137..5783415667 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -48,7 +48,7 @@ Click the 'Add user' button and you will see the new user form: ![Keycloak add user tab screenshot - new user form ](../images/keycloak_add_users.png) -Please fill out the three fields, outlined above. These are 'Username', 'Email', and 'Groups'. +Fill out the three fields, outlined above. These are 'Username', 'Email', and 'Groups'. Depending on the authentication provider selected ('password', 'GitHub' or 'Auth0'), the values entered into the 'Username' field will differ slightly. The following table outlines those differences: From a4ad95b588fc88b8480c1b2f7f8f84736c0690d0 Mon Sep 17 00:00:00 2001 From: eskild <42120229+iameskild@users.noreply.github.com> Date: Thu, 3 Mar 2022 15:54:56 +0100 Subject: [PATCH 08/16] Update docs/source/installation/login.md Co-authored-by: Tania Allard --- docs/source/installation/login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index 5783415667..938038a05f 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -70,7 +70,7 @@ Once the user is created, you can set a password. It's best to unset the 'Temporary' on/off button so the user won't be forced to change the password on first login. -### Add user from command line +### Add user from the command line To make adding users easier for new QHub deployments, there is a QHub command that can help. > NOTE: If you changed the initial_root_password for Keycloak this method will not work. From 2ca3aa5601351ca4f3bd65151841aa44837bff6e Mon Sep 17 00:00:00 2001 From: eskild <42120229+iameskild@users.noreply.github.com> Date: Thu, 3 Mar 2022 15:55:20 +0100 Subject: [PATCH 09/16] Update docs/source/installation/login.md Co-authored-by: Tania Allard --- docs/source/installation/login.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index 938038a05f..4ad06635cd 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -73,6 +73,10 @@ It's best to unset the 'Temporary' on/off button so the user won't be forced to ### Add user from the command line To make adding users easier for new QHub deployments, there is a QHub command that can help. + +> NOTE: If you changed the initial_root_password for Keycloak this method will not work. + +> NOTE: This method is primarily used by developers as a quick workaround. > NOTE: If you changed the initial_root_password for Keycloak this method will not work. > NOTE: This method is primarily used by developers as a quick workaround. From 2b11c33448ed5824926c7da38b61a778e47d9108 Mon Sep 17 00:00:00 2001 From: eskild <42120229+iameskild@users.noreply.github.com> Date: Thu, 3 Mar 2022 15:55:54 +0100 Subject: [PATCH 10/16] Update docs/source/user_guide/troubleshooting.md Co-authored-by: Tania Allard --- docs/source/user_guide/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/user_guide/troubleshooting.md b/docs/source/user_guide/troubleshooting.md index 9a94e63dcf..8e0a1f2618 100644 --- a/docs/source/user_guide/troubleshooting.md +++ b/docs/source/user_guide/troubleshooting.md @@ -3,7 +3,7 @@ ## "DNS domain=`your_qhub_domain` record does not exist" ### *Issue* -During your initial QHub deployment, at the end of "04-kubernetes-ingress" stage, you receive an output message stating that the DNS record for `your_qhub_domain` "appears not to exist, has recently been updated, or has yet to fully propagate." +During your initial QHub deployment, at the end of the `04-kubernetes-ingress` stage, you receive an output message stating that the DNS record for `your_qhub_domain` "appears not to exist, has recently been updated, or has yet to fully propagate." ### *Reason for observed behavior* As the output message mentions, this is likely the result of the non-deterministic behavior of DNS. From e78e894b70cf97c1ce69ae1a40f343d7c14644eb Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 16:03:26 +0100 Subject: [PATCH 11/16] updates from review --- docs/source/installation/login.md | 8 ++++---- docs/source/user_guide/troubleshooting.md | 14 +++++++------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index 4ad06635cd..7968449603 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -11,7 +11,7 @@ The `root` Keycloak user is only able to login and manage the Keycloak identity After the initial deployment, it is **highly** recommended that you change the Keycloak `root` user password as soon as you can. > NOTE: From this point on, the `security.keycloak.initial_root_password` field in `qhub-config.yaml` has no effect. If you redeploy QHub it will not reset the password back to the old one (or anything else that might be in the field in your YAML file). We strongly recommend you delete this field. -1. To change the `root` user password, navigate to `https://myqhubsite.com/auth/admin/`, and login with the password provided. +1. To change the `root` user password, your QHub's instance admin dashboard i.e , and log in with the password provided. ![QhHub admin view - Root Login to Keycloak form](../images/keycloak_master_login.png) @@ -42,13 +42,13 @@ All QHub users will be part of the `qhub` realm (a realm is a distinct identity The `qhub` realm is selected by default, we strongly recommend leaving it as is. -Click 'Users' along the left-hand side of the page. +1. Click 'Users' along the left-hand side of the page. -Click the 'Add user' button and you will see the new user form: +2. Click the 'Add user' button and you will see the new user form: ![Keycloak add user tab screenshot - new user form ](../images/keycloak_add_users.png) -Fill out the three fields, outlined above. These are 'Username', 'Email', and 'Groups'. +3. Fill out the three fields, outlined above. These are 'Username', 'Email', and 'Groups'. Depending on the authentication provider selected ('password', 'GitHub' or 'Auth0'), the values entered into the 'Username' field will differ slightly. The following table outlines those differences: diff --git a/docs/source/user_guide/troubleshooting.md b/docs/source/user_guide/troubleshooting.md index 8e0a1f2618..1ce2d375da 100644 --- a/docs/source/user_guide/troubleshooting.md +++ b/docs/source/user_guide/troubleshooting.md @@ -1,18 +1,18 @@ # Troubleshooting guide -## "DNS domain=`your_qhub_domain` record does not exist" +## DNS domain=`your_qhub_domain` record does not exist -### *Issue* +### Issue During your initial QHub deployment, at the end of the `04-kubernetes-ingress` stage, you receive an output message stating that the DNS record for `your_qhub_domain` "appears not to exist, has recently been updated, or has yet to fully propagate." -### *Reason for observed behavior* +### Reason for observed behavior As the output message mentions, this is likely the result of the non-deterministic behavior of DNS. Without going into a deep dive of what DNS is or how it works, the issue encountered here is that the when QHub tries to lookup the IP address associated with the DNS record, `your_qhub_domain`, nothing is returned. Unfortunately, this "lookup" is not as straight-forward as it sounds. To lookup the correct IP associated with this domain, many intermediate servers (root, top level domain, and authoritative nameservers) are checked, each with their own cache which was updated an unknown time ago (usually on the order of minutes but not always). For those interested to learn more about DNS, see [this CloudFlare article](https://howdns.works/)). -### *Troubleshooting* +### Troubleshooting Again, as the output message mentions, it will ask if you want it to retry this DNS lookup again after another wait period; this wait period keeps increasing after each retry. However, it's still possible that after waiting 15 or more minutes that the DNS still won't resolve. At this point, feel free to cancel the deployment and rerun the same deployment command again in an hour or two. Although not guaranteed, it's extremely likely that the DNS will resolve correctly after this prolonged wait period. @@ -20,13 +20,13 @@ At this point, feel free to cancel the deployment and rerun the same deployment ## A Conda-Store environment fails to build -### *Issue* +### Issue One of the two (`dashboard` or `dask`) Conda-Store environments created during the initial QHub deployment fails to appear as options when logged into JupyterHub. If your user has access to Conda-Store, you can verify this by visiting `.com/conda-store` and having a look at the build status of the missing environment. -### *Reason for observed behavior* +### Reason for observed behavior The reason for this issue is due to how these environments are simultaneously built. Under the hood, Conda-Store relies on Mamba/Conda to resolve and download the specific packages listed in the environment YAML. If they both environment builds try to download the same package with different versions, the build that started first will have their package overwritten by the second build. This causes the first build to fail. -### *Troubleshooting* +### Troubleshooting To resolve this issue, navigate to `.com/conda-store`, find the environment build that failed and trigger it to re-build. From e0329e7f983395d39fe166948084593d169f16f8 Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 16:06:30 +0100 Subject: [PATCH 12/16] Minor change to link name --- docs/source/user_guide/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/user_guide/troubleshooting.md b/docs/source/user_guide/troubleshooting.md index 1ce2d375da..8b2e6b0b98 100644 --- a/docs/source/user_guide/troubleshooting.md +++ b/docs/source/user_guide/troubleshooting.md @@ -10,7 +10,7 @@ As the output message mentions, this is likely the result of the non-determinist Without going into a deep dive of what DNS is or how it works, the issue encountered here is that the when QHub tries to lookup the IP address associated with the DNS record, `your_qhub_domain`, nothing is returned. Unfortunately, this "lookup" is not as straight-forward as it sounds. To lookup the correct IP associated with this domain, many intermediate servers (root, top level domain, and authoritative nameservers) are checked, each with their own cache which was updated an unknown time ago (usually on the order of minutes but not always). -For those interested to learn more about DNS, see [this CloudFlare article](https://howdns.works/)). +For those interested to learn more about DNS, [see this interesting comic](https://howdns.works/)). ### Troubleshooting Again, as the output message mentions, it will ask if you want it to retry this DNS lookup again after another wait period; this wait period keeps increasing after each retry. However, it's still possible that after waiting 15 or more minutes that the DNS still won't resolve. From a67322ed4340c4849c47f499ef7f3f072c858aff Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 16:11:12 +0100 Subject: [PATCH 13/16] updates from review --- docs/source/installation/login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index 7968449603..c7b95efd41 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -59,7 +59,7 @@ Depending on the authentication provider selected ('password', 'GitHub' or 'Auth Once the 'Username' field is updated, please add a valid email address in the 'Email' field. > NOTE: Although not required, users may not be able to log into Grafana if this field isn't properly set. -Lastly, associate the user with one or more of the 'Groups'. Out of the box, QHub is deployed with the following groups: 'admin', 'analyst', and 'developer' (see below for more information about 'Groups'). +Lastly, associate the user with one or more of the 'Groups'. Out of the box, QHub is deployed with the following groups: 'admin', 'analyst', and 'developer' (see the sections [Groups](./login.md#groups) below). Enter the name you would like for the user then click 'Save'. From 577a95dc6b6016c099fc7494ba312bcc181c96f4 Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 16:12:35 +0100 Subject: [PATCH 14/16] link to conda-store repo --- docs/source/user_guide/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/user_guide/troubleshooting.md b/docs/source/user_guide/troubleshooting.md index 8b2e6b0b98..f6f8f5156c 100644 --- a/docs/source/user_guide/troubleshooting.md +++ b/docs/source/user_guide/troubleshooting.md @@ -21,7 +21,7 @@ At this point, feel free to cancel the deployment and rerun the same deployment ## A Conda-Store environment fails to build ### Issue -One of the two (`dashboard` or `dask`) Conda-Store environments created during the initial QHub deployment fails to appear as options when logged into JupyterHub. +One of the two (`dashboard` or `dask`) [Conda-Store](https://github.com/Quansight/conda-store) environments created during the initial QHub deployment fails to appear as options when logged into JupyterHub. If your user has access to Conda-Store, you can verify this by visiting `.com/conda-store` and having a look at the build status of the missing environment. From 2278808a4f7f6d5a83f69b9e31fea83da8686705 Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 16:15:17 +0100 Subject: [PATCH 15/16] updates from review --- docs/source/installation/login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index c7b95efd41..b8430b0e61 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -59,7 +59,7 @@ Depending on the authentication provider selected ('password', 'GitHub' or 'Auth Once the 'Username' field is updated, please add a valid email address in the 'Email' field. > NOTE: Although not required, users may not be able to log into Grafana if this field isn't properly set. -Lastly, associate the user with one or more of the 'Groups'. Out of the box, QHub is deployed with the following groups: 'admin', 'analyst', and 'developer' (see the sections [Groups](./login.md#groups) below). +Lastly, associate the user with one or more of the 'Groups'. Out of the box, QHub is deployed with the following groups: 'admin', 'analyst', and 'developer' (see the [Groups](./login.md#groups) section below for more details). Enter the name you would like for the user then click 'Save'. From 967adaf66182f9a02418f78cb3cf7ce9d811056c Mon Sep 17 00:00:00 2001 From: iameskild Date: Thu, 3 Mar 2022 16:17:38 +0100 Subject: [PATCH 16/16] delete duplicates --- docs/source/installation/login.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md index b8430b0e61..45511804cb 100644 --- a/docs/source/installation/login.md +++ b/docs/source/installation/login.md @@ -77,8 +77,7 @@ To make adding users easier for new QHub deployments, there is a QHub command th > NOTE: If you changed the initial_root_password for Keycloak this method will not work. > NOTE: This method is primarily used by developers as a quick workaround. -> NOTE: If you changed the initial_root_password for Keycloak this method will not work. -> NOTE: This method is primarily used by developers as a quick workaround. + Run: