From 66a2d785df349b42c6167775025cf015494f0f2b Mon Sep 17 00:00:00 2001 From: rushtehrani Date: Fri, 5 Jun 2020 15:31:56 -0700 Subject: [PATCH 1/7] add troubleshooting section --- docs/deployment/troubleshooting/overview.md | 4 ++++ sidebars.js | 4 ++++ 2 files changed, 8 insertions(+) create mode 100644 docs/deployment/troubleshooting/overview.md diff --git a/docs/deployment/troubleshooting/overview.md b/docs/deployment/troubleshooting/overview.md new file mode 100644 index 00000000..1b37b54d --- /dev/null +++ b/docs/deployment/troubleshooting/overview.md @@ -0,0 +1,4 @@ +--- +title: Troubleshooting +sidebar_label: Troubleshooting +--- \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index e160e8f7..3014f50a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -90,6 +90,10 @@ module.exports = { 'deployment/configuration/files', 'deployment/configuration/tls', ] + }, + { + type: 'doc', + id: 'deployment/troubleshooting/overview' } ], reference: [ From 4e753f620bb4a190f8093c19a77891c518b6990a Mon Sep 17 00:00:00 2001 From: Aleksandr Melnikov Date: Fri, 5 Jun 2020 17:03:07 -0700 Subject: [PATCH 2/7] Adding a note about quoting the cloudflare token. --- docs/deployment/configuration/tls.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/deployment/configuration/tls.md b/docs/deployment/configuration/tls.md index 0edc61b4..2e33fbf7 100644 --- a/docs/deployment/configuration/tls.md +++ b/docs/deployment/configuration/tls.md @@ -124,6 +124,17 @@ certManager: email: ``` +:::note +If your token has an non-alphanumerical character, surround the token with single quotes. +```yaml +certManager: + cloudflare: + apiToken: '' + email: +``` + +::: + ### Google CloudDNS The flag is `clouddns`, as in From 47bf21b9bef792ff95f9aca7fbf1ccde4a9c9505 Mon Sep 17 00:00:00 2001 From: Aleksandr Melnikov Date: Fri, 5 Jun 2020 17:03:30 -0700 Subject: [PATCH 3/7] Adding some trouble shooting steps, related to cloud providers and page loading. --- docs/deployment/troubleshooting/overview.md | 87 ++++++++++++++++++++- 1 file changed, 86 insertions(+), 1 deletion(-) diff --git a/docs/deployment/troubleshooting/overview.md b/docs/deployment/troubleshooting/overview.md index 1b37b54d..26a152bb 100644 --- a/docs/deployment/troubleshooting/overview.md +++ b/docs/deployment/troubleshooting/overview.md @@ -1,4 +1,89 @@ --- title: Troubleshooting sidebar_label: Troubleshooting ---- \ No newline at end of file +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This document outlines trouble shooting for various topics. + +## You deployed to a cloud provided cluster using CloudFlare as DNS provider. + +Issue: +- You enter the URL into your browser and the page does not load. + +### Debugging steps: + +#### Make sure all the pods are running with no errors + +Execute: +```shell script +kubectl get pods -A +``` + +Check if all are running. If some are pending, wait for them to complete. +- If they take a long time, they may not be scheduling correctly. + +If some are showing an error, check the pod logs with `kubectl log` or check +the pod in more detail with `kubectl describe` + +#### Test to see if the DNS is setup correctly. + +We want to check that the domain is pointed to your IP. + +Use `ping` shell command. + +```text +$ ping app.web-demo.onepanel.ai +PING app.web-demo.onepanel.ai (52.224.34.111) 56(84) bytes of data. +``` +- This is pointing to the right IP + +#### Check your Cloudflare API Token Value + +If your token was typo'd when entered, that can cause an issue. + +If the token has non-alphanumerical characters, surround the token with single quotes. + +Example: +```yaml +certManager: + # DNS Provider: Cloudflare + # Docs: https://onepanelio.github.io/core-docs/docs/deployment/configuration/tls#cloudflare + # CLI flag: --dns-provider=cloudflare + cloudflare: + apiToken: token123ab_c + email: +``` +Should be +```yaml +certManager: + # DNS Provider: Cloudflare + # Docs: https://onepanelio.github.io/core-docs/docs/deployment/configuration/tls#cloudflare + # CLI flag: --dns-provider=cloudflare + cloudflare: + apiToken: 'token123ab_c' + email: +``` + +Then run `optcl apply` again. + +#### Investigating kubernetes resources + +You can use this as a resource: +- https://cert-manager.io/docs/faq/acme/ + +But in short: +- Check the status of the following resources (namespace: istio-system) + +certificate(s) +- kubectl get certificates -n istio-system +- kubectl describe certificate -n istio-system + +certificaterequest(s) + +order(s) + +challenge(s) + +There is a good chance that one of these will describe what the issue is. From e100de865553bc7eca443301d162bdd3f95b6acf Mon Sep 17 00:00:00 2001 From: rushtehrani Date: Mon, 8 Jun 2020 11:01:22 -0700 Subject: [PATCH 4/7] expand troubleshooting section --- docs/deployment/troubleshooting/overview.md | 97 ++++++++------------- 1 file changed, 38 insertions(+), 59 deletions(-) diff --git a/docs/deployment/troubleshooting/overview.md b/docs/deployment/troubleshooting/overview.md index 26a152bb..c29702c0 100644 --- a/docs/deployment/troubleshooting/overview.md +++ b/docs/deployment/troubleshooting/overview.md @@ -2,88 +2,67 @@ title: Troubleshooting sidebar_label: Troubleshooting --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -This document outlines trouble shooting for various topics. +This document outlines steps to troubleshoot issues that may arise after initial deployment of Onepanel. -## You deployed to a cloud provided cluster using CloudFlare as DNS provider. -Issue: -- You enter the URL into your browser and the page does not load. +## General troubleshooting steps -### Debugging steps: +Once you have setup DNS accordingly but the site isn't showing up or you can't login, double check that you have set up DNS correctly: -#### Make sure all the pods are running with no errors - -Execute: -```shell script -kubectl get pods -A +```bash +opctl app status ``` -Check if all are running. If some are pending, wait for them to complete. -- If they take a long time, they may not be scheduling correctly. +The command above will return a result similar to the following: -If some are showing an error, check the pod logs with `kubectl log` or check -the pod in more detail with `kubectl describe` +``` +Your deployment is ready. -#### Test to see if the DNS is setup correctly. +In your DNS, add an A record for *.sub.example.com and point it to '52.225.33.112' +Once complete, your application will be running at https://app.sub.example.com +``` -We want to check that the domain is pointed to your IP. +:::note +Depending on your provider, the `opctl app status` may prompt you to set up a `CNAME` record. +::: -Use `ping` shell command. +If you see "Your deployment is ready", double check that your DNS record is correct, then ping the domain in the URL above to confirm it is ready: -```text -$ ping app.web-demo.onepanel.ai -PING app.web-demo.onepanel.ai (52.224.34.111) 56(84) bytes of data. +```bash +$ ping app.sub.example.com +PING app.sub.example.com (52.225.33.112) 56(84) bytes of data. ``` -- This is pointing to the right IP -#### Check your Cloudflare API Token Value +If you see "Not all required pods are running. Your deployment is not ready.", run the following command: -If your token was typo'd when entered, that can cause an issue. +```bash +kubectl get pods -A +``` -If the token has non-alphanumerical characters, surround the token with single quotes. +For `Pending` pods, check the `Age`, if it has been less than 5 minutes, wait and check again. -Example: -```yaml -certManager: - # DNS Provider: Cloudflare - # Docs: https://onepanelio.github.io/core-docs/docs/deployment/configuration/tls#cloudflare - # CLI flag: --dns-provider=cloudflare - cloudflare: - apiToken: token123ab_c - email: -``` -Should be -```yaml -certManager: - # DNS Provider: Cloudflare - # Docs: https://onepanelio.github.io/core-docs/docs/deployment/configuration/tls#cloudflare - # CLI flag: --dns-provider=cloudflare - cloudflare: - apiToken: 'token123ab_c' - email: -``` +If the pods are showing `Error` or have been in `Pending` state for more than 5 minutes, check the pod in more details by running `kubectl describe` for more details. You can also check the pod log by running `kubectl logs`. -Then run `optcl apply` again. +In most cases, pods stuck in `Pending` state could mean that you need to add another node to your cluster. -#### Investigating kubernetes resources -You can use this as a resource: -- https://cert-manager.io/docs/faq/acme/ +## Troubleshooting deployments with cert-manager +Onepanel uses [cert-manager](https://cert-manager.io/) to automatically manages TLS certificates when you install Onepanel with the following flags: -But in short: -- Check the status of the following resources (namespace: istio-system) +```bash +opctl init ... --enable-cert-manager --dns-provider +``` -certificate(s) -- kubectl get certificates -n istio-system -- kubectl describe certificate -n istio-system +All cert-manager resources in Onepanel are installed in the `istio-system` namespace. -certificaterequest(s) +If you have enabled cert-manager and your application after following [General troubleshooting steps](#general-troubleshooting-steps), then you're most likely running into certificate issues. -order(s) +You can troubleshoot these issues by following the steps in [Troubleshooting Issuing ACME Certificates](https://cert-manager.io/docs/faq/acme/). Make sure to run all the commands in the `istio-system` namespace. For example to get the certificate that Onepanel uses: -challenge(s) +```bash +kubectl describe certificate cert-manager-wildcard-certificate -n istio-system +``` -There is a good chance that one of these will describe what the issue is. +## Still having issues? +Join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues). From cadae2372bd111d89ba67bed4f34f25998164e5c Mon Sep 17 00:00:00 2001 From: rushtehrani Date: Mon, 8 Jun 2020 11:19:27 -0700 Subject: [PATCH 5/7] reference troubleshooting docs --- docs/deployment/public/aks.md | 10 ++++++++-- docs/deployment/public/eks.md | 10 ++++++++-- docs/deployment/public/gke.md | 10 ++++++++-- docs/getting-started/quickstart.md | 8 ++++++-- 4 files changed, 30 insertions(+), 8 deletions(-) diff --git a/docs/deployment/public/aks.md b/docs/deployment/public/aks.md index 1601f126..a000a535 100644 --- a/docs/deployment/public/aks.md +++ b/docs/deployment/public/aks.md @@ -144,7 +144,7 @@ opctl apply ``` :::note -If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, run `kubectl get pods --all-namespaces` to see if there are any crashing pods. +If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview). ::: 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running: @@ -159,7 +159,13 @@ opctl app status Note that you should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com` ::: -7. Use the following command to get your auth token to log into Onepanel: +7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token. + +:::note +If the application is not loading, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page for some steps that can help resolve most issues. If you are still having issues, join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues). +::: + +8. Use the following command to get your auth token to log into Onepanel: ```bash opctl auth token diff --git a/docs/deployment/public/eks.md b/docs/deployment/public/eks.md index dbcaf86e..033bef05 100644 --- a/docs/deployment/public/eks.md +++ b/docs/deployment/public/eks.md @@ -119,7 +119,7 @@ opctl apply ``` :::note -If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, run `kubectl get pods --all-namespaces` to see if there are any crashing pods. +If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview). ::: 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running: @@ -134,7 +134,13 @@ opctl app status Note that you should use a wildcard `CNAME` record, for example: `*.example.com` or `*.subdomain.example.com` ::: -7. Use the following command to get your auth token to log into Onepanel: +7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token. + +:::note +If the application is not loading, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page for some steps that can help resolve most issues. If you are still having issues, join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues). +::: + +8. Use the following command to get your auth token to log into Onepanel: ```bash opctl auth token diff --git a/docs/deployment/public/gke.md b/docs/deployment/public/gke.md index a63c1385..42830818 100644 --- a/docs/deployment/public/gke.md +++ b/docs/deployment/public/gke.md @@ -115,7 +115,7 @@ opctl apply ``` :::note -If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, run `kubectl get pods --all-namespaces` to see if there are any crashing pods. +If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview). ::: 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running: @@ -130,7 +130,13 @@ opctl app status Note that you should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com` ::: -7. Use the following command to get your auth token to log into Onepanel: +7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token. + +:::note +If the application is not loading, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page for some steps that can help resolve most issues. If you are still having issues, join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues). +::: + +8. Use the following command to get your auth token to log into Onepanel: ```bash opctl auth token diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 9d820650..ad291618 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -200,7 +200,7 @@ opctl apply ``` :::note -If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, run `kubectl get pods --all-namespaces` to see if there are any crashing pods. +If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview). ::: 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running: @@ -211,7 +211,11 @@ opctl app status 6. Create the appropriate DNS record in your DNS provider based on the instructions above. -7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a token screen as showng below: +7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token. + +:::note +If the application is not loading, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page for some steps that can help resolve most issues. If you are still having issues, join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues). +::: 8. Use the following command to get your auth token to log into Onepanel: From 1bf47c50381907a927ea02e85183975bbe18f60a Mon Sep 17 00:00:00 2001 From: rushtehrani Date: Mon, 8 Jun 2020 11:22:26 -0700 Subject: [PATCH 6/7] fix typo --- docs/deployment/public/aks.md | 2 +- docs/deployment/public/eks.md | 2 +- docs/deployment/public/gke.md | 2 +- docs/getting-started/quickstart.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/deployment/public/aks.md b/docs/deployment/public/aks.md index a000a535..661f4f57 100644 --- a/docs/deployment/public/aks.md +++ b/docs/deployment/public/aks.md @@ -144,7 +144,7 @@ opctl apply ``` :::note -If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview). +If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page. ::: 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running: diff --git a/docs/deployment/public/eks.md b/docs/deployment/public/eks.md index 033bef05..bdb9b4f7 100644 --- a/docs/deployment/public/eks.md +++ b/docs/deployment/public/eks.md @@ -119,7 +119,7 @@ opctl apply ``` :::note -If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview). +If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page. ::: 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running: diff --git a/docs/deployment/public/gke.md b/docs/deployment/public/gke.md index 42830818..54eed423 100644 --- a/docs/deployment/public/gke.md +++ b/docs/deployment/public/gke.md @@ -115,7 +115,7 @@ opctl apply ``` :::note -If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview). +If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page. ::: 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running: diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index ad291618..f03be9e4 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -200,7 +200,7 @@ opctl apply ``` :::note -If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview). +If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page. ::: 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running: From 4ba00b334d3b42390d1be4f5cd200fd5966b09b4 Mon Sep 17 00:00:00 2001 From: rushtehrani Date: Mon, 8 Jun 2020 11:29:15 -0700 Subject: [PATCH 7/7] add notes about hosts file --- docs/deployment/public/aks.md | 6 +++++- docs/deployment/public/eks.md | 6 +++++- docs/deployment/public/gke.md | 6 +++++- docs/getting-started/quickstart.md | 4 ++++ 4 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/deployment/public/aks.md b/docs/deployment/public/aks.md index 661f4f57..f9496fce 100644 --- a/docs/deployment/public/aks.md +++ b/docs/deployment/public/aks.md @@ -155,8 +155,12 @@ opctl app status 6. Create an `A` record in your DNS provider based on the instructions above. +:::note +You should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com` +::: + :::tip -Note that you should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com` +If you're waiting for your DNS record to propogate, you can set up a [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) to quickly test the deployment. ::: 7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token. diff --git a/docs/deployment/public/eks.md b/docs/deployment/public/eks.md index bdb9b4f7..8001c99e 100644 --- a/docs/deployment/public/eks.md +++ b/docs/deployment/public/eks.md @@ -130,8 +130,12 @@ opctl app status 6. Create a `CNAME` record in your DNS provider based on the instructions above. +:::note +You should use a wildcard `CNAME` record, for example: `*.example.com` or `*.subdomain.example.com` +::: + :::tip -Note that you should use a wildcard `CNAME` record, for example: `*.example.com` or `*.subdomain.example.com` +If you're waiting for your DNS record to propogate, you can set up a [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) to quickly test the deployment. ::: 7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token. diff --git a/docs/deployment/public/gke.md b/docs/deployment/public/gke.md index 54eed423..3d3f087c 100644 --- a/docs/deployment/public/gke.md +++ b/docs/deployment/public/gke.md @@ -126,8 +126,12 @@ opctl app status 6. Create an `A` record in your DNS provider based on the instructions above. +:::note +You should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com` +::: + :::tip -Note that you should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com` +If you're waiting for your DNS record to propogate, you can set up a [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) to quickly test the deployment. ::: 7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token. diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index f03be9e4..97c66baa 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -211,6 +211,10 @@ opctl app status 6. Create the appropriate DNS record in your DNS provider based on the instructions above. +:::tip +If you don't have a domain name handy or you're waiting for your DNS record to propogate, you can set up a [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) to quickly test the deployment. +::: + 7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token. :::note