diff --git a/docs/docs-content/clusters/edge/site-deployment/deploy-cluster.md b/docs/docs-content/clusters/edge/site-deployment/deploy-cluster.md index 92a736ffbd..19c2457812 100644 --- a/docs/docs-content/clusters/edge/site-deployment/deploy-cluster.md +++ b/docs/docs-content/clusters/edge/site-deployment/deploy-cluster.md @@ -80,15 +80,15 @@ You can refer to the [Prepare the DHCP Server for vSphere](https://docs.vmware.c ## Build Edge Artifacts -In this section, you will use the [CanvOS](https://github.com/spectrocloud/CanvOS/blob/main/README.md) utility to build an Edge installer ISO image and provider images for all the Palette-supported Kubernetes versions. The utility builds multiple provider images, so you can use either one that matches the desired Kubernetes version you want to use with your cluster profile. +In this section, you will use the [CanvOS](https://github.com/spectrocloud/CanvOS/blob/main/README.md) utility to build an Edge installer ISO image and provider images for all the Palette-supported Kubernetes versions. The utility builds multiple provider images, so you can use any image that matches the desired Kubernetes version you want to use with your cluster profile. You must perform this part of the tutorial on a Linux machine with an AMD64(x86_64) processor architecture that has network connectivity to your VMware vCenter environment. -This tutorial builds and uses the provider image compatible with K3s v1.25.2. +This tutorial builds and uses the provider image compatible with K3s v1.27.5. ### Check Out Starter Code Issue the following and subsequent command-line instructions on your Linux machine, which this tutorial refers to as the development environment. -Clone the [CanvOS](https://github.com/spectrocloud/CanvOS) GitHub repository containing the starter code to build Edge artifacts. +Clone the [CanvOS](https://github.com/spectrocloud/CanvOS) GitHub repository containing the starter code to build Edge artifacts. ```bash git clone https://github.com/spectrocloud/CanvOS.git @@ -100,17 +100,17 @@ Change to the **CanvOS** directory. cd CanvOS ``` -View the available [git tag](https://github.com/spectrocloud/CanvOS/tags). -
+ +View the available [git tags](https://github.com/spectrocloud/CanvOS/tags). ```bash git tag ``` -Check out the newest available tag. This guide uses **v3.4.3** tag as an example. +Check out the newest available tag. This guide uses **v4.1.2** tag as an example. -```shell -git checkout v3.4.3 +```bash +git checkout v4.1.2 ``` ## Define Arguments @@ -126,7 +126,7 @@ export CUSTOM_TAG=demo Issue the command below to create the **.arg** file with the custom tag. The remaining arguments will use the default values. For example, `ubuntu` is the default operating system, `demo` is the default tag, and [ttl.sh](https://ttl.sh/) is the default image registry. The default ttl.sh image registry is free and does not require a sign-up. Images pushed to ttl.sh are ephemeral and will expire after the 24 hrs time limit. -Using the arguments defined in the **.arg** file, the final provider images you generate will have the following naming convention, `[IMAGE_REGISTRY]/[IMAGE_REPO]:[CUSTOM_TAG]`. In this example, the provider images will be `ttl.sh/ubuntu:k3s-1.25.2-v3.4.3-demo`. Refer to the **.arg.template** sample file in the current directory or the [README](https://github.com/spectrocloud/CanvOS#readme) to learn more about the default values. +Using the arguments defined in the **.arg** file, the final provider images you generate will have the following naming convention, `[IMAGE_REGISTRY]/[IMAGE_REPO]:[CUSTOM_TAG]`. In this example, the provider images will be `ttl.sh/ubuntu:k3s-1.27.5-v4.1.2-demo`. Refer to the **.arg.template** sample file in the current directory or the [README](https://github.com/spectrocloud/CanvOS#readme) to learn more about the default values. ```bash cat << EOF > .arg @@ -137,8 +137,8 @@ IMAGE_REPO=ubuntu OS_VERSION=22 K8S_DISTRIBUTION=k3s ISO_NAME=palette-edge-installer -PE_VERSION=$(git describe --abbrev=0 --tags) ARCH=amd64 +UPDATE_KERNEL=false EOF ``` @@ -179,16 +179,10 @@ Use the following command to create the **user-data** file containing the tenant description: "Stores the registration token and lets the agent use the auto-registration functionality and authenticate with the provided token.", tooltipPlacement: "rightTop", }, - { - x: 500, - y: 224, - label: 2, - description: "Instructs the installer to turn the host machine off once the installation is complete.", - }, { x: 600, y: 300, - label: 3, + label: 2, description: "Sets the login credentials for Edge hosts. The login credentials allow you to SSH log in to the edge host for debugging purposes.", tooltipPlacement: "rightTop", } @@ -201,8 +195,8 @@ cat << EOF > user-data stylus: site: edgeHostToken: $token -install: - poweroff: true + paletteEndpoint: api.spectrocloud.com + users: - name: kairos passwd: kairos @@ -224,9 +218,9 @@ The expected output should show that the `edgeHostToken` and login credentials f #cloud-config stylus: site: + paletteEndpoint: api.spectrocloud.com edgeHostToken: 62ElvdMeX5MdOESgTleBjjKQg8YkaIN3 -install: - poweroff: true + users: - name: kairos passwd: kairos @@ -263,7 +257,7 @@ options: system.repo: ubuntu system.k8sDistribution: k3s system.osName: ubuntu - system.peVersion: v3.4.3 + system.peVersion: v4.1.2 system.customTag: demo system.osVersion: 22 ``` @@ -298,18 +292,30 @@ docker images --filter=reference='*/*:*demo' ```hideClipboard bash {3,4} REPOSITORY TAG IMAGE ID CREATED SIZE -ttl.sh/ubuntu k3s-1.24.6-v3.4.3-demo 3a672a023bd3 45 minutes ago 4.61GB -ttl.sh/ubuntu k3s-1.25.2-v3.4.3-demo 0217de3b9e7c 45 minutes ago 4.61GB +ttl.sh/ubuntu k3s-1.25.13-v4.1.2-demo b25cfbaadd79 2 hours ago 4.13GB +ttl.sh/ubuntu k3s-1.25.13-v4.1.2-demo_linux_amd64 b25cfbaadd79 2 hours ago 4.13GB +ttl.sh/ubuntu k3s-1.26.8-v4.1.2-demo f2d870f3b8bd 2 hours ago 4.12GB +ttl.sh/ubuntu k3s-1.26.8-v4.1.2-demo_linux_amd64 f2d870f3b8bd 2 hours ago 4.12GB +ttl.sh/ubuntu k3s-1.27.2-v4.1.2-demo 6df130ae97e2 2 hours ago 4.12GB +ttl.sh/ubuntu k3s-1.27.2-v4.1.2-demo_linux_amd64 6df130ae97e2 2 hours ago 4.12GB +ttl.sh/ubuntu k3s-1.26.4-v4.1.2-demo a14409825650 2 hours ago 4.13GB +ttl.sh/ubuntu k3s-1.26.4-v4.1.2-demo_linux_amd64 a14409825650 2 hours ago 4.13GB +ttl.sh/ubuntu k3s-1.27.5-v4.1.2-demo bee555567baf 2 hours ago 4.12GB +ttl.sh/ubuntu k3s-1.27.5-v4.1.2-demo_linux_amd64 bee555567baf 2 hours ago 4.12GB +ttl.sh/ubuntu k3s-1.25.2-v4.1.2-demo 9c465e51a671 2 hours ago 4.1GB +ttl.sh/ubuntu k3s-1.25.2-v4.1.2-demo_linux_amd64 9c465e51a671 2 hours ago 4.1GB +ttl.sh/ubuntu k3s-1.24.6-v4.1.2-demo 6a56cdd58c0b 2 hours ago 4.1GB +ttl.sh/ubuntu k3s-1.24.6-v4.1.2-demo_linux_amd64 6a56cdd58c0b 2 hours ago 4.1GB ``` ## Push Provider Images Push the provider images to the image registry indicated in the **.arg** file so that you can reference the provider image later in your cluster profile. -Since we used the provider image compatible with K3s v1.25 in the cluster profile, you would use the following command to push the provider image compatible with K3s v1.25 to the image registry. If you want to use the other provider image compatible with K3s v1.24 instead, push that version to the image registry. The example below and default behavior uses the [ttl.sh](https://ttl.sh/) image registry. This image registry is free and does not require you to sign up to use it. Images pushed to ttl.sh are ephemeral and will expire after 24 hours. +Since we used the provider image compatible with K3s v1.27 in the cluster profile, you would use the following command to push the provider image compatible with K3s v1.27 to the image registry. If you want to use the other provider image, push that version to the image registry. The example below and default behavior uses the [ttl.sh](https://ttl.sh/) image registry. This image registry is free and does not require you to sign up to use it. Images pushed to ttl.sh are ephemeral and will expire after 24 hours. ```bash -docker push ttl.sh/ubuntu:k3s-1.25.2-v3.4.3-demo +docker push ttl.sh/ubuntu:k3s-1.27.5-v4.1.2-demo ``` :::caution @@ -389,7 +395,7 @@ The next step is to use the following `docker run` command to trigger Packer bui - The `--env-file` option reads the **.packerenv** file. -- The `--volume ` option mounts a local directory to our official tutorials container, `ghcr.io/spectrocloud/tutorials:1.0.7`. +- The `--volume ` option mounts a local directory to our official tutorials container, `ghcr.io/spectrocloud/tutorials:1.0.8`. - The `sh -c "cd edge/vmware/packer/ && packer build -force --var-file=vsphere.hcl build.pkr.hcl` shell sub-command changes to the container's **edge/vmware/packer/** directory and invokes `packer build` to create the VM template. The `packer build` command has the following options: @@ -423,7 +429,7 @@ The next step is to use the following `docker run` command to trigger Packer bui :::info - Should you need to change the VM template name or VM settings defined in the **vsphere.hcl** file, or review the Packer script, you must open a bash session into the container using the `docker run -it --env-file .packerenv --volume "${ISOFILEPATH}:/edge/vmware/packer/build" ghcr.io/spectrocloud/tutorials:1.0.7 bash` command, and change to the **edge/vmware/packer/** directory to make the modifications. After you finish the modifications, issue the `packer build -force --var-file=vsphere.hcl build.pkr.hcl` command to trigger the Packer build process. + Should you need to change the VM template name or VM settings defined in the **vsphere.hcl** file, or review the Packer script, you must open a bash session into the container using the `docker run -it --env-file .packerenv --volume "${ISOFILEPATH}:/edge/vmware/packer/build" ghcr.io/spectrocloud/tutorials:1.0.8 bash` command, and change to the **edge/vmware/packer/** directory to make the modifications. After you finish the modifications, issue the `packer build -force --var-file=vsphere.hcl build.pkr.hcl` command to trigger the Packer build process. ::: @@ -434,7 +440,7 @@ Issue the following command to trigger the Packer build process to create a VM t docker run --interactive --tty --rm \ --env-file .packerenv \ --volume "${ISOFILEPATH}:/edge/vmware/packer/build" \ - ghcr.io/spectrocloud/tutorials:1.0.7 \ + ghcr.io/spectrocloud/tutorials:1.0.8 \ sh -c "cd edge/vmware/packer/ && packer build -force --var-file=vsphere.hcl build.pkr.hcl" ``` @@ -490,7 +496,7 @@ cat .goenv The next step is to use the following `docker run` command to clone the VM template and provision three VMs. Here is an explanation of the options and sub-command used below: -- The `--env-file` option reads the **.goenv** file in our official `ghcr.io/spectrocloud/tutorials:1.0.7` tutorials container. +- The `--env-file` option reads the **.goenv** file in our official `ghcr.io/spectrocloud/tutorials:1.0.8` tutorials container. - The `sh -c "cd edge/vmware/clone_vm_template/ && ./deploy-edge-host.sh"` shell sub-command changes to the container's **edge/vmware/clone_vm_template/** directory and invokes the **deploy-edge-host.sh** shell script. @@ -531,7 +537,7 @@ export GOVC_FOLDER="${vcenter_folder}" :::info -Suppose you have changed the VM template name in the previous step or need to change the number of VMs to provision. In that case, you must modify the **setenv.sh** script. To do so, you can reuse the container bash session from the previous step if it is still active, or you can open another bash session into the container using the `docker run -it --env-file .goenv ghcr.io/spectrocloud/tutorials:1.0.7 bash` command. If you use an existing container bash session, create the **.goenv** file described above and source it in your container environment. Next, change to the **edge/vmware/clone_vm_template/** directory to modify the **setenv.sh** script, and issue the `./deploy-edge-host.sh` command to deploy the VMs. +Suppose you have changed the VM template name in the previous step or need to change the number of VMs to provision. In that case, you must modify the **setenv.sh** script. To do so, you can reuse the container bash session from the previous step if it is still active, or you can open another bash session into the container using the `docker run -it --env-file .goenv ghcr.io/spectrocloud/tutorials:1.0.8 bash` command. If you use an existing container bash session, create the **.goenv** file described above and source it in your container environment. Next, change to the **edge/vmware/clone_vm_template/** directory to modify the **setenv.sh** script, and issue the `./deploy-edge-host.sh` command to deploy the VMs. ::: @@ -540,7 +546,7 @@ Issue the following command to clone the VM template and provision three VMs. ```bash docker run -it --rm \ --env-file .goenv \ - ghcr.io/spectrocloud/tutorials:1.0.7 \ + ghcr.io/spectrocloud/tutorials:1.0.8 \ sh -c "cd edge/vmware/clone_vm_template/ && ./deploy-edge-host.sh" ``` @@ -634,7 +640,7 @@ options: system.repo: ubuntu system.k8sDistribution: k3s system.osName: ubuntu - system.peVersion: v3.4.3 + system.peVersion: v4.1.2 system.customTag: demo system.osVersion: 22 ``` @@ -653,10 +659,10 @@ Click on the **Next layer** button to add the following Kubernetes layer to your |**Pack Type**|**Registry**|**Pack Name**|**Pack Version**| |---|---|---|---| -|Kubernetes|Public Repo|Palette Optimized K3s|`1.25.x`| +|Kubernetes|Public Repo|Palette Optimized K3s|`1.27.x`| -Select the K3s version 1.25.x. 1.25.X because earlier in this tutorial, you pushed a provider image compatible with K3s v1.25.2 to the *ttl.sh* image registry. The `system.uri` attribute of the BYOOS pack will reference the Kubernetes version you select using the `{{ .spectro.system.kubernetes.version }}` [macro](../../cluster-management/macros.md). +Select the K3s version 1.27.x. 1.27.X because earlier in this tutorial, you pushed a provider image compatible with K3s v1.27.5 to the *ttl.sh* image registry. The `system.uri` attribute of the BYOOS pack will reference the Kubernetes version you select using the `{{ .spectro.system.kubernetes.version }}` [macro](../../cluster-management/macros.md). Click on the **Next layer** button, and add the following network layer. This example uses the Calico Container Network Interface (CNI). However, you can choose a different CNI pack that fits your needs, such as Flannel, Cilium, or Custom CNI. @@ -868,7 +874,7 @@ Switch back to the **CanvOS** directory in the Linux development environment con ```bash docker run --interactive --tty --rm --env-file .goenv \ - ghcr.io/spectrocloud/tutorials:1.0.7 \ + ghcr.io/spectrocloud/tutorials:1.0.8 \ sh -c "cd edge/vmware/clone_vm_template/ && ./delete-edge-host.sh" ``` @@ -890,8 +896,20 @@ docker images Note the provider image name and tags, and use the following command syntax to remove all provider images. ```bash -docker image rm --force ttl.sh/ubuntu:k3s-1.25.2-v3.4.3-demo -docker image rm --force ttl.sh/ubuntu:k3s-1.24.6-v3.4.3-demo +docker rmi ttl.sh/ubuntu:k3s-1.25.13-v4.1.2-demo +docker rmi ttl.sh/ubuntu:k3s-1.25.13-v4.1.2-demo_linux_amd64 +docker rmi ttl.sh/ubuntu:k3s-1.26.8-v4.1.2-demo +docker rmi ttl.sh/ubuntu:k3s-1.26.8-v4.1.2-demo_linux_amd64 +docker rmi ttl.sh/ubuntu:k3s-1.27.2-v4.1.2-demo +docker rmi ttl.sh/ubuntu:k3s-1.27.2-v4.1.2-demo_linux_amd64 +docker rmi ttl.sh/ubuntu:k3s-1.26.4-v4.1.2-demo +docker rmi ttl.sh/ubuntu:k3s-1.26.4-v4.1.2-demo_linux_amd64 +docker rmi ttl.sh/ubuntu:k3s-1.27.5-v4.1.2-demo +docker rmi ttl.sh/ubuntu:k3s-1.27.5-v4.1.2-demo_linux_amd64 +docker rmi ttl.sh/ubuntu:k3s-1.25.2-v4.1.2-demo +docker rmi ttl.sh/ubuntu:k3s-1.25.2-v4.1.2-demo_linux_amd64 +docker rmi ttl.sh/ubuntu:k3s-1.24.6-v4.1.2-demo +docker rmi ttl.sh/ubuntu:k3s-1.24.6-v4.1.2-demo_linux_amd64 ``` ### Delete VMware vSphere Resources diff --git a/docs/docs-content/clusters/public-cloud/aws/add-aws-accounts.md b/docs/docs-content/clusters/public-cloud/aws/add-aws-accounts.md index 5a18387b51..f921baea0c 100644 --- a/docs/docs-content/clusters/public-cloud/aws/add-aws-accounts.md +++ b/docs/docs-content/clusters/public-cloud/aws/add-aws-accounts.md @@ -21,17 +21,17 @@ Palette supports integration with AWS Cloud Accounts. This also includes support ## AWS Account -
+This section provides guidance in creating an AWS account that uses static or dynamic access credentials. ### Static Access Credentials -To add an AWS cloud account using static access credentials follow these steps: +Use the steps below to add an AWS cloud account using static access credentials. #### Prerequisites - An AWS account - Sufficient access to create an IAM role or IAM user. -- Palette IAM policies. Please review the [Required IAM Policies](required-iam-policies.md) section for guidance. +- Palette IAM policies. Review the [Required IAM Policies](required-iam-policies.md) section for guidance. #### Add AWS Account to Palette @@ -40,65 +40,71 @@ To add an AWS cloud account using static access credentials follow these steps: - [IAM User creation guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). -2. In the AWS console, assign the Palette required IAM policies to the role or the IAM user that Palette will use. +2. In the AWS console, assign the Palette-required IAM policies to the IAM role or the IAM user that Palette will use. -3. Log in to [Palette](https://console.spectrocloud.com) as Tenant admin. +3. Log in to [Palette](https://console.spectrocloud.com) as tenant admin. -4. Go to **Tenant Settings** > **Cloud Accounts** and click **+Add AWS Account**. +4. From the left **Main Menu**, click on **Tenant Settings**. -5. In the cloud account creation wizard provide the following information: +5. Select **Cloud Accounts**, and click **+Add AWS Account**. + + +6. In the cloud account creation wizard provide the following information: * **Account Name:** Custom name for the cloud account. * **Description:** Optional description for the cloud account. - * **Partition:** Choose **AWS** from the drop-down menu. + * **Partition:** Choose **AWS** from the **drop-down Menu**. * **Credentials:** * AWS Access key * AWS Secret access key -6. Click the **Validate** button to validate the credentials. +7. Click the **Validate** button to validate the credentials. -7. Once the credentials are validated, the **Add IAM Policies** toggle displays. Toggle **Add IAM Policies** on. +8. Once the credentials are validated, the **Add IAM Policies** toggle displays. Toggle **Add IAM Policies** on. -8. A drop-down menu displays a lists of available AWS IAM policies in your AWS account. Select any desired IAM policies you want to assign to Palette IAM role or IAM user. +9. Use the **drop-down Menu**, which lists available IAM policies in your AWS account, to select any desired IAM policies you want to assign to Palette IAM role or IAM user. #### Validate -You can validate the account is available in Palette by reviewing the list of cloud accounts. To review the list of cloud accounts navigate to the left **Main Menu**. Click on **Tenant Settings**. Next, click on **Cloud Accounts**. Your newly added AWS cloud account is listed under the AWS sections. +You can validate the account is available in Palette by reviewing the list of cloud accounts. To review the list of cloud accounts, navigate to the left **Main Menu** and click on **Tenant Settings**. Next, click on **Cloud Accounts**. Your newly added AWS cloud account is listed under the AWS section. ### Dynamic Access Credentials -To add an AWS cloud account using STS credentials follow the steps below: +Use the steps below to add an AWS cloud account using Security Token Service (STS) credentials. #### Prerequisites -- An AWS account +- An AWS account. - Sufficient access to create an IAM role or IAM user. -- Palette IAM policies. Please review the [Required IAM Policies](required-iam-policies.md) section for guidance. +- Palette IAM policies. Review the [Required IAM Policies](required-iam-policies.md) section for guidance. #### Add AWS Account to Palette -1. Log in to [Palette](https://console.spectrocloud.com) as Tenant admin. +1. Log in to [Palette](https://console.spectrocloud.com) as tenant admin. -2. Go to **Tenant Settings** > **Cloud Accounts** and click **+Add AWS Account**. +2. From the left **Main Menu**, click on **Tenant Settings**. -3. In the cloud account creation wizard give the following information: - * **Account Name** - * **Description** - * Select **STS** authentication for validation: +3. Select **Cloud Accounts**, and click **+Add AWS Account**. + + +4. In the cloud account creation wizard give the following information: + * **Account Name**: Custom name for the cloud account. + * **Description**: Optional description for the cloud account. + * Select **STS** authentication for validation. -4. You will be provided with information on the right hand-side of the wizard. You will need this information to create an IAM Role for Palette. The following table lists out the information provided by the wizard after your selects **STS**. +5. You will be provided with information on the right side of the wizard. You will need this information to create an IAM Role for Palette. The following table lists the information provided by the wizard after you select **STS**. |**Parameter**|**Description**| |---------|---------------| @@ -106,29 +112,29 @@ To add an AWS cloud account using STS credentials follow the steps below: |**Account ID**|Copy the Account ID displayed on the UI| |**Require External ID**| Enable| |**External ID**|Copy the External ID displayed on the UI| - |**Permissions Policy**|Search and select the 4 policies added in step #2| + |**Permissions Policy**|Search and select the 4 policies added in step 2| |**Role Name**|SpectroCloudRole| -5. In the AWS console, create a new IAM role for Palette. Use the following resources if you need additional help. +6. In the AWS console, create a new IAM role for Palette. Use the following resources if you need additional help. - [IAM Role creation guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html). - [IAM User creation guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). -6. In the AWS console, assign the [Palette required IAM policies](required-iam-policies.md) to the role that Palette will use. +7. In the AWS console, assign the [Palette required IAM policies](required-iam-policies.md) to the role that Palette will use. -7. In the AWS console, browse to the **Role Details** page and copy the Amazon Resource Name (ARN) for the role. +8. In the AWS console, browse to the **Role Details** page and copy the Amazon Resource Name (ARN) for the role. -8. In Palette, paste the role ARN into the **ARN** input box. +9. In Palette, paste the role ARN into the **ARN** input box. -9. Click the **Validate** button to validate the credentials. +10. Click the **Validate** button to validate the credentials. #### Validate -You can validate the account is available in Palette by reviewing the list of cloud accounts. To review the list of cloud accounts navigate to the left **Main Menu**. Click on **Tenant Settings**. Next, click on **Cloud Accounts**. Your newly added AWS cloud account is listed under the AWS sections. +You can validate the account is available in Palette by reviewing the list of cloud accounts. To review the list of cloud accounts navigate to the left **Main Menu**. Click on **Tenant Settings**. Next, click on **Cloud Accounts**. Your newly added AWS cloud account is listed under the AWS section. @@ -137,11 +143,13 @@ You can validate the account is available in Palette by reviewing the list of cl ## AWS GovCloud Account -Palette supports integration with [AWS GovCloud (US)](https://aws.amazon.com/govcloud-us/?whats-new-ess.sort-by=item.additionalFields.postDateTime&whats-new-ess.sort-order=desc). Using Palette you can deploy Kubernetes clusters to your AWS GovCloud account. To get started with AWS GovCloud and Palette, use the following steps. -
+Palette supports integration with [AWS GovCloud (US)](https://aws.amazon.com/govcloud-us/?whats-new-ess.sort-by=item.additionalFields.postDateTime&whats-new-ess.sort-order=desc). Using Palette you can deploy Kubernetes clusters to your AWS GovCloud account. This section provides guidance in creating an AWS GovCloud account that uses static or dynamic access credentials. ### Static Access Credentials +Use the steps below to add an AWS cloud account using static access credentials. + + #### Prerequisites - An AWS account @@ -161,10 +169,13 @@ Palette supports integration with [AWS GovCloud (US)](https://aws.amazon.com/gov 3. Log in to [Palette](https://console.spectrocloud.com) as Tenant admin. -4. Go to **Tenant Settings** > **Cloud Accounts** and click **+Add AWS Account**. +4. From the left **Main Menu**, click on **Tenant Settings**. + + +5. Select **Cloud Accounts**, and click **+Add AWS Account**. -5. In the cloud account creation wizard provide the following information: +6. In the cloud account creation wizard provide the following information: * **Account Name:** Custom name for the cloud account. * **Description:** Optional description for the cloud account. @@ -175,20 +186,20 @@ Palette supports integration with [AWS GovCloud (US)](https://aws.amazon.com/gov * AWS Secret access key -6. Click the **Validate** button to validate the credentials. +7. Click on the **Validate** button to validate the credentials. -7. Once the credentials are validated, the **Add IAM Policies** toggle displays. Toggle **Add IAM Policies** on. +8. Once the credentials are validated, the **Add IAM Policies** toggle displays. Toggle **Add IAM Policies** on. -8. A drop-down menu displays a lists of available AWS IAM policies in your AWS account. Select any desired IAM policies you want to assign to Palette IAM role or IAM user. +9. Use the **drop-down Menu**, which lists available IAM policies in your AWS account, to select any desired IAM policies you want to assign to Palette IAM role or IAM user. #### Validate -You can validate the account is available in Palette by reviewing the list of cloud accounts. To review the list of cloud accounts navigate to the left **Main Menu**. Click on **Tenant Settings**. Next, click **Cloud Accounts**. Your newly added AWS cloud account is listed under the AWS sections. +You can validate the account is available in Palette by reviewing the list of cloud accounts. To review the list of cloud accounts navigate to the left **Main Menu**. Click on **Tenant Settings**. Next, click **Cloud Accounts**. Your newly added AWS cloud account is listed under the AWS section. ### Dynamic Access Credentials -To add an AWS GovCloud cloud account using STS credentials follow the steps below: +Use the steps below to add an AWS cloud account using STS credentials. #### Prerequisites @@ -202,16 +213,19 @@ To add an AWS GovCloud cloud account using STS credentials follow the steps belo 1. Log in to [Palette](https://console.spectrocloud.com) as Tenant admin. -2. Go to **Tenant Settings** > **Cloud Accounts** and click **+Add AWS Account**. +2. From the left **Main Menu**, click on **Tenant Settings**. + + +3. Select **Cloud Accounts**, and click **+Add AWS Account**. -3. In the cloud account creation wizard give the following information: +4. In the cloud account creation wizard give the following information: * **Account Name** * **Description** * Select **STS** authentication for validation: -4. You will be provided with information on the right hand-side of the wizard. You will need this information to create an IAM Role for Palette. The following table lists out the information provided by the wizard after you selects **STS**. +5. You will be provided with information on the right side of the wizard. You will need this information to create an IAM Role for Palette. The following table lists the information provided by the wizard after you select **STS**. |**Parameter**|**Description**| |---------|---------------| @@ -222,21 +236,21 @@ To add an AWS GovCloud cloud account using STS credentials follow the steps belo |**Permissions Policy**|Search and select the 4 policies added in step #2| |**Role Name**|SpectroCloudRole| -5. In the AWS console, create a new IAM role for Palette. Use the following resources if you need additional help. +6. In the AWS console, create a new IAM role for Palette. Use the following resources if you need additional help. - [IAM Role creation guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html). - [IAM User creation guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). -6. In the AWS console, assign the [Palette required IAM policies](required-iam-policies.md) to the role that Palette will use. +7. In the AWS console, assign the [Palette required IAM policies](required-iam-policies.md) to the role that Palette will use. -7. In the AWS console, browse to the **Role Details** page and copy the Amazon Resource Name (ARN) for the role. +8. In the AWS console, browse to the **Role Details** page and copy the Amazon Resource Name (ARN) for the role. -8. In Palette, paste the role arn into the **ARN** input box. +9. In Palette, paste the role ARN into the **ARN** input box. -9. Click the **Validate** button to validate the credentials. +10. Click on the **Validate** button to validate the credentials. #### Validate diff --git a/docs/docs-content/clusters/public-cloud/aws/eks.md b/docs/docs-content/clusters/public-cloud/aws/eks.md index 6a11072921..55674de495 100644 --- a/docs/docs-content/clusters/public-cloud/aws/eks.md +++ b/docs/docs-content/clusters/public-cloud/aws/eks.md @@ -1,172 +1,243 @@ --- sidebar_label: "Create and Manage AWS EKS Cluster" title: "Create and Manage AWS EKS Cluster" -description: "Learn how to deploy and manage AWS EKS clusters with Palette" +description: "Learn how to deploy and manage AWS EKS clusters with Palette." hide_table_of_contents: false -tags: ["public cloud", "aws"] +tags: ["public cloud", "aws", "eks"] sidebar_position: 30 --- -Palette supports creating and managing AWS Elastic Kubernetes Service (EKS) clusters deployed to an AWS account. This section guides you on how to create an AWS EKS cluster in AWS that is managed by Palette. +Palette supports creating and managing Amazon Web Services (AWS) Elastic Kubernetes Service (EKS) clusters deployed to an AWS account. This section guides you on how to create an EKS cluster in AWS that Palette manages. ## Prerequisites -The following prerequisites must be met before deploying a cluster to AWS: +- Access to an AWS cloud account. -- Access to an AWS cloud account - Palette integration with AWS account. Review [Add AWS Account](add-aws-accounts.md) for guidance. -- An infrastructure cluster profile for AWS EKS. Review [Create an Infrastructure Profile](../../../profiles/cluster-profiles/create-cluster-profiles/create-infrastructure-profile.md) for guidance. -- An [EC2 Key Pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) in the target region. -- Palette creates compute, network, and storage resources in AWS during the provisioning of Kubernetes clusters. Ensure there is sufficient capacity in the preferred AWS region for the creation of the following resources: - - vCPU - - VPC + +- An infrastructure cluster profile for AWS EKS. When you create the profile, ensure you choose **EKS** as the **Managed Kubernetes** cloud type. Review [Create an Infrastructure Profile](../../../profiles/cluster-profiles/create-cluster-profiles/create-infrastructure-profile.md) for guidance. + +- An EC2 key pair for the target region that provides a secure connection to your EC2 instances. To learn how to create a key pair, refer to the [Amazon EC2 key pairs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) resource. + +- To access your EKS cluster using kubectl, you will need the [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) plugin installed. If you are using a custom OIDC provider, you will need the [kubelogin](https://github.com/int128/kubelogin) plugin installed. Refer to the [Access EKS Cluster](#access-eks-cluster) section for more information. + + +- To use secrets encryption, which is available only during EKS cluster creation, you must have created an AWS Key Management Service (KMS) key. If you do not have one, review [Enable Secrets Encryption for EKS Cluster](enable-secrets-encryption-kms-key.md) for guidance. + +- If you do not provide your own Virtual Private Cloud (VPC), Palette creates one for you with compute, network, and storage resources in AWS when it provisions Kubernetes clusters. Ensure there is sufficient capacity in the preferred AWS region to create the following resources. Note that Palette does not create these resources if you specify an existing VPC. + - Virtual CPU (vCPU) + - Virtual Private Cloud (VPC) - Elastic IP - Internet Gateway - Elastic Load Balancers - - NAT Gateway + - Network Address Translation (NAT) Gateway +
-:::info + :::info -The following tags should be added to the virtual private network (VPC) public subnets to enable automatic subnet discovery for integration with AWS load balancer service. Replace the value `yourClusterName` with your cluster's name. -- `kubernetes.io/role/elb = 1` -- `sigs.k8s.io/cluster-api-provider-aws/role = public` -- `kubernetes.io/cluster/[yourClusterName] = shared` -- `sigs.k8s.io/cluster-api-provider-aws/cluster/[yourClusterName] = owned` + To enable automated subnet discovery to create external load balancers, you need to add tags to the Virtual Private Cloud (VPC) public subnets. For more information about tagging VPC networks, refer to the AWS [EKS VPC Subnet Discovery](https://repost.aws/knowledge-center/eks-vpc-subnet-discovery) reference guide. Use the AWS Tag Editor and specify the region and resource type. Then, add the following tags. Replace the value `yourClusterName` with your cluster's name. To learn more about the Tag Editor, refer to the [AWS Tag Editor](https://docs.aws.amazon.com/tag-editor/latest/userguide/tag-editor.html) reference guide. -::: + - `kubernetes.io/role/elb = 1` + - `sigs.k8s.io/cluster-api-provider-aws/role = public` + - `kubernetes.io/cluster/[yourClusterName] = shared` + - `sigs.k8s.io/cluster-api-provider-aws/cluster/[yourClusterName] = owned` -## Deploy an AWS Cluster + ::: -Use the following steps to provision a new AWS EKS cluster: +Use the following steps to deploy an EKS cluster on AWS. -1. Ensure you are in the correct project scope. +1. Log in to [Palette](https://console.spectrocloud.com/). +2. Ensure you are in the correct project scope. -2. Navigate to the left **Main Menu** and click on **Clusters** +3. From the left **Main Menu** select **Clusters**, and click on the **Add New Cluster** button. +4. Select **Deploy New Cluster** on the next page Palette displays. This will allow you to deploy a cluster using your own cloud account. -3. Click on **Add New Cluster** +5. Select **AWS** and click on the **Start AWS Configuration** button. +6. Fill out the following basic information, and click **Next** to continue. -4. You will receive a prompt asking you if you want to deploy a new cluster or import an existing cluster. Click on **Deploy New Cluster** + | **Field** | **Description** | + |-----------|-----------------| + | **Cluster Name**| A custom name for the cluster. | + | **Description**| Use the description to provide context about the cluster.| + | **Tags**| Assign any desired cluster tags. Tags on a cluster are propagated to the Virtual Machines (VMs) deployed to the target environments. Example: `region:us-east-1a` or `zone:vpc-private-us-east-1a`.| + | **Cloud Account** | If you already added your AWS account in Palette, select it from the **drop-down Menu**. Otherwise, click on **Add New Account** and add your AWS account information. | + To learn how to add an AWS account, review the [Add an AWS Account to Palette](add-aws-accounts.md) guide. -5. Select **AWS** and click on **Start AWS Configuration** + +7. Select **EKS** listed under **Managed Kubernetes**. -6. Populate the wizard page with the following information: name, description, tags and AWS account. Tags on a cluster are propagated to the VMs deployed to the target environments. Click on **Next** after you have filled out all the required information. +8. Select the EKS cluster profile you created and click on **Next**. Palette displays the cluster profile layers. -7. Selected **Managed Kubernetes** and click on your cluster profile that supports AWS EKS. Click on **Next**. +9. Review the profile layers and customize parameters as desired in the YAML files that display when you select a layer. You can configure custom OpenID Connect (OIDC) for EKS clusters at the Kubernetes layer. Check out [Access EKS Cluster](#access-eks-cluster) if you need more guidance. +10. Click on **Next** to continue. -8. Review and customize pack parameters, as desired. By default, parameters for all packs are set with values, defined in the cluster profile. Click on **Next**. +11. Provide the following cluster configuration information and click on **Next** to continue. + |**Parameter**| **Description**| + |-------------|---------------| + |**Static Placement** | By default, Palette uses dynamic placement. This creates a new Virtual Private Cloud (VPC) for the cluster that contains two subnets in different Availability Zones (AZs), which is required for EKS cluster deployment. Palette places resources in these clusters, manages the resources, and deletes them when the corresponding cluster is deleted.

If you want to place resources into pre-existing VPCs, enable the **Static Placement** option, and provide the VPCID in the **VPCID** field that displays with this option enabled. You will need to specify two subnets in different Availability Zones (AZs). | + |**Region** | Use the **drop-down Menu** to choose the AWS region where you would like to provision the cluster.| + |**SSH Key Pair Name** | Choose the SSH key pair for the region you selected. SSH key pairs must be pre-configured in your AWS environment. This is called an EC2 Key Pair in AWS. The key you select is inserted into the provisioned VMs.| + |**Cluster Endpoint Access**| This setting provides access to the Kubernetes API endpoint. Select **Private**, **Public** or **Private & Public**. For more information, refer to the [Amazon EKS cluster endpoint access control](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) reference guide.| + |**Public Access CIDRs** |This setting controls which IP address CIDR ranges can access the cluster. To fully allow unrestricted network access, enter `0.0.0.0/0` in the field. For more information, refer to the [Amazon EKS cluster endpoint access control](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) reference guide.| + |**Private Access CIDRs** |This setting controls which private IP address CIDR ranges can access the cluster. Private CIDRs provide a way to specify private, self-hosted, and air-gapped networks or Private Cloud Gateway (PCG) that may be located in other VPCs connected to the VPC hosting the cluster endpoint.

To restrict network access, enter the IP address CIDR range that will provide access to the cluster. Although `0.0.0.0/0` is pre-populated in this field, only IPs that can reach the private endpoint are those within the VPC or any other connected VPCs. For example, while using `0.0.0.0/0` would allow traffic throughout the VPC and all peered VPCs, specifying the VPC CIDR `10.0.0.0/16` would limit traffic to an individual VPC. For more information, refer to the [Amazon EKS cluster endpoint access control](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) reference guide.| + |**Enable Encryption**| Use this option for secrets encryption. You must have an existing AWS Key Management Service (KMS) key you can use. Toggle the **Enable encryption** option and use the **drop-down Menu** in the **ARN** field to select the KMS key ARN.

If you do not have a KMS key and want to create one to use this option, review [Enable Secrets Encryption for EKS Cluster](enable-secrets-encryption-kms-key.md). Once your KMS key is created, return to this Cluster Config step to enable secrets encryption and specify the KMS key ARN. | -9. Provide the AWS cloud account and placement information. + :::caution - |**Parameter**| **Description**| - |-------------|---------------| - |**Cloud Account** | Select the desired cloud account. AWS cloud accounts with AWS credentials need to be pre-configured in project settings.| - |**Static Placement** | By default, Palette uses dynamic placement, wherein a new VPC with a public and private subnet is created to place cluster resources for every cluster.
These resources are fully managed by Palette and deleted, when the corresponding cluster is deleted. Turn on the **Static Placement** option if it's desired to place resources into preexisting VPCs and subnets.| - |**Region** | Choose the preferred AWS region where you would like the clusters to be provisioned.| - |**SSH Key Pair Name** | Choose the desired SSH Key pair. SSH key pairs need to be pre-configured on AWS for the desired regions. The selected key is inserted into the VMs provisioned.| - |**Cluster Endpoint Access**| Select Private, Public or Private & Public, in order to control communication with the Kubernetes API endpoint. For more information, refer to the [Amazon EKS cluster endpoint access control](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) reference guide. :::caution If you set the cluster endpoint to Public, specify `0.0.0.0/0` in the Public Access CIDR field to open it to all possible IP addresses. Otherwise, Palette will not open it up entirely. :::| - |**Public Access CIDR** |This setting controls which IP address CIDR range can access the cluster. To fully allow unrestricted network access, enter `0.0.0.0/0` in the field. For more information, refer to the [Amazon EKS cluster endpoint access control](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) reference guide.| - |**Enable Encryption**|The user can enable secret encryption by toggling **Enable Encryption**. Provide the provider KMS key ARN to complete the wizard. Review [EKS Cluster Encryption](#eks-cluster-secrets-encryption) for more details.| - |**Worker Pool Update**|Optionally enable the option to update the worker pool in parallel.| - - -10. Make the choice of updating the worker pool in parallel, if required. Click on **Next**. + If you set the cluster endpoint to **Public**, ensure you specify `0.0.0.0/0` in the **Public Access CIDR** field to open it to all possible IP addresses. Otherwise, Palette will not open it up entirely. We recommend specifying the **Private & Public** option to cover all the possibilities. + ::: -11. Configure the master and worker node pools. A single master and a worker node pool are configured by default. This is the section where you can specify the availability zones (AZ), instance types, [instance cost type](architecture#spot-instances), disk size, and the number of nodes. Use the following tables to better understand the available input options. +12. Provide the following node pool and cloud configuration information. If you will be using Fargate profiles, you can add them here. + - Node Configuration Settings + |**Parameter**| **Description**| |-------------|----------------| - |**Name** | A descriptive name for the node pool.| - |**Size** | Make your choice of minimum, maximum and desired sizes for the worker pool. The size of the worker pool will scale between the minimum and maximum size under varying workload conditions. Review the [AWS Instance Type and Pod Capacity](architecture#formula-for-pod-calculation) documentation for help in determining the proper instance type and size. | - |[Taints](../../cluster-management/taints.md#taints): |Optionally enable node affinity optionally to attracts pods to a set of nodes| - |[Labels](../../cluster-management/taints.md#labels): |Optionally enable labels to constrain a pod to only run on a particular set of nodes| - |**Instance Type** | Select the AWS instance type to be used for all nodes in the node pool.| + |**Node pool name** | A descriptive name for the node pool.| + |**Number of nodes in the pool** | Specify the number of nodes in the worker pool.| + |**Additional Labels** | You can add optional labels to nodes in key-value format. For more information about applying labels, review [Apply Labels to Nodes](../../cluster-management/taints.md/#apply-labels-to-nodes). Example: `"environment": "production"` | + |**Taints** | You can apply optional taint labels to a node pool during cluster creation or edit taint labels on an existing cluster. Review the [Node Pool](../../cluster-management/node-pool.md) management page and [Apply Taints to Nodes](../../cluster-management/taints.md/#apply-taints-to-nodes) page to learn more. Toggle the **Taint** button to create a taint label. When tainting is enabled, you need to provide a custom key-value pair. Use the **drop-down Menu** to choose one of the following **Effect** options:
**NoSchedule** - Pods are not scheduled onto nodes with this taint.
**PreferNoSchedule** - Kubernetes attempts to avoid scheduling pods onto nodes with this taint, but scheduling is not prohibited.
**NoExecute** - Existing pods on nodes with this taint are evicted.| + + - Cloud Configuration settings - * Cloud Configuration settings: + |**Parameter**| **Description**| + |-------------|----------------| + | **Instance Option** | Choose a pricing method:
**On-Demand** instances provide stable and uninterrupted compute capacity at a higher cost.
**Spot** instances allow you to bid for unused EC2 capacity at a lower cost.
We recommend you base your choice on your application's requirements. | + |**Instance Type** | Select the instance type to use for all nodes in the node pool.| + |**Enable Nodepool Customization** | To use a pre-configured VM image, toggle this option on and provide the Amazon Machine Image (AMI) ID. When this option is enabled, you can use the **drop-down Menu** to specify the disk type to use. | + |**Root Disk size** | You can choose disk size based on your requirements. The default size is `60`. | - |**Parameter**| **Description**| - |-------------|----------------| - |**Instance Option**:| Choose between on-demand or spot instances| - |**Instance Type**:| Choose an instance type | - |**Availability Zones**:|Select at least one availability zone within the VPC| - |**Disk Size**|Make the choice of disk size as per requirement| + - Fargate Profiles - * You can create one or more Fargate profiles for the EKS cluster to use. + You can create one or more Fargate profiles for the EKS cluster to use. Click **+ Add Fargate Profile**. For more information about Fargate profiles, refer to the [AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html) reference guide. |**Parameter**| **Description**| |-------------|---------------| - |**Name** |Provide a name for the Fargate profile.| + |**Name** |A custom name for the Fargate profile.| |**Subnets** |Pods running on Fargate Profiles are not assigned public IP addresses, so only private subnets (with no direct route to an Internet Gateway) are accepted for this parameter. For dynamic provisioning, this input is not required and subnets are automatically selected.| - |**Selectors** |Define pod selector by providing a target namespace and optionally labels. Pods with matching namespace and app labels are scheduled to run on dynamically provisioned compute nodes.
You can have up to five selectors in a Fargate profile and a pod only needs to match one selector to run using the Fargate profile.| + |**Selectors** |Define a pod selector by providing a target namespace and optional labels. Pods with a matching namespace and app labels are scheduled to run on dynamically provisioned compute nodes.
You can have up to five selectors in a Fargate profile, and a pod only needs to match one selector to run using the Fargate profile.| + + :::info + + You can add new worker pools if you need to customize certain worker nodes to run specialized workloads. As an example, the default worker pool may be configured with the m3.large instance types for general-purpose workloads, and another worker pool with instance type g2.2xlarge can be configured to run GPU workloads. + + ::: -:::info +13. Click on **Next** to continue. -You can add new worker pools if you need to customize certain worker nodes to run specialized workloads. As an example, the default worker pool may be configured with the m3.large instance types for general-purpose workloads, and another worker pool with instance type g2.2xlarge can be configured to run GPU workloads. +14. Specify your preferred **OS Patching Schedule** for EKS-managed machines. -::: +15. Enable any scan options you want Palette to perform, and select a scan schedule. Palette provides support for Kubernetes configuration security, penetration testing, and conformance testing. -12. An optional taint label can be applied to a node pool during the cluster creation. For a an existing cluster, the taint label can be edited, review the [Node Pool](../../cluster-management/node-pool.md) management page to learn more. Toggle the **Taint** button to create a label. +16. Schedule any backups you want Palette to perform. Review [Backup and Restore](../../cluster-management/backup-restore/backup-restore.md) for more information. +17. RBAC configuration is required when you configure custom OIDC. You must map a set of users or groups to a Kubernetes RBAC role. To learn how to map a Kubernetes role to users and groups, refer to [Create Role Bindings](../../cluster-management/cluster-rbac.md/#create-role-bindings). Refer to [Use RBAC with OIDC](../../../integrations/kubernetes.md/#use-rbac-with-oidc) for an example. -13. Enable or disable node pool taints. If tainting is enabled then you need provide values for the following parameters: - - |**Parameter**| **Description**| - |-------------|---------------| - |**Key** |Custom key for the taint.| - |**Value** | Custom value for the taint key.| - | **Effect** | Make the choice of effect from the drop-down menu. Review the effect table bellow for more details. | - - #### Effect Table - - |**Parameter**| **Description**| - |-------------|---------------| - | **NoSchedule**| A pod that cannot tolerate the node taint and should not be scheduled to the node. - | **PreferNoSchedule**| The system will avoid placing a non-tolerant pod to the tainted node but is not guaranteed. - | **NoExecute**| New pods will not be scheduled on the node, and existing pods on the node if any on the node will be evicted they do not tolerate the taint. | +18. Click on the **Validate** button and review the cluster configuration and settings summary. -14. Click on **Next**. - -15. The settings page is where you can configure patching schedule, security scans, backup settings, setup role based access control (RBAC), and enable [Palette Virtual Clusters](../../../devx/palette-virtual-clusters/palette-virtual-clusters.md). Review the settings and make changes if needed. Click on **Validate**. +19. Click **Finish Configuration** to deploy the cluster. + + The cluster details page of the cluster contains the status and details of the deployment. Use this page to track the deployment progress. + + :::info + + Provisioning an AWS EKS clusters can take several minutes. + + ::: -16. Review the settings summary and click on **Finish Configuration** to deploy the cluster. Be aware that provisioning an AWS EKS clusters can take several minutes. -The cluster details page of the cluster contains the status and details of the deployment. Use this page to track the deployment progress. +For information on how to access your cluster using the kubectl CLI, review [Access EKS Cluster](#access-eks-cluster). ## Validate -You can validate your cluster is up and running by reviewing the cluster details page. Navigate to the left **Main Menu** and click on **Clusters**. The **Clusters** page contains a list of all available clusters managed by Palette. Click on the row for the cluster you wish to review its details page. Ensure the **Cluster Status** field contains the value **Running**. +You can validate your cluster is up and in **Running** state. + +1. Log in to [Palette](https://console.spectrocloud.com/). + +2. Navigate to the left **Main Menu** and select **Clusters**. The **Clusters** page displays a list of all available clusters that Palette manages. +3. Click on the cluster you created to view its details page. + +4. Ensure the **Cluster Status** field displays **Running**. + +
+ +## Access EKS Cluster + +You can access your Kubernetes cluster by using the kubectl CLI, which requires authentication. Depending on how you will authenticate to your EKS cluster, you need to install the appropriate plugin. The table below lists the plugin required for two EKS deployment scenarios. + +| **Scenario** | **Plugin** | +| ----------------------------------------- | --------------------------------------- | +| Deploy EKS cluster with custom OIDC | [kubelogin](https://github.com/int128/kubelogin) | +| Deploy EKS cluster access with default AWS authentication | [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) | + + + Select the appropriate tab for your deployment. + + + + + + +To access an EKS cluster with default AWS authentication, you need to do the following: + +- Install [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html). + +- Configure your AWS credentials. The aws-iam-authenticator plugin requires AWS credentials to access the cluster. Refer to the [Configuration and Credential File Settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) reference guide. + + +- Download the kubeconfig file from the cluster details page. Refer to the [Kubectl](../../cluster-management/palette-webctl.md) guide for more information. + + + + + + +To use custom OIDC, you need to do the following: + +- Install [kubelogin](https://github.com/int128/kubelogin). We recommend kubelogin for its ease of authentication. For more information and to learn about other available helper applications, you can visit [OIDC Identity Provider authentication for Amazon EKS](https://aws.amazon.com/blogs/containers/introducing-oidc-identity-provider-authentication-amazon-eks/). + +- Configure OIDC in the Kubernetes pack YAML file. Refer to steps for Amazon EKS in the [Configure Custom OIDC](../../../integrations/kubernetes-generic.md/#configure-custom-oidc) guide. + +- Map a set of users or groups to a Kubernetes RBAC role. To learn how to map a Kubernetes role to users and groups, refer to [Create Role Bindings](../../cluster-management/cluster-rbac.md/#create-role-bindings). Refer to [Use RBAC with OIDC](../../../integrations/kubernetes.md/#use-rbac-with-oidc) for an example. + + +- Download the kubeconfig file from the cluster details page. Refer to the [Kubectl](../../cluster-management/palette-webctl.md) guide for more information. + + + + + + +Once you have the required plugin installed and kubeconfig file downloaded, you can use kubectl to access your cluster. + +:::tip + +For guidance in setting up kubectl, review the [Kubectl](../../cluster-management/palette-webctl.md) guide. + +::: -## EKS Cluster Secrets Encryption +## Resources -Palette encourages using AWS Key Management Service (KMS) to provide envelope encryption of Kubernetes secrets stored in Amazon Elastic Kubernetes Service (EKS) clusters. This encryption is -a defense-in-depth security strategy to protect sensitive data such as passwords, docker registry credentials, and TLS keys stored as [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/). +- [Add AWS Account](add-aws-accounts.md) -### Prerequisites +- [Create an Infrastructure Profile](../../../profiles/cluster-profiles/create-cluster-profiles/create-infrastructure-profile.md) -* KMS key created in the AWS account. -* KMS key is of the type symmetric. -* KMS key policy permits the following actions; encrypt and decrypt. +- [EKS Cluster Encryption](#eks-cluster-secrets-encryption) -### Configure KMS +- [Configure Custom OIDC](../../../integrations/kubernetes.md/#configure-custom-oidc) -The IAM User or IAM role that Palette is using must have the following IAM permissions. +- [Create Role Bindings](../../cluster-management/cluster-rbac.md/#create-role-bindings). -```json hideClipboard -kms:CreateGrant, -kms:ListAliases, -kms:ListKeys, -kms:DescribeKeys -``` -Ensure the IAM role or IAM user can perform the required IAM permissions on the KMS key that will be used for EKS. -You can enable secret encryption during the EKS cluster creation process by toggling the encryption button providing the Amazon Resource Name (ARN) of the encryption key. The encryption option is available on the cluster creation wizard's **Cluster Config** page. +- [Use RBAC with OIDC](../../../integrations/kubernetes.md/#use-rbac-with-oidc) \ No newline at end of file diff --git a/docs/docs-content/clusters/public-cloud/aws/enable-secrets-encryption-kms-key.md b/docs/docs-content/clusters/public-cloud/aws/enable-secrets-encryption-kms-key.md new file mode 100644 index 0000000000..d13f374ca6 --- /dev/null +++ b/docs/docs-content/clusters/public-cloud/aws/enable-secrets-encryption-kms-key.md @@ -0,0 +1,110 @@ +--- +sidebar_label: "Enable Secrets Encryption for EKS Cluster" +title: "Enable Secrets Encryption for EKS Cluster" +description: "Learn how to create an AWS KMS key to encrypt Kubernetes secrets for EKS Clusters." +tags: ["public cloud", "aws", "eks", "kms"] +sidebar_position: 40 +--- + + + +We encourage using AWS Key Management Service (KMS) to provide envelope encryption of Kubernetes secrets stored in Amazon Elastic Kubernetes Service (EKS) clusters. This encryption is +a defense-in-depth security strategy to protect sensitive data such as passwords, docker registry credentials, and Transport Layer Security (TLS) keys stored as [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/). + +Palette provides an **Enable encryption** option, which is only available during the cluster creation process. You can enable secrets encryption when you create an EKS cluster by toggling the **Enable encryption** button and providing the Amazon Resource Name (ARN) of the KMS key. The **Enable encryption** option is available on the cluster creation wizard's **Cluster Config** page for EKS. + +## Prerequisites + +- An AWS account added to Palette. Review [Add AWS Account](add-aws-accounts.md) for guidance. + +- IAM user or role has attached policies listed in [Required IAM Policies](required-iam-policies.md). + +- A **PaletteControllersEKSPolicy** created in AWS and attached to the IAM user or role that Palette is using. To create this policy, refer to [Controllers EKS Policy](required-iam-policies.md#controllers-eks-policy). + +- An AWS KMS key created in the AWS region you intend to deploy cluster to with Palette. + +- Ensure the IAM user or role Palette uses has at a minimum, permissions to list, describe, all KMS keys in the account. The describe and create grant permissions are only required for the KMS key that Palette uses to encrypt Kubernetes secrets. + + - `kms:ListKeys` + - `kms:ListAliases` + - `kms:DescribeKey` + - `kms:CreateGrant` + +
+ + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "Statement1", + "Effect": "Allow", + "Action": [ + "kms:ListKeys", + "kms:ListAliases" + ], + "Resource": ["*"] + }, + { + "Sid": "Statement2", + "Effect": "Allow", + "Action": [ + "kms:DescribeKey", + "kms:CreateGrant" + ], + "Resource": ["*"] + } + ] + } + ``` + + Check out the [Create a KMS Key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-overview.html) guide for more information on key policies. + + +## Create KMS Key + +Use the following steps to configure a KMS key. + +1. Log in to AWS console and navigate to the Key Management Service. + +2. Select the region where your KMS key policy is created. + + :::caution + + Ensure you create the KMS key in the same region that you intend to deploy EKS clusters through Palette. Alternatively, you can create a multi-region KMS key that can be used across different regions. To learn how to create a multi-region key, review Amazon’s [Multi-Region Keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) reference guide. + + ::: + +3. Create a KMS key of type **Symmetric** and with usage **Encrypt and decrypt**. Check out the AWS guide [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) for guidance. + +4. Ensure the IAM user or role that Palette is using has a policy attached with the following required IAM permissions. Replace the account ID and the placeholder `REPLACE_ME` with the name of IAM User. If you are using an IAM role, change the ARN to end with `:role/REPLACE_ME`. + + ```json + { + "Sid": "Allow Palette use of the KMS key", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::123456789:user/REPLACE_ME" + }, + "Action": [ + "kms:Encrypt", + "kms:Decrypt", + "kms:ReEncrypt*", + "kms:GenerateDataKey*", + "kms:DescribeKey" + ], + "Resource": "*" + }, + ``` + + :::info + + If you are using IAM to delegate access to the KMS key, you can continue to do so without modifying the KMS key policy. Ensure the Palette IAM User or role have the proper custom IAM policy attached that grants it access to the KMS key. Refer to the [Using IAM policies with AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html) to learn more about managing KMS keys with IAM policies. + + ::: + +If you need more guidance creating a KMS key, review the AWS [Creating KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-cmk-keystore.html) reference guide. + +## Validate + +You can verify the KMS key is integrated with Palette. When you deploy an EKS cluster on AWS and toggle the **Enable encryption** option at the Cluster Config step in the wizard, the KMS key ARN displays in the **drop-down Menu**. diff --git a/docs/docs-content/clusters/public-cloud/aws/required-iam-policies.md b/docs/docs-content/clusters/public-cloud/aws/required-iam-policies.md index bf627ba61b..293c8edf1a 100644 --- a/docs/docs-content/clusters/public-cloud/aws/required-iam-policies.md +++ b/docs/docs-content/clusters/public-cloud/aws/required-iam-policies.md @@ -4,22 +4,18 @@ title: "Required IAM Policies" description: "A list of required IAM policies that Palette requires." hide_table_of_contents: false tags: ["public cloud", "aws", "iam"] -sidebar_position: 40 +sidebar_position: 50 --- Palette requires proper Amazon Web Services (AWS) permissions to operate and perform actions on your behalf. The following policies include all the permissions needed for cluster provisioning with Palette. -
- -* **PaletteControllersPolicy** +* **PaletteControllerPolicy** * **PaletteControlPlanePolicy** - * **PaletteNodesPolicy** - * **PaletteDeploymentPolicy** Additional IAM policies may be required depending on the use case. For example, AWS Elastic Kubernetes Service (EKS) requires the **PaletteControllersEKSPolicy**. Check out the [Controllers EKS Policy](#controllers-eks-policy) section to review the IAM policy. diff --git a/docs/docs-content/integrations/kubernetes-generic.md b/docs/docs-content/integrations/kubernetes-generic.md index a4afb3b603..66f7d45133 100644 --- a/docs/docs-content/integrations/kubernetes-generic.md +++ b/docs/docs-content/integrations/kubernetes-generic.md @@ -153,7 +153,7 @@ OIDC requires a *RoleBinding* for the users or groups you want to provide cluste The custom method to configure OIDC and apply RBAC for an OIDC provider can be used for all cloud services except Amazon Elastic Kubernetes Service (EKS) and [Azure-AKS](../clusters/public-cloud/azure/aks.md#configure-an-azure-active-directory). - + @@ -194,7 +194,6 @@ Follow these steps to configure a third-party OIDC IDP. You can apply these step oidc-extra-scope: profile,email,openid ``` - @@ -202,7 +201,6 @@ Follow these steps to configure a third-party OIDC IDP. You can apply these step Follow these steps to configure OIDC for managed EKS clusters. -
1. In the Kubernetes pack, uncomment the lines in the `oidcIdentityProvider` parameter section of the Kubernetes pack, and enter your third-party provider details. @@ -230,6 +228,11 @@ clientConfig: 3. Provide third-party OIDC IDP details. + + +4. Refer to the [Access EKS Cluster](../clusters/public-cloud/aws/eks.md#access-eks-cluster) for guidance on how to access an EKS cluster. + + @@ -362,7 +365,7 @@ OIDC requires a *RoleBinding* for the users or groups you want to provide cluste The custom method to configure OIDC and apply RBAC for an OIDC provider can be used for all cloud services except Amazon Elastic Kubernetes Service (EKS) and [Azure-AKS](../clusters/public-cloud/azure/aks.md#configure-an-azure-active-directory). - + @@ -405,6 +408,7 @@ Follow these steps to configure a third-party OIDC IDP. You can apply these step ``` + @@ -438,6 +442,10 @@ clientConfig: 3. Provide third-party OIDC IDP details. + +4. Refer to the [Access EKS Cluster](../clusters/public-cloud/aws/eks.md#access-eks-cluster) for guidance on how to access an EKS cluster. + + @@ -569,7 +577,7 @@ OIDC requires a *RoleBinding* for the users or groups you want to provide cluste The custom method to configure OIDC and apply RBAC for an OIDC provider can be used for all cloud services except Amazon Elastic Kubernetes Service (EKS) and [Azure-AKS](../clusters/public-cloud/azure/aks.md#configure-an-azure-active-directory). - + @@ -618,7 +626,6 @@ Follow these steps to configure a third-party OIDC IDP. You can apply these step Follow these steps to configure OIDC for managed EKS clusters. -
1. In the Kubernetes pack, uncomment the lines in the `oidcIdentityProvider` parameter section of the Kubernetes pack, and enter your third-party provider details. @@ -650,6 +657,9 @@ Follow these steps to configure OIDC for managed EKS clusters. 3. Provide third-party OIDC IDP details. + +4. Refer to the [Access EKS Cluster](../clusters/public-cloud/aws/eks.md#access-eks-cluster) for guidance on how to access an EKS cluster. +