docs: address getting started feedback (#4809) (#4821)

* docs: address getting started feedback * docs: vale feedback * docs: fix typo * Apply suggestions from code review Co-authored-by: Adelina Simion <[email protected]> * docs: apply suggestions from code review --------- Co-authored-by: Adelina Simion <[email protected]> (cherry picked from commit 8402c66) Co-authored-by: caroldelwing <[email protected]>
spectrocloud · Nov 28, 2024 · aebfd4b · aebfd4b
1 parent 9c70f4c
commit aebfd4b
Show file tree

Hide file tree

Showing 27 changed files with 210 additions and 111 deletions.
diff --git a/_partials/_create-tenant-api-key.mdx b/_partials/_create-tenant-api-key.mdx
@@ -3,13 +3,13 @@ partial_category: palette-setup
 partial_name: create-tenant-api-key
 ---
 
-1. Log in to [Palette](https://console.spectrocloud.com) as a tenant admin.
+1. Log in to [Palette](https://console.spectrocloud.com).
 
-2. Switch to the **Tenant Admin** scope
+2. Click on the **drop-down Menu** at the top of the page and switch to the **Tenant Admin** scope.
 
 3. Navigate to the left **Main Menu** and select **Tenant Settings**.
 
-4. From the **Tenant Settings Menu**, select **API Keys**.
+4. From the **Tenant Settings Menu**, click on **Security** and select **API Keys**.
 
 5. Click on **Add New API key**.
 

diff --git a/docs/docs-content/getting-started/aws/aws.md b/docs/docs-content/getting-started/aws/aws.md
@@ -22,6 +22,8 @@ introducing you with Palette workflows and capabilities.
 In this section, you learn how to create a cluster profile. Then, you deploy a cluster to AWS by using Palette. Once
 your cluster is deployed, you can update it using cluster profile updates.
 
+<!-- vale off -->
+
 <SimpleCardGrid
   cards={[
     {

diff --git a/docs/docs-content/getting-started/aws/create-cluster-profile.md b/docs/docs-content/getting-started/aws/create-cluster-profile.md
@@ -42,24 +42,25 @@ In the **Basic Information** section, assign the name **aws-profile**, a brief p
 defaults to **1.0.0**. Click on **Next**.
 
 **Cloud Type** allows you to choose the infrastructure provider with which this cluster profile is associated. Select
-**AWS** and click on **Next**.
+**AWS IaaS** and click on **Next**.
 
 The **Profile Layers** step is where you specify the packs that compose the profile. There are four required
 infrastructure packs and several optional add-on packs you can choose from. Every pack requires you to select the **Pack
 Type**, **Registry**, and **Pack Name**.
 
-For this tutorial, use the following packs:
+For this tutorial, use the following packs. If there are differences between the latest version of a pack and the
+version you select, a YAML editor will open. Click **Confirm Changes** to proceed.
 
-| Pack Name      | Version | Layer            |
-| -------------- | ------- | ---------------- |
-| ubuntu-aws LTS | 22.4.x  | Operating System |
-| Kubernetes     | 1.29.x  | Kubernetes       |
-| cni-calico     | 3.27.x  | Network          |
-| csi-aws-ebs    | 1.26.x  | Storage          |
+| Pack Name                   | Version | Registry    | Layer            |
+| --------------------------- | ------- | ----------- | ---------------- |
+| Ubuntu                      | 22.4.x  | Public Repo | Operating System |
+| Palette eXtended Kubernetes | 1.29.x  | Public Repo | Kubernetes       |
+| Calico                      | 3.27.x  | Public Repo | Network          |
+| Amazon EBS CSI              | 1.26.x  | Public Repo | Storage          |
 
-As you fill out the information for each layer, click on **Next** to proceed to the next layer.
+As you select each layer, click on **Next Layer** to proceed to the next one.
 
-Click on **Confirm** after you have completed filling out all the core layers.
+Click on **Confirm** and then **Next** after you have completed selecting all the core layers.
 
 ![A view of the cluster profile stack](/getting-started/aws/getting-started_create-cluster-profile_clusters_parameters.webp)
 
@@ -99,7 +100,7 @@ Select the **Enable Hello Universe API** preset. The pack manifest changes accor
 The pack requires two values to be replaced for the authorization token and for the database password when using this
 preset. Replace these values with your own base64 encoded values. The
 [_hello-universe_](https://github.com/spectrocloud/hello-universe?tab=readme-ov-file#single-load-balancer) repository
-provides a token that you can use.
+provides an unencoded token that you can use.
 
 Click on **Confirm Updates**. The manifest editor closes.
 

diff --git a/docs/docs-content/getting-started/aws/deploy-k8s-cluster.md b/docs/docs-content/getting-started/aws/deploy-k8s-cluster.md
@@ -145,6 +145,13 @@ application with a frontend, API server, and Postgres database.
 
 Use the following steps to remove all the resources you created for the tutorial.
 
+:::tip
+
+If you plan to explore the [Deploy Cluster Profile Updates](./update-k8s-cluster.md) tutorial, do not delete your
+cluster, as it is a prerequisite for the tutorial.
+
+:::
+
 To remove the cluster, navigate to the left **Main Menu** and click on **Clusters**. Select the cluster you want to
 delete to access its details page.
 

diff --git a/docs/docs-content/getting-started/aws/deploy-manage-k8s-cluster-tf.md b/docs/docs-content/getting-started/aws/deploy-manage-k8s-cluster-tf.md
@@ -373,7 +373,19 @@ resource "spectrocloud_cluster_aws" "aws-cluster" {
 ## Terraform Tests
 
 Before starting the cluster deployment, test the Terraform code to ensure the resources will be provisioned correctly.
-Issue the following command in your terminal.
+
+Issue the following command in your terminal to initialize Terraform. The `init` command initializes the working
+directory that contains the Terraform files.
+
+```shell
+terraform init
+```
+
+```text hideClipboard
+Terraform has been successfully initialized!
+```
+
+Next, issue the `terraform test` command to start the tests.
 
 ```bash
 terraform test
@@ -428,8 +440,10 @@ the control plane or worker node pools as needed.
 
 :::warning
 
-Ensure that the SSH key pair specified in `aws-key-pair-name` is available in the same region specified by `aws-region`.
-For example, if `aws-region` is set to `us-east-1`, use the name of a key pair that exists in the `us-east-1` region.
+Note that `aws-cloud-account-name` must be replaced with the name of the AWS cloud account registered in Palette.
+Additionally, ensure that the SSH key pair specified in `aws-key-pair-name` is available in the same region specified by
+`aws-region`. For example, if `aws-region` is set to `us-east-1`, use the name of a key pair that exists in the
+`us-east-1` region.
 
 :::
 
@@ -472,17 +486,6 @@ environment variable. This step allows the Terraform code to authenticate with t
 export SPECTROCLOUD_APIKEY=<Your-Spectro-Cloud-API-key>
 ```
 
-Next, issue the following command to initialize Terraform. The `init` command initializes the working directory that
-contains the Terraform files.
-
-```shell
-terraform init
-```
-
-```text hideClipboard
-Terraform has been successfully initialized!
-```
-
 :::warning
 
 Before deploying the resources, ensure that there are no active clusters named `aws-cluster` or cluster profiles named

diff --git a/docs/docs-content/getting-started/aws/scale-secure-cluster.md b/docs/docs-content/getting-started/aws/scale-secure-cluster.md
@@ -106,12 +106,11 @@ are only visible in the **Default** project. Therefore, you will need to create
 Navigate to the left **Main Menu** and click on **Profiles**. Click on **Import Cluster Profile**. The **Import Cluster
 Profile** pane opens.
 
-Paste the following in the text editor. Click on **Validate**. The **Select repositories** dialog appears.
+Paste the following in the text editor. Click on **Validate**.
 
 <PartialsComponent category="getting-started" name="import-hello-uni-aws" />
 
-Click on **Confirm**. Then, click on **Confirm** on the **Import Cluster Profile** pane. Palette creates a new cluster
-profile named **aws-profile**.
+Click on **Confirm**. Palette creates a new cluster profile named **aws-profile**.
 
 On the **Profiles** list, select **Project** from the **Contexts** drop-down. Your newly created cluster profile
 displays. The Palette UI confirms that the cluster profile was created in the scope of the

diff --git a/docs/docs-content/getting-started/aws/update-k8s-cluster.md b/docs/docs-content/getting-started/aws/update-k8s-cluster.md
@@ -149,6 +149,7 @@ kubectl commands against the host cluster.
 ![Image that the kubeconfig file](/getting-started/aws/getting-started_update-k8s-cluster_download-kubeconfig.webp)
 
 Open a terminal window and set the environment variable `KUBECONFIG` to point to the kubeconfig file you downloaded.
+Issue the following command, replacing `~/Downloads/admin.aws-cluster.kubeconfig` with the path to your kubeconfig file.
 
 ```shell
 export KUBECONFIG=~/Downloads/admin.aws-cluster.kubeconfig

diff --git a/docs/docs-content/getting-started/azure/azure.md b/docs/docs-content/getting-started/azure/azure.md
@@ -22,6 +22,8 @@ approach, while introducing you with Palette workflows and capabilities.
 In this section, you learn how to create a cluster profile. Then, you deploy a cluster to Azure by using Palette. Once
 your cluster is deployed, you can update it using cluster profile updates.
 
+<!-- vale off -->
+
 <SimpleCardGrid
   cards={[
     {

diff --git a/docs/docs-content/getting-started/azure/create-cluster-profile.md b/docs/docs-content/getting-started/azure/create-cluster-profile.md
@@ -41,24 +41,25 @@ In the **Basic Information** section, assign the name **azure-profile**, a brief
 version defaults to **1.0.0**. Click on **Next**.
 
 **Cloud Type** allows you to choose the infrastructure provider with which this cluster profile is associated. Select
-**Azure** and click on **Next**.
+**Azure IaaS** and click on **Next**.
 
 The **Profile Layers** step is where you specify the packs that compose the profile. There are four required
 infrastructure packs and several optional add-on packs you can choose from. Every pack requires you to select the **Pack
 Type**, **Registry**, and **Pack Name**.
 
-For this tutorial, use the following packs:
+For this tutorial, use the following packs. If there are differences between the latest version of a pack and the
+version you select, a YAML editor will open. Click **Confirm Changes** to proceed.
 
-| Pack Name        | Version | Layer            |
-| ---------------- | ------- | ---------------- |
-| ubuntu-azure LTS | 22.4.x  | Operating System |
-| Kubernetes       | 1.30.x  | Kubernetes       |
-| cni-calico-azure | 3.26.x  | Network          |
-| Azure Disk       | 1.28.x  | Storage          |
+| Pack Name                   | Version | Registry    | Layer            |
+| --------------------------- | ------- | ----------- | ---------------- |
+| Ubuntu                      | 22.4.x  | Public Repo | Operating System |
+| Palette eXtended Kubernetes | 1.30.x  | Public Repo | Kubernetes       |
+| Calico                      | 3.26.x  | Public Repo | Network          |
+| Azure Disk                  | 1.28.x  | Public Repo | Storage          |
 
-As you fill out the information for each layer, click on **Next** to proceed to the next layer.
+As you select each layer, click on **Next Layer** to proceed to the next one.
 
-Click on **Confirm** after you have completed filling out all the core layers.
+Click on **Confirm** and then **Next** after you have completed selecting all the core layers.
 
 ![Azure cluster profile overview page](/getting-started/azure/getting-started_create-cluster-profile_cluster_profile_stack.webp)
 
@@ -98,7 +99,7 @@ Select the **Enable Hello Universe API** preset. The pack manifest changes accor
 The pack requires two values to be replaced for the authorization token and for the database password when using this
 preset. Replace these values with your own base64 encoded values. The
 [_hello-universe_](https://github.com/spectrocloud/hello-universe?tab=readme-ov-file#single-load-balancer) repository
-provides a token that you can use.
+provides an unencoded token that you can use.
 
 Click on **Confirm Updates**. The manifest editor closes.
 

diff --git a/docs/docs-content/getting-started/azure/deploy-k8s-cluster.md b/docs/docs-content/getting-started/azure/deploy-k8s-cluster.md
@@ -144,6 +144,13 @@ application with a frontend, API server, and Postgres database.
 
 Use the following steps to remove all the resources you created for the tutorial.
 
+:::tip
+
+If you plan to explore the [Deploy Cluster Profile Updates](./update-k8s-cluster.md) tutorial, do not delete your
+cluster, as it is a prerequisite for the tutorial.
+
+:::
+
 To remove the cluster, navigate to the left **Main Menu** and click on **Clusters**. Select the cluster you want to
 delete to access its details page.
 

diff --git a/docs/docs-content/getting-started/azure/deploy-manage-k8s-cluster-tf.md b/docs/docs-content/getting-started/azure/deploy-manage-k8s-cluster-tf.md
@@ -379,7 +379,19 @@ resource "spectrocloud_cluster_azure" "azure-cluster" {
 ## Terraform Tests
 
 Before starting the cluster deployment, test the Terraform code to ensure the resources will be provisioned correctly.
-Issue the following command in your terminal.
+
+Issue the following command in your terminal to initialize Terraform. The `init` command initializes the working
+directory that contains the Terraform files.
+
+```shell
+terraform init
+```
+
+```text hideClipboard
+Terraform has been successfully initialized!
+```
+
+Next, issue the `terraform test` command to start the tests.
 
 ```bash
 terraform test
@@ -432,6 +444,12 @@ occurrences of `REPLACE_ME` with their corresponding values, such as those for t
 `azure-region`, `azure_subscription_id`, and `azure_resource_group` variables. You can also update the values for the
 nodes in the control plane or worker node pools as needed.
 
+:::warning
+
+Ensure that `azure-cloud-account-name` is replaced with the name of the Azure cloud account registered in Palette.
+
+:::
+
 ```hcl {4,8-11}
 ###########################
 # Azure Deployment Settings
@@ -476,17 +494,6 @@ environment variable. This step allows the Terraform code to authenticate with t
 export SPECTROCLOUD_APIKEY=<Your-Spectro-Cloud-API-key>
 ```
 
-Next, issue the following command to initialize Terraform. The `init` command initializes the working directory that
-contains the Terraform files.
-
-```shell
-terraform init
-```
-
-```text hideClipboard
-Terraform has been successfully initialized!
-```
-
 :::warning
 
 Before deploying the resources, ensure that there are no active clusters named `azure-cluster` or cluster profiles named

diff --git a/docs/docs-content/getting-started/azure/scale-secure-cluster.md b/docs/docs-content/getting-started/azure/scale-secure-cluster.md
@@ -106,12 +106,11 @@ are only visible in the **Default** project. Therefore, you will need to create
 Navigate to the left **Main Menu** and click on **Profiles**. Click on **Import Cluster Profile**. The **Import Cluster
 Profile** pane opens.
 
-Paste the following in the text editor. Click on **Validate**. The **Select repositories** dialog appears.
+Paste the following in the text editor. Click on **Validate**.
 
 <PartialsComponent category="getting-started" name="import-hello-uni-azure" />
 
-Click on **Confirm**. Then, click on **Confirm** on the **Import Cluster Profile** pane. Palette creates a new cluster
-profile named **azure-profile**.
+Click on **Confirm**. Palette creates a new cluster profile named **azure-profile**.
 
 On the **Profiles** list, select **Project** from the **Contexts** drop-down. Your newly created cluster profile
 displays. The Palette UI confirms that the cluster profile was created in the scope of the

diff --git a/docs/docs-content/getting-started/azure/update-k8s-cluster.md b/docs/docs-content/getting-started/azure/update-k8s-cluster.md
@@ -149,6 +149,8 @@ kubectl commands against the host cluster.
 ![Image that the kubeconfig file](/getting-started/azure/getting-started_update-k8s-cluster_download-kubeconfig.webp)
 
 Open a terminal window and set the environment variable `KUBECONFIG` to point to the kubeconfig file you downloaded.
+Issue the following command, replacing `~/Downloads/admin.azure-cluster.kubeconfig` with the path to your kubeconfig
+file.
 
 ```shell
 export KUBECONFIG=~/Downloads/admin.azure-cluster.kubeconfig

diff --git a/docs/docs-content/getting-started/gcp/create-cluster-profile.md b/docs/docs-content/getting-started/gcp/create-cluster-profile.md
@@ -41,25 +41,26 @@ In the **Basic Information** section, assign the name **gcp-profile**, provide a
 **Full**, and assign the tag **env:gcp**. You can leave the version empty if you want to. Just be aware that the version
 defaults to **1.0.0**. Click on **Next**.
 
-Cloud Type allows you to choose the infrastructure provider with which this cluster profile is associated. Select
-**Google Cloud** and click on **Next**.
+Cloud Type allows you to choose the infrastructure provider with which this cluster profile is associated. Select **GCP
+IaaS** and click on **Next**.
 
 The **Profile Layers** step is where you specify the packs that compose the profile. There are four required
 infrastructure packs and several optional add-on packs you can choose from. Every pack requires you to select the **Pack
 Type**, **Registry**, and **Pack Name**.
 
-For this tutorial, use the following packs:
+For this tutorial, use the following packs. If there are differences between the latest version of a pack and the
+version you select, a YAML editor will open. Click **Confirm Changes** to proceed.
 
-| Pack Name      | Version | Layer            |
-| -------------- | ------- | ---------------- |
-| ubuntu-gcp LTS | 22.4.x  | Operating System |
-| Kubernetes     | 1.28.x  | Kubernetes       |
-| cni-calico     | 3.27.x  | Network          |
-| csi-gcp-driver | 1.12.x  | Storage          |
+| Pack Name                   | Version | Registry    | Layer            |
+| --------------------------- | ------- | ----------- | ---------------- |
+| Ubuntu                      | 22.4.x  | Public Repo | Operating System |
+| Palette eXtended Kubernetes | 1.28.x  | Public Repo | Kubernetes       |
+| Calico                      | 3.27.x  | Public Repo | Network          |
+| GCE Persistent Disk CSI     | 1.12.x  | Public Repo | Storage          |
 
-As you fill out the information for each layer, click on **Next** to proceed to the next layer.
+As you select each layer, click on **Next Layer** to proceed to the next one.
 
-Click on **Confirm** after you have completed filling out all the core layers.
+Click on **Confirm** and then **Next** after you have completed selecting all the core layers.
 
 ![GCP cluster profile view](/getting-started/gcp/getting-started_create-cluster-profile_cluster_profile_stack.webp)
 
@@ -99,7 +100,7 @@ Select the **Enable Hello Universe API** preset. The pack manifest changes accor
 The pack requires two values to be replaced for the authorization token and for the database password when using this
 preset. Replace these values with your own base64 encoded values. The
 [_hello-universe_](https://github.com/spectrocloud/hello-universe?tab=readme-ov-file#single-load-balancer) repository
-provides a token that you can use.
+provides an unencoded token that you can use.
 
 Click on **Confirm Updates**. The manifest editor closes.
 

diff --git a/docs/docs-content/getting-started/gcp/deploy-k8s-cluster.md b/docs/docs-content/getting-started/gcp/deploy-k8s-cluster.md
@@ -145,6 +145,13 @@ application with a frontend, API server, and Postgres database.
 
 Use the following steps to remove all the resources you created for the tutorial.
 
+:::tip
+
+If you plan to explore the [Deploy Cluster Profile Updates](./update-k8s-cluster.md) tutorial, do not delete your
+cluster, as it is a prerequisite for the tutorial.
+
+:::
+
 To remove the cluster, navigate to the left **Main Menu** and click on **Clusters**. Select the cluster you want to
 delete to access its details page.