Merge pull request #256212 from khdownie/kendownie-acstor-akscli

v-dirichards · web-flow · commit e8c4cf368bd9 · 2023-11-06T10:32:15.000-06:00
Updated Quickstart with AKS CLI
diff --git a/articles/storage/container-storage/container-storage-aks-quickstart.md b/articles/storage/container-storage/container-storage-aks-quickstart.md
@@ -1,35 +1,161 @@
 ---
 title: Quickstart for using Azure Container Storage Preview with Azure Kubernetes Service (AKS)
-description: Learn how to install Azure Container Storage Preview on an Azure Kubernetes Service cluster using an installation script.
+description: Create a Linux-based Azure Kubernetes Service (AKS) cluster, install Azure Container Storage, and create a storage pool.
 author: khdownie
 ms.service: azure-container-storage
 ms.topic: quickstart
-ms.date: 09/20/2023
+ms.date: 11/03/2023
 ms.author: kendownie
+ms.custom: devx-track-azurecli
 ---
 
 # Quickstart: Use Azure Container Storage Preview with Azure Kubernetes Service
-[Azure Container Storage](container-storage-introduction.md) is a cloud-based volume management, deployment, and orchestration service built natively for containers. This Quickstart shows you how to install Azure Container Storage Preview on an [Azure Kubernetes Service (AKS)](../../aks/intro-kubernetes.md) cluster using a provided installation script.
+
+[Azure Container Storage](container-storage-introduction.md) is a cloud-based volume management, deployment, and orchestration service built natively for containers. This Quickstart shows you how to create a Linux-based [Azure Kubernetes Service (AKS)](../../aks/intro-kubernetes.md) cluster, install Azure Container Storage, and create a storage pool using Azure CLI.
 
 ## Prerequisites
 
 [!INCLUDE [container-storage-prerequisites](../../../includes/container-storage-prerequisites.md)]
 
-- You'll need an AKS cluster with an appropriate [virtual machine type](install-container-storage-aks.md#vm-types). If you don't already have an AKS cluster, follow [these instructions](install-container-storage-aks.md#getting-started) to create one.
+> [!IMPORTANT]
+> This Quickstart will work for most use cases. An exception is if you plan to use Azure Elastic SAN Preview as backing storage for your storage pool and you don't have owner-level access to the Azure subscription. If both these statements apply to you, use the [manual installation steps](install-container-storage-aks.md) instead. Alternatively, you can complete this Quickstart with the understanding that a storage pool won't be automatically created, and then [create an Elastic SAN storage pool manually](use-container-storage-with-elastic-san.md).
+
+## Getting started
+
+- Take note of your Azure subscription ID. We recommend using a subscription on which you have an [Owner](../../role-based-access-control/built-in-roles.md#owner) role.
+
+- [Launch Azure Cloud Shell](https://shell.azure.com), or if you're using a local installation, sign in to the Azure CLI by using the [az login](/cli/azure/reference-index#az-login) command.
+
+- If you're using Azure Cloud Shell, you might be prompted to mount storage. Select the Azure subscription where you want to create the storage account and select **Create**.
+
+## Install the required extensions
+
+Upgrade to the latest version of the `aks-preview` cli extension by running the following command.
+
+```azurecli-interactive
+az extension add --upgrade --name aks-preview
+```
+
+Add or upgrade to the latest version of k8s-extension by running the following command.
+
+```azurecli-interactive
+az extension add --upgrade --name k8s-extension
+```
+
+## Set subscription context
+
+Set your Azure subscription context using the `az account set` command. You can view the subscription IDs for all the subscriptions you have access to by running the `az account list --output table` command. Remember to replace `<subscription-id>` with your subscription ID.
+
+```azurecli-interactive
+az account set --subscription <subscription-id>
+```
+
+## Register resource providers
+
+The `Microsoft.ContainerService` and `Microsoft.KubernetesConfiguration` resource providers must be registered on your Azure subscription. To register these providers, run the following commands:
+
+```azurecli-interactive
+az provider register --namespace Microsoft.ContainerService --wait 
+az provider register --namespace Microsoft.KubernetesConfiguration --wait 
+```
+
+## Create a resource group
+
+An Azure resource group is a logical group that holds your Azure resources that you want to manage as a group. If you already have a resource group you want to use, you can skip this section.
+
+When you create a resource group, you're prompted to specify a location. This location is:
+
+* The storage location of your resource group metadata.
+* Where your resources will run in Azure if you don't specify another region during resource creation.
+
+Create a resource group using the `az group create` command. Replace `<resource-group-name>` with the name of the resource group you want to create, and replace `<location>` with an Azure region such as *eastus*, *westus2*, *westus3*, or *westeurope*. See this [list of Azure regions](container-storage-introduction.md#regional-availability) where Azure Container Storage is available.
+
+```azurecli-interactive
+az group create --name <resource-group-name> --location <location>
+```
+
+If the resource group was created successfully, you'll see output similar to this:
+
+```output
+{
+  "id": "/subscriptions/<guid>/resourceGroups/myContainerStorageRG",
+  "location": "eastus",
+  "managedBy": null,
+  "name": "myContainerStorageRG",
+  "properties": {
+    "provisioningState": "Succeeded"
+  },
+  "tags": null
+}
+```
+
+## Choose a data storage option for your storage pool
+
+Before deploying Azure Container Storage, you'll need to decide which back-end storage option you want to use to create your storage pool and persistent volumes. Three options are currently available:
+
+- **Azure Elastic SAN Preview**: Azure Elastic SAN preview is a good fit for general purpose databases, streaming and messaging services, CI/CD environments, and other tier 1/tier 2 workloads. Storage is provisioned on demand per created volume and volume snapshot. Multiple clusters can access a single SAN concurrently, however persistent volumes can only be attached by one consumer at a time.
+
+- **Azure Disks**: Azure Disks are a good fit for databases such as MySQL, MongoDB, and PostgreSQL. Storage is provisioned per target container storage pool size and maximum volume size.
+
+- **Ephemeral Disk**: This option uses local NVMe drives on the AKS cluster nodes and is extremely latency sensitive (low sub-ms latency), so it's best for applications with no data durability requirement or with built-in data replication support such as Cassandra. AKS discovers the available ephemeral storage on AKS nodes and acquires the drives for volume deployment. 
+
+You'll specify the storage pool type when you install Azure Container Storage.
+
+## Choose a VM type for your cluster
+
+If you intend to use Azure Elastic SAN Preview or Azure Disks as backing storage, then you should choose a [general purpose VM type](../../virtual-machines/sizes-general.md) such as **standard_d4s_v5** for the cluster nodes. If you intend to use Ephemeral Disk, choose a [storage optimized VM type](../../virtual-machines/sizes-storage.md) with NVMe drives such as **standard_l8s_v3**. In order to use Ephemeral Disk, the VMs must have NVMe drives. You'll specify the VM type when you create the cluster in the next section.
 
 > [!IMPORTANT]
-> If you created your AKS cluster using the Azure portal, it will likely have two node pools: a user node pool and a system/agent node pool. Before you can install Azure Container Storage, you must label the user node pool. In this article, this is done automatically by passing the user node pool name to the script as a parameter. However, if your cluster consists of only a system node pool, which is often the case with test/dev clusters, you'll need to first [add a new user node pool](../../aks/create-node-pools.md#add-a-node-pool) before running the script. This is because when you create an AKS cluster using the Azure portal, a taint `CriticalAddOnsOnly` gets added to the agent/system nodepool, which blocks installation of Azure Container Storage on the system node pool. This taint isn't added when an AKS cluster is created using Azure CLI. 
+> You must choose a VM type that supports [Azure premium storage](../../virtual-machines/premium-storage-performance.md). Each VM should have a minimum of four virtual CPUs (vCPUs). Azure Container Storage will consume one core for I/O processing on every VM the extension is deployed to.
 
-## Install Azure Container Storage
+## Create a new AKS cluster and install Azure Container Storage
 
-[!INCLUDE [container-storage-script-install](../../../includes/container-storage-script-install.md)]
+If you already have an AKS cluster deployed, skip this section and go to [Install Azure Container Storage on an existing AKS cluster](#install-azure-container-storage-on-an-existing-aks-cluster).
+
+Run the following command to create a new AKS cluster, install Azure Container Storage, and create a storage pool. Replace `<cluster-name>` and `<resource-group-name>` with your own values, and specify which VM type you want to use. You'll need a node pool of at least three Linux VMs. Replace `<storage-pool-type>` with `azureDisk`, `ephemeraldisk`, or `elasticSan`.
+
+Optional storage pool parameters:
+
+| **Parameter**      | **Default** |
+|----------------|-------------|
+| --storage-pool-name | mypool-<random 7 char lowercase> |
+| --storage-pool-size | 512Gi (1Ti for Elastic SAN) |
+| --storage-pool-sku | Premium_LRS |
+| --storage-pool-option | NVMe |
+
+```azurecli-interactive
+az aks create -n <cluster-name> -g <resource-group-name> --node-vm-size Standard_D4s_v3 --node-count 3 --enable-azure-container-storage <storage-pool-type>
+```
+
+The deployment will take 10-15 minutes to complete.
+
+## Install Azure Container Storage on an existing AKS cluster
+
+If you already have an AKS cluster that meets the [VM requirements](#choose-a-vm-type-for-your-cluster), run the following command to install Azure Container Storage on the cluster and create a storage pool. Replace `<cluster-name>` and `<resource-group-name>` with your own values. Replace `<storage-pool-type>` with `azureDisk`, `ephemeraldisk`, or `elasticSan`.
+
+Running this command will enable Azure Container Storage on a node pool named `nodepool1`, which is the default node pool name. If you want to install it on other node pools, see [Install Azure Container Storage on specific node pools](#install-azure-container-storage-on-specific-node-pools).
+
+> [!IMPORTANT]
+> **If you created your AKS cluster using the Azure portal:** The cluster will likely have a user node pool and a system/agent node pool. However, if your cluster consists of only a system node pool, which is the case with test/dev clusters created with the Azure portal, you'll need to first [add a new user node pool](../../aks/create-node-pools.md#add-a-node-pool) and then label it. This is because when you create an AKS cluster using the Azure portal, a taint `CriticalAddOnsOnly` is added to the system/agent nodepool, which blocks installation of Azure Container Storage on the system node pool. This taint isn't added when an AKS cluster is created using Azure CLI.
 
-## Choose a data storage option
+```azurecli-interactive
+az aks update -n <cluster-name> -g <resource-group-name> --enable-azure-container-storage <storage-pool-type>
+```
 
-Next you'll need to choose a back-end storage option to create your storage pool. Choose one of the following three options and follow the link to create a storage pool and persistent volume claim.
+The deployment will take 10-15 minutes to complete.
 
-- **Azure Elastic SAN Preview**: Azure Elastic SAN preview is a good fit for general purpose databases, streaming and messaging services, CD/CI environments, and other tier 1/tier 2 workloads. Storage is provisioned on demand per created volume and volume snapshot. Multiple clusters can access a single SAN concurrently, however persistent volumes can only be attached by one consumer at a time. [Create a storage pool using Azure Elastic SAN Preview](use-container-storage-with-elastic-san.md#create-a-storage-pool).
+### Install Azure Container Storage on specific node pools
 
-- **Azure Disks**: Azure Disks are a good fit for databases such as MySQL, MongoDB, and PostgreSQL. Storage is provisioned per target container storage pool size and maximum volume size. [Create a storage pool using Azure Disks](use-container-storage-with-managed-disks.md#create-a-storage-pool).
+If you want to install Azure Container Storage on specific node pools, follow these instructions. The node pools must contain at least three Linux VMs each.
 
-- **Ephemeral Disk**: This option uses local NVMe drives on the AKS nodes and is extremely latency sensitive (low sub-ms latency), so it's best for applications with no data durability requirement or with built-in data replication support such as Cassandra. AKS discovers the available ephemeral storage on AKS nodes and acquires the drives for volume deployment. [Create a storage pool using Ephemeral Disk](use-container-storage-with-local-disk.md#create-a-storage-pool).
+1. Run the following command to view the list of available node pools. Replace `<resource-group-name>` and `<cluster-name>` with your own values.
+   
+   ```azurecli-interactive
+   az aks nodepool list --resource-group <resource-group-name> --cluster-name <cluster-name>
+   ```
+   
+2. Run the following command to install Azure Container Storage on specific node pools. Replace `<cluster-name>` and `<resource-group-name>` with your own values. Replace `<storage-pool-type>` with `azureDisk`, `ephemeraldisk`, or `elasticSan`.
+   
+   ```azurecli-interactive
+   az aks update -n <cluster-name> -g <resource-group-name> --enable-azure-container-storage <storage-pool-type> --azure-container-storage-nodepools <comma separated values of nodepool names> 
+   ```
diff --git a/articles/storage/container-storage/install-container-storage-aks.md b/articles/storage/container-storage/install-container-storage-aks.md
@@ -4,20 +4,21 @@ description: Learn how to install Azure Container Storage Preview for use with A
 author: khdownie
 ms.service: azure-container-storage
 ms.topic: how-to
-ms.date: 09/26/2023
+ms.date: 10/27/2023
 ms.author: kendownie
 ms.custom: devx-track-azurecli
 ---
 
 # Install Azure Container Storage Preview for use with Azure Kubernetes Service
-[Azure Container Storage](container-storage-introduction.md) is a cloud-based volume management, deployment, and orchestration service built natively for containers. This article shows you how to create an [Azure Kubernetes Service (AKS)](../../aks/intro-kubernetes.md) cluster and install Azure Container Storage Preview on the cluster.
+
+[Azure Container Storage](container-storage-introduction.md) is a cloud-based volume management, deployment, and orchestration service built natively for containers. This article shows you how to create an [Azure Kubernetes Service (AKS)](../../aks/intro-kubernetes.md) cluster, label the node pool, and install Azure Container Storage Preview on the cluster. Alternatively, you can install Azure Container Storage Preview [using a QuickStart](container-storage-aks-quickstart.md) instead of following the manual steps in this article.
 
 ## Prerequisites
 
 [!INCLUDE [container-storage-prerequisites](../../../includes/container-storage-prerequisites.md)]
 
 > [!NOTE]
-> If you already have an AKS cluster deployed, you can proceed to [Connect to the cluster](#connect-to-the-cluster). Alternatively, you can install Azure Container Storage Preview [using an automated installation script](container-storage-aks-quickstart.md) instead of following the manual steps outlined in this article.
+> If you already have an AKS cluster deployed, proceed to [Connect to the cluster](#connect-to-the-cluster).
 
 ## Getting started
 
@@ -59,7 +60,7 @@ az group create --name <resource-group-name> --location <location>
 
 If the resource group was created successfully, you'll see output similar to this:
 
-```json
+```output
 {
   "id": "/subscriptions/<guid>/resourceGroups/myContainerStorageRG",
   "location": "eastus",
@@ -112,7 +113,7 @@ The deployment will take a few minutes to complete.
 
 ## Connect to the cluster
 
-To connect to the cluster, use the Kubernetes command-line client, `kubectl`.
+To connect to the cluster, use the Kubernetes command-line client, `kubectl`. It's already installed if you're using Azure Cloud Shell, or you can install it locally by running the `az aks install-cli` command.
 
 1. Configure `kubectl` to connect to your cluster using the `az aks get-credentials` command. The following command:
 
diff --git a/includes/container-storage-prerequisites.md b/includes/container-storage-prerequisites.md
@@ -2,14 +2,12 @@
 author: khdownie
 ms.service: azure-container-storage
 ms.topic: include
-ms.date: 09/07/2023
+ms.date: 11/06/2023
 ms.author: kendownie
 ---
 
 - If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
 
-- This article requires version 2.0.64 or later of the Azure CLI. See [How to install the Azure CLI](/cli/azure/install-azure-cli). If you're using the Bash environment in Azure Cloud Shell, the latest version is already installed. If you plan to run the commands locally instead of in Azure Cloud Shell, be sure to run them with administrative privileges. For more information, see [Quickstart for Bash in Azure Cloud Shell](../articles/cloud-shell/quickstart.md).
-
-- You'll need the Kubernetes command-line client, `kubectl`. It's already installed if you're using Azure Cloud Shell, or you can install it locally by running the `az aks install-cli` command.
+- This article requires the latest version (2.35.0 or later) of the Azure CLI. See [How to install the Azure CLI](/cli/azure/install-azure-cli). If you're using the Bash environment in Azure Cloud Shell, the latest version is already installed. If you plan to run the commands locally instead of in Azure Cloud Shell, be sure to run them with administrative privileges. For more information, see [Quickstart for Bash in Azure Cloud Shell](../articles/cloud-shell/quickstart.md).
 
 - Optional: We'd like input on how you plan to use Azure Container Storage. Please complete this [short survey](https://aka.ms/AzureContainerStoragePreviewSignUp).
