[version-4-4] DOC-887: SSH usernames (#5091) (#5325)

* DOC-887: SSH usernames (#5091) * docs: SSH usernames draft * docs: GCP GKE addition * docs: update based on packs JSON * docs: remove tencent * docs: miss bold providers * docs: clean up edge description * docs: code review suggestions Co-authored-by: caroldelwing <[email protected]> * ci: auto-formatting prettier issues * docs: move article to new location * ci: auto-formatting prettier issues * docs: fix legacy spelling mistakes * docs: root username for BYO-OS * docs: remove script workaround for GCP GKE * docs: update based on recent testing * ci: auto-formatting prettier issues * docs: clarify what sets vSphere username * docs: code review suggestions Co-authored-by: Karl Cardenas <[email protected]> * ci: auto-formatting prettier issues * docs: resolving content comments * docs: index page for SSH * docs: fix redirect and lingering broken links * ci: auto-formatting prettier issues --------- Co-authored-by: caroldelwing <[email protected]> Co-authored-by: benradstone <[email protected]> Co-authored-by: Karl Cardenas <[email protected]> (cherry picked from commit 83294cc) * docs: remove agent mode reference --------- Co-authored-by: Ben Radstone <[email protected]> Co-authored-by: Ben Radstone <[email protected]>
spectrocloud · Jan 9, 2025 · 06c8875 · 06c8875
1 parent c6f820a
commit 06c8875
Show file tree

Hide file tree

Showing 16 changed files with 145 additions and 34 deletions.
diff --git a/docs/docs-content/automation/crossplane/deploy-cluster-azure-crossplane.md b/docs/docs-content/automation/crossplane/deploy-cluster-azure-crossplane.md
@@ -18,8 +18,8 @@ how to use Crossplane to deploy a Palette-managed Kubernetes cluster in Azure.
   API key.
 - A public [Azure](https://learn.microsoft.com/en-us/training/modules/create-an-azure-account) cloud account with the
   required [permissions](../../clusters/public-cloud/azure/required-permissions.md).
-- An SSH key pair available. Check out the [Create an Upload an SSH Key](../../clusters/cluster-management/ssh-keys.md)
-  page for guidance.
+- An SSH key pair available. Check out the
+  [Create and Upload an SSH Key](../../clusters/cluster-management/ssh/ssh-keys.md) page for guidance.
 - The Azure account must be registered in Palette. Follow the
   [Register and Manage Azure Cloud Account](../../clusters/public-cloud/azure/azure-cloud.md) guide to register your
   account in Palette.

diff --git a/docs/docs-content/automation/crossplane/deploy-cluster-gcp-crossplane.md b/docs/docs-content/automation/crossplane/deploy-cluster-gcp-crossplane.md
@@ -18,8 +18,8 @@ how to use Crossplane to deploy a Palette-managed Kubernetes cluster in GCP.
   API key.
 - A public [GCP](https://cloud.google.com/iam/docs/creating-managing-service-accounts) service account with the required
   [roles](../../clusters/public-cloud/gcp/add-gcp-accounts.md#prerequisites).
-- An SSH key pair available. Check out the [Create an Upload an SSH Key](../../clusters/cluster-management/ssh-keys.md)
-  page for guidance.
+- An SSH key pair available. Check out the
+  [Create and Upload an SSH Key](../../clusters/cluster-management/ssh/ssh-keys.md) page for guidance.
 - The GCP account must be registered in Palette. Follow the
   [Register and Manage GCP Accounts](../../clusters/public-cloud/gcp/add-gcp-accounts.md) guide to register your account
   in Palette.

diff --git a/docs/docs-content/clusters/cluster-management/ssh/_category_.json b/docs/docs-content/clusters/cluster-management/ssh/_category_.json
@@ -0,0 +1,3 @@
+{
+  "position": 10
+}
diff --git a/...t/clusters/cluster-management/ssh-keys.md → ...usters/cluster-management/ssh/ssh-keys.md b/...t/clusters/cluster-management/ssh-keys.md → ...usters/cluster-management/ssh/ssh-keys.md
@@ -7,12 +7,11 @@ sidebar_position: 10
 tags: ["clusters", "cluster management"]
 ---
 
-Palette supports SSH (Secure Shell) to establish, administer, and communicate with remote clusters. This section
-describes creating and managing SSH Keys in the Palette Management Console.
+This section describes creating and managing SSH Keys in the Palette Management Console.
 
 ## Scope of SSH Key
 
-Palette groups clusters for logical separation into [Projects](../../tenant-settings/projects/projects.md). Users and
+Palette groups clusters for logical separation into [Projects](../../../tenant-settings/projects/projects.md). Users and
 teams can be assigned roles within a project for granular control over permissions within the project scope. SSH key
 authentication is scoped to a project. Multiple users can gain access to a single project. To access a cluster with SSH,
 you need a public SSH key registered in Palette.
@@ -26,8 +25,9 @@ you need a public SSH key registered in Palette.
 ## Create and Upload an SSH Key
 
 <PartialsComponent category="palette-setup" name="generate-ssh-key" />
+
 ## Validate
 
 You can validate that the SSH public key is available in Palette by attempting to deploy a host cluster. During the host
 cluster creation wizard, you will be able to assign the SSH key to the cluster. Refer to the
-[Deploy a Cluster](../public-cloud/deploy-k8s-cluster.md) tutorial for additional guidance.
+[Deploy a Cluster](../../public-cloud/deploy-k8s-cluster.md) tutorial for additional guidance.
diff --git a/docs/docs-content/clusters/cluster-management/ssh/ssh-usernames.md b/docs/docs-content/clusters/cluster-management/ssh/ssh-usernames.md
@@ -0,0 +1,89 @@
+---
+sidebar_label: "SSH Usernames"
+title: "SSH Usernames"
+description:
+  "A list of the Secure Shell (SSH) usernames created on Kubernetes nodes for each provider and operating system (OS)
+  pack available in Palette."
+icon: ""
+hide_table_of_contents: false
+sidebar_position: 20
+---
+
+This page lists the Secure Shell (SSH) user names created on Kubernetes nodes, which vary by provider and Operating
+System (OS).
+
+These user names are relevant when using [SSH key pairs](./ssh-keys.md) with your Palette host clusters.
+
+## Public Cloud
+
+Public Cloud includes both Infrastructure as a Service (IaaS) and Managed Kubernetes.
+
+### Infrastructure Provider
+
+| Provider       | OS Pack    | SSH Username |
+| -------------- | ---------- | ------------ |
+| **AWS IaaS**   | **Ubuntu** | `ubuntu`     |
+| **AWS IaaS**   | **CentOS** | `centos`     |
+| **Azure IaaS** | **Ubuntu** | `ubuntu`     |
+| **Azure IaaS** | **CentOS** | `centos`     |
+| **GCP IaaS**   | **Ubuntu** | `ubuntu`     |
+| **GCP IaaS**   | **CentOS** | `centos`     |
+
+### Managed Kubernetes
+
+| Provider      | OS Pack                        | SSH Username                                                                        |
+| ------------- | ------------------------------ | ----------------------------------------------------------------------------------- |
+| **AWS EKS**   | **Amazon EKS optimized Linux** | `ec2-user`                                                                          |
+| **Azure AKS** | **Linux**                      | `azureuser`                                                                         |
+| **GCP GKE**   | **Container-Optimized OS**     | Refer to the [SSH Configuration on GCP GKE](#ssh-configuration-on-gcp-gke) section. |
+
+#### SSH Configuration on GCP GKE
+
+It is not possible to configure GCP GKE clusters with an SSH key during cluster creation. If SSH access to your GCP GKE
+nodes is critical, consider one of the following options:
+
+- Configure project or node-level metadata to include your SSH key. Refer to
+  [Predefined and custom metadata keys](https://cloud.google.com/compute/docs/metadata/overview#predefined-and-custom-metadata-keys)
+  for guidance.
+
+- Enable OS Login and associate your SSH key with your IAM identity. Refer to
+  [How OS Login works](https://cloud.google.com/compute/docs/oslogin#how_os_login_works) for guidance.
+
+## Data Center
+
+| Provider           | OS Pack    | SSH Username |
+| ------------------ | ---------- | ------------ |
+| **MAAS**           | **Ubuntu** | `ubuntu`     |
+| **Openstack**      | **Ubuntu** | `ubuntu`     |
+| **VMware vSphere** | **Ubuntu** | `spectro`    |
+| **VMware vSphere** | **CentOS** | `spectro`    |
+
+## Edge
+
+This is dependent on the OS you provide for your edge hosts using
+[EdgeForge](../../../clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md).
+
+If using EdgeForge, you can also create custom users and assign SSH keys to them using cloud-init stages. Refer to
+[Cloud Init Stages](../../edge/edge-configuration/cloud-init.md#assign-an-ssh-key) for an example.
+
+## Bring Your Own OS
+
+You can select **Bring Your Own OS (BYOOS)** as the OS pack for your cluster in Palette. The default SSH username will
+depend on the OS image that you have built. Refer to [Bring Your Own OS (BYOOS)](../../../byoos/byoos.md) for further
+guidance on building custom images.
+
+- For images built using the [Kubernetes Image Builder](../../../byoos/image-builder/build-image.md), the SSH username
+  is defined as the value for `ssh_username` in the corresponding OS JSON file. For example, the
+  [Amazon Linux 2 JSON](https://github.com/kubernetes-sigs/image-builder/blob/main/images/capi/packer/ami/amazon-2.json#L11)
+  sets the `ssh_username` value as `ec2-user`.
+
+  If `ssh_username` is not defined in the OS JSON, then `root` is set by the **Bring Your Own OS (BYOOS)** pack.
+
+- For images built for VMware vSphere, the SSH username is set to `spectro` by Palette.
+
+## Resources
+
+- [SSH Keys](./ssh-keys.md)
+- [Deploy a Cluster (Public Cloud)](../../public-cloud/deploy-k8s-cluster.md)
+- [Data Center Clusters](../../data-center/data-center.md)
+- [Create Cluster Definition (Edge)](../../edge/site-deployment/cluster-deployment.md)
diff --git a/docs/docs-content/clusters/cluster-management/ssh/ssh.md b/docs/docs-content/clusters/cluster-management/ssh/ssh.md
@@ -0,0 +1,19 @@
+---
+sidebar_label: "SSH"
+title: "SSH"
+description:
+  "Learn how to use Palette to manage your Secure Shell (SSH) keys and the usernames created when deploying clusters."
+icon: ""
+hide_table_of_contents: false
+sidebar_position: 1
+---
+
+Palette supports SSH (Secure Shell) to establish, administer, and communicate with remote clusters.
+
+You can deploy SSH keys to your cluster nodes using Palette. The SSH username used for key deployment depends on your
+provider and operating system.
+
+## Resources
+
+- [SSH Keys](./ssh-keys.md)
+- [SSH Usernames](./ssh-usernames.md)
diff --git a/docs/docs-content/clusters/data-center/vmware/create-manage-vmware-clusters.md b/docs/docs-content/clusters/data-center/vmware/create-manage-vmware-clusters.md
@@ -89,14 +89,14 @@ Before you begin, ensure that you have the following prerequisites:
 8. Fill out the VMware vSphere configuration details for the cluster. Refer to the table below to learn more about each
    option. Click **Next** to proceed.
 
-   | Field Name                | Description                                                                                                                                                                                             | Required |
-   | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-   | **Datacenter**            | The VMware vSphere datacenter where the cluster and its nodes will be deployed.                                                                                                                         | Yes      |
-   | **Deployment Folder**     | The folder in the datacenter where the cluster and its nodes will be deployed. Check the box **Append cluster name** if you want the cluster name appended to the folder name.                          | Yes      |
-   | **Image Template Folder** | The folder in the datacenter where the image templates are stored. This is typically in the **spectro-templates** folder.                                                                               | Yes      |
-   | **Network Type**          | The network type to use for the cluster. Select **Static IP** if you want to use static IP addresses. Select **DHCP** if you want to use Dynamic Host Configuration Protocol (DHCP).                    | Yes      |
-   | **SSH Key**               | The SSH key to use for the cluster. Check out the [Create and Upload an SSH Key](../../cluster-management/ssh-keys.md#create-and-upload-an-ssh-key) guide to learn how to upload an SSH key to Palette. | No       |
-   | **NTP Servers**           | The Network Time Protocol (NTP) servers to use for the cluster.                                                                                                                                         | No       |
+   | Field Name                | Description                                                                                                                                                                                                 | Required |
+   | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+   | **Datacenter**            | The VMware vSphere datacenter where the cluster and its nodes will be deployed.                                                                                                                             | Yes      |
+   | **Deployment Folder**     | The folder in the datacenter where the cluster and its nodes will be deployed. Check the box **Append cluster name** if you want the cluster name appended to the folder name.                              | Yes      |
+   | **Image Template Folder** | The folder in the datacenter where the image templates are stored. This is typically in the **spectro-templates** folder.                                                                                   | Yes      |
+   | **Network Type**          | The network type to use for the cluster. Select **Static IP** if you want to use static IP addresses. Select **DHCP** if you want to use Dynamic Host Configuration Protocol (DHCP).                        | Yes      |
+   | **SSH Key**               | The SSH key to use for the cluster. Check out the [Create and Upload an SSH Key](../../cluster-management/ssh/ssh-keys.md#create-and-upload-an-ssh-key) guide to learn how to upload an SSH key to Palette. | No       |
+   | **NTP Servers**           | The Network Time Protocol (NTP) servers to use for the cluster.                                                                                                                                             | No       |
 
    :::warning
 

diff --git a/docs/docs-content/clusters/public-cloud/azure/aks.md b/docs/docs-content/clusters/public-cloud/azure/aks.md
@@ -16,8 +16,8 @@ explains how you can create an Azure AKS cluster managed by Palette.
   [Register and Manage Azure Cloud Account](./azure-cloud.md) for guidance.
 
 - A Secure Shell (SSH) key that you have pre-configured in your Azure environment. Refer to the
-  [SSH Keys](../../cluster-management/ssh-keys.md) guide for more information about creating and managing SSH keys in
-  Palette.
+  [SSH Keys](../../cluster-management/ssh/ssh-keys.md) guide for more information about creating and managing SSH keys
+  in Palette.
 
 - An infrastructure cluster profile for Azure. Review
   [Create an Infrastructure Profile](../../../profiles/cluster-profiles/create-cluster-profiles/create-infrastructure-profile.md)

diff --git a/docs/docs-content/clusters/public-cloud/azure/create-azure-cluster.md b/docs/docs-content/clusters/public-cloud/azure/create-azure-cluster.md
@@ -28,8 +28,8 @@ to create an IaaS Kubernetes cluster in Azure that Palette manages.
 - Palette integration with Azure account. Review [Register and Manage Azure Cloud Account](azure-cloud.md) for guidance.
 
 - A Secure Shell (SSH) key pre-configured in your Azure environment. Refer to the
-  [SSH Keys](../../cluster-management/ssh-keys.md) guide for more information about creating and managing SSH keys in
-  Palette.
+  [SSH Keys](../../cluster-management/ssh/ssh-keys.md) guide for more information about creating and managing SSH keys
+  in Palette.
 
 - An infrastructure cluster profile for Azure. Review
   [Create an Infrastructure Profile](../../../profiles/cluster-profiles/create-cluster-profiles/create-infrastructure-profile.md)

diff --git a/docs/docs-content/clusters/public-cloud/deploy-k8s-cluster.md b/docs/docs-content/clusters/public-cloud/deploy-k8s-cluster.md
@@ -71,7 +71,7 @@ To complete this tutorial, you will need the following.
 
   <br />
 
-- An SSH Key Pair. Use the [Create and Upload an SSH Key](../cluster-management/ssh-keys.md) guide to learn how to
+- An SSH Key Pair. Use the [Create and Upload an SSH Key](../cluster-management/ssh/ssh-keys.md) guide to learn how to
   create an SSH key and upload it to Palette.
 
   - AWS users must create an AWS Key pair before starting the tutorial. If you need additional guidance, check out the
@@ -350,7 +350,7 @@ pack contains a set of default values. You can change the manifest values if nee
 
 The **Cluster config** section allows you to select the **Subscription**, **Region**, **Resource Group**, **Storage
 account**, and **SSH Key** to apply to the host cluster. All clusters require you to assign an SSH key. Refer to the
-[SSH Keys](../cluster-management/ssh-keys.md) guide for information about uploading an SSH key.
+[SSH Keys](../cluster-management/ssh/ssh-keys.md) guide for information about uploading an SSH key.
 
 <br />
 
@@ -515,7 +515,7 @@ pack contains a set of default values. You can change the manifest values if nee
 #### Cluster Configuration
 
 The **Cluster config** section allows you to select the **Project**, **Region**, and **SSH Key** to apply to the host
-cluster. All clusters require you to assign an SSH key. Refer to the [SSH Keys](/clusters/cluster-management/ssh-keys)
+cluster. All clusters require you to assign an SSH key. Refer to the [SSH Keys](../cluster-management/ssh/ssh-keys.md)
 guide for information about uploading an SSH key.
 
 <br />

diff --git a/docs/docs-content/clusters/public-cloud/gcp/create-gcp-iaas-cluster.md b/docs/docs-content/clusters/public-cloud/gcp/create-gcp-iaas-cluster.md
@@ -23,8 +23,8 @@ Ensure the following requirements are met before you attempt to deploy a cluster
   for guidance.
 
 - An SSH Key that is uploaded to Palette and available for usage. Refer to the
-  [SSH Keys](/clusters/cluster-management/ssh-keys) guide to learn how to create an SSH key and upload the public key to
-  Palette.
+  [SSH Keys](../../cluster-management/ssh/ssh-keys.md) guide to learn how to create an SSH key and upload the public key
+  to Palette.
 
 - Palette creates compute, network, and storage resources while provisioning Kubernetes clusters. Ensure there is
   sufficient capacity in the preferred GCP region to create the following resources:
@@ -69,7 +69,7 @@ Ensure the following requirements are met before you attempt to deploy a cluster
    | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Project**          | The project to which the cluster belongs.                                                                                                                                                   |
    | **Region**           | Choose the desired GCP region to deploy the cluster.                                                                                                                                        |
-   | **SSH Key**          | Choose the desired SSH key. Refer to the [SSH Keys](../../cluster-management/ssh-keys.md) guide to learn how to create an SSH key and upload the public key to Palette.                     |
+   | **SSH Key**          | Choose the desired SSH key. Refer to the [SSH Keys](../../cluster-management/ssh/ssh-keys.md) guide to learn how to create an SSH key and upload the public key to Palette.                 |
    | **Static Placement** | Check the **Static Placement** box to deploy resources into a pre-existing VPC. Review the [Static Placement](#static-placement) table below to learn more about the required input fields. |
 
    #### Static Placement

diff --git a/docs/docs-content/getting-started/azure/deploy-k8s-cluster.md b/docs/docs-content/getting-started/azure/deploy-k8s-cluster.md
@@ -64,7 +64,7 @@ pack contains a set of default values. You can change the manifest values if nee
 
 The **Cluster Config** section allows you to select the **Subscription**, **Region**, **Resource Group**, **Storage
 account**, and **SSH Key** to apply to the host cluster. All clusters require you to assign an SSH key. Refer to the
-[SSH Keys](../../clusters/cluster-management/ssh-keys.md) guide for information about uploading an SSH key.
+[SSH Keys](../../clusters/cluster-management/ssh/ssh-keys.md) guide for information about uploading an SSH key.
 
 When you are done selecting a **Subscription**, **Region**, **Resource Group**, **Storage account** and **SSH Key**,
 click on **Next**.

diff --git a/docs/docs-content/tutorials/cluster-deployment/pcg/deploy-app-pcg.md b/docs/docs-content/tutorials/cluster-deployment/pcg/deploy-app-pcg.md
@@ -46,7 +46,7 @@ To complete this tutorial, you will need the following prerequisites in place.
     - A Palette API key. Refer to the [Create API Key](../../../user-management/authentication/api-key/create-api-key.md) page for instructions on how to create an API key.
     - A [VMware vSphere](https://docs.vmware.com/en/VMware-vSphere/index.html) user account with the [required permissions](../../../clusters/data-center/vmware/permissions.md).
     - A Linux x86-64 machine with access to a terminal and Internet, as well as connection to both Palette and VMware vSphere.
-    - An SSH key pair. Use the [Create and Upload an SSH Key](../../../clusters/cluster-management/ssh-keys.md) guide to learn how to create an SSH key and upload it to Palette.
+    - An SSH key pair. Use the [Create and Upload an SSH Key](../../../clusters/cluster-management/ssh/ssh-keys.md) guide to learn how to create an SSH key and upload it to Palette.
     - The following IP address requirements must be met in your VMware vSphere environment:
         - One IP address available for the single-node PCG deployment. Refer to the [PCG Sizing](../../../clusters/pcg/manage-pcg/scale-pcg-nodes.md) section for more information on sizing.
         - One IP address reserved for cluster repave operations.