From 5e921b33b9173ccde8fe321d35534b04ebbd5d93 Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Thu, 19 Sep 2024 17:41:06 -0300 Subject: [PATCH] docs: Add troubleshooting step around case insensitive routing to Ansible guides (#46775) * docs: Add troubleshooting step around case-insensitive routing to Ansible guides * Fix config levels * Update ansible.mdx Co-authored-by: Paul Gottschling * Update ansible.mdx Co-authored-by: Paul Gottschling * Whitelist word for spell checker --------- Co-authored-by: Paul Gottschling --- docs/cspell.json | 1 + .../machine-id/access-guides/ansible.mdx | 28 ++++++++++++++++ .../server-access/guides/ansible.mdx | 32 +++++++++++++++++-- 3 files changed, 59 insertions(+), 2 deletions(-) diff --git a/docs/cspell.json b/docs/cspell.json index bc2d4d46fb96b..8b28fd15e9c82 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -139,6 +139,7 @@ "Mqgcq", "Multifactor", "Multihost", + "MYHOSTNAME", "Mzgz", "NOFILE", "NOKEY", diff --git a/docs/pages/enroll-resources/machine-id/access-guides/ansible.mdx b/docs/pages/enroll-resources/machine-id/access-guides/ansible.mdx index c38a8511ed672..2e2806a884d27 100644 --- a/docs/pages/enroll-resources/machine-id/access-guides/ansible.mdx +++ b/docs/pages/enroll-resources/machine-id/access-guides/ansible.mdx @@ -230,6 +230,34 @@ If `ssh` works, try running the playbook with verbose mode on: $ ansible-playbook -vvv playbook.yaml ``` +If your hostnames contain uppercase characters (like `MYHOSTNAME`), please note that Teleport's internal hostname matching +is case sensitive by default, which can also lead to seeing this error. + +If this is the case, you can work around this by enabling case-insensitive routing at the cluster level. + + + + +Edit your `/etc/teleport.yaml` config file on all servers running the Teleport `auth_service`, then restart Teleport on each. + +```yaml +auth_service: + case_insensitive_routing: true +``` + + + + +Run `tctl edit cluster_networking_config` to add the following specification, then save and exit. + +```yaml +spec: + case_insensitive_routing: true +``` + + + + ## Next steps - Read the [configuration reference](../../../reference/machine-id/configuration.mdx) to explore diff --git a/docs/pages/enroll-resources/server-access/guides/ansible.mdx b/docs/pages/enroll-resources/server-access/guides/ansible.mdx index 0d3d239fd4ba5..62d2327f66b6c 100644 --- a/docs/pages/enroll-resources/server-access/guides/ansible.mdx +++ b/docs/pages/enroll-resources/server-access/guides/ansible.mdx @@ -87,7 +87,7 @@ to a valid SSH username that works with the target host and is allowed by Telepo From the folder `ansible`, run the ansible playbook: ```code -$ ansible-playbook playbook.yaml +$ ansible-playbook playbook.yaml # PLAY [all] ***************************************************************************************************************************************** # TASK [Gathering Facts] ***************************************************************************************************************************** @@ -106,7 +106,7 @@ all ansible commands in the audit log. ## Troubleshooting -In case if ansible can not connect, you may see error like this one: +In cases where Ansible cannot connect, you may see an error like this: ```txt example.host | UNREACHABLE! => { @@ -129,3 +129,31 @@ If `ssh` works, try running the playbook with verbose mode on: ```code $ ansible-playbook -vvvv playbook.yaml ``` + +If your hostnames contain uppercase characters (like `MYHOSTNAME`), please note that Teleport's internal hostname matching +is case sensitive by default, which can also lead to seeing this error. + +If this is the case, you can work around this by enabling case-insensitive routing at the cluster level. + + + + +Edit your `/etc/teleport.yaml` config file on all servers running the Teleport `auth_service`, then restart Teleport on each. + +```yaml +auth_service: + case_insensitive_routing: true +``` + + + + +Run `tctl edit cluster_networking_config` to add the following specification, then save and exit. + +```yaml +spec: + case_insensitive_routing: true +``` + + + \ No newline at end of file