From 27e36063c48f424090ae0536825d7edeeb4061e8 Mon Sep 17 00:00:00 2001 From: Kevin W Monroe Date: Fri, 12 Apr 2024 09:41:07 -0500 Subject: [PATCH] Add a troubleshooting docs page (#305) * add troubleshooting explanation --- docs/src/howto/index.md | 9 +++---- docs/src/howto/support.md | 13 +++++++++- docs/src/reference/index.md | 1 + docs/src/reference/troubleshooting.md | 37 +++++++++++++++++++++++++++ 4 files changed, 54 insertions(+), 6 deletions(-) create mode 100644 docs/src/reference/troubleshooting.md diff --git a/docs/src/howto/index.md b/docs/src/howto/index.md index eeace3b14..1a0cf9473 100644 --- a/docs/src/howto/index.md +++ b/docs/src/howto/index.md @@ -18,17 +18,16 @@ install/index networking/index /howto/storage /howto/contribute +/howto/support ``` --- ## Other documentation types -Our Reference section is for when you need to check specific details or -information such as the command reference or release notes. - -Alternatively, the [Tutorials section] contains step-by-step tutorials to help -guide you through exploring and using Canonical Kubernetes. +If you are just getting started, the [Tutorials section] contains +step-by-step tutorials to help guide you through exploring and using +Canonical Kubernetes. For a better understanding of how Canonical Kubernetes works and related topics such as security, our [Explanation section] helps you expand your knowledge diff --git a/docs/src/howto/support.md b/docs/src/howto/support.md index 38c492ec6..60b1b1c9d 100644 --- a/docs/src/howto/support.md +++ b/docs/src/howto/support.md @@ -1 +1,12 @@ -# Get support +# How to get support + +Support for Canonical Kubernetes is available in a variety of ways: + +- Engagement with the [Canonical Kubernetes Community] +- Understanding common [Troubleshooting Techniques] +- Professional support services with [Ubuntu Support] + + +[Canonical Kubernetes Community]: ../reference/community +[Troubleshooting Techniques]: ../reference/troubleshooting +[Ubuntu Support]: https://ubuntu.com/support diff --git a/docs/src/reference/index.md b/docs/src/reference/index.md index 215b5e227..d6d392722 100644 --- a/docs/src/reference/index.md +++ b/docs/src/reference/index.md @@ -17,6 +17,7 @@ Overview /reference/community /reference/architecture /reference/roadmap +/reference/troubleshooting ``` ## Other documentation types diff --git a/docs/src/reference/troubleshooting.md b/docs/src/reference/troubleshooting.md new file mode 100644 index 000000000..c2a403c7a --- /dev/null +++ b/docs/src/reference/troubleshooting.md @@ -0,0 +1,37 @@ +# Troubleshooting + +This page provides techniques for troubleshooting common Canonical Kubernetes +issues. + +## Kubectl error: "dial tcp 127.0.0.1:6443: connect: connection refused" + +### Problem + +The [kubeconfig file] generated by the `k8s kubectl` CLI can not be used to +access the cluster from an external machine. The following error is seen when +running `kubectl` with the invalid kubeconfig: + +```bash +... +E0412 08:36:06.404499 517166 memcache.go:265] couldn't get current server API group list: Get "https://127.0.0.1:6443/api?timeout=32s": dial tcp 127.0.0.1:6443: connect: connection refused +The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port? +``` + +### Explanation + +A common technique for viewing a cluster kubeconfig file is by using the +`kubectl config view` command. + +The `k8s kubectl` command invokes an integrated `kubectl` client. Thus +`k8s kubectl config view` will output a seemingly valid kubeconfig file. +However, this will only be valid on cluster nodes where control plane services +are available on localhost endpoints. + +### Solution + +Use `k8s config` instead of `k8s kubectl config` to generate a kubeconfig file +that is valid for use on external machines. + + + +[kubeconfig file]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/