|
| 1 | +--- |
| 2 | +title: Quickstart - Deploy Azure applications to Azure Kubernetes Service clusters using Bicep extensibility Kubernetes provider |
| 3 | +description: Learn how to quickly create a Kubernetes cluster and deploy Azure applications in Azure Kubernetes Service (AKS) using Bicep extensibility Kubernetes provider. |
| 4 | +ms.topic: quickstart |
| 5 | +ms.date: 02/21/2023 |
| 6 | +#Customer intent: As a developer or cluster operator, I want to quickly create an AKS cluster and deploy an application so that I can see how to run applications using the managed Kubernetes service in Azure. |
| 7 | +--- |
| 8 | + |
| 9 | +# Quickstart: Deploy Azure applications to Azure Kubernetes Service (AKS) clusters using Bicep extensibility Kubernetes provider (Preview) |
| 10 | + |
| 11 | +Azure Kubernetes Service (AKS) is a managed Kubernetes service that lets you quickly deploy and manage clusters. In this quickstart, you'll deploy a sample multi-container application with a web front-end and a Redis instance to an AKS cluster. |
| 12 | + |
| 13 | +This quickstart assumes a basic understanding of Kubernetes concepts. For more information, see [Kubernetes core concepts for Azure Kubernetes Service (AKS)][kubernetes-concepts]. |
| 14 | + |
| 15 | +[!INCLUDE [About Bicep](../../../includes/resource-manager-quickstart-bicep-introduction.md)] |
| 16 | + |
| 17 | +> [!IMPORTANT] |
| 18 | +> The Bicep Kubernetes provider is currently in preview. You can enable the feature from the [Bicep configuration file](../../azure-resource-manager/bicep/bicep-config.md#enable-experimental-features) by adding: |
| 19 | +> |
| 20 | +> ```json |
| 21 | +> { |
| 22 | +> "experimentalFeaturesEnabled": { |
| 23 | +> "extensibility": true, |
| 24 | +> } |
| 25 | +> } |
| 26 | +> ``` |
| 27 | +
|
| 28 | +## Prerequisites |
| 29 | +
|
| 30 | +[!INCLUDE [quickstarts-free-trial-note](../../../includes/quickstarts-free-trial-note.md)] |
| 31 | +
|
| 32 | +* To set up your environment for Bicep development, see [Install Bicep tools](../../azure-resource-manager/bicep/install.md). After completing those steps, you'll have [Visual Studio Code](https://code.visualstudio.com/) and the [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep). You also have either the latest [Azure CLI](/cli/azure/) or the latest [Azure PowerShell module](/powershell/azure/new-azureps-module-az). |
| 33 | +
|
| 34 | +* To create an AKS cluster using a Bicep file, you provide an SSH public key. If you need this resource, see [Create an SSH key pair](#create-an-ssh-key-pair). If not, skip to [Review the Bicep file](#review-the-bicep-file). |
| 35 | +
|
| 36 | +* The identity you use to create your cluster has the appropriate minimum permissions. For more information on access and identity for AKS, see [Access and identity options for Azure Kubernetes Service (AKS)](../concepts-identity.md). |
| 37 | +
|
| 38 | +* To deploy a Bicep file, you need write access on the resources you deploy and access to all operations on the `Microsoft.Resources/deployments` resource type. For example, to deploy a virtual machine, you need `Microsoft.Compute/virtualMachines/write and Microsoft.Resources/deployments/*` permissions. For a list of roles and permissions, see [Azure built-in roles](../../role-based-access-control/built-in-roles.md). |
| 39 | +
|
| 40 | +### Create an SSH key pair |
| 41 | +
|
| 42 | +To access AKS nodes, you connect using an SSH key pair (public and private), which you generate using the `ssh-keygen` command. By default, these files are created in the *~/.ssh* directory. Running the `ssh-keygen` command will overwrite any SSH key pair with the same name already existing in the given location. |
| 43 | +
|
| 44 | +1. Go to [https://shell.azure.com](https://shell.azure.com) to open Cloud Shell in your browser. |
| 45 | +
|
| 46 | +1. Run the `ssh-keygen` command. The following example creates an SSH key pair using RSA encryption and a bit length of 4096: |
| 47 | +
|
| 48 | + ```console |
| 49 | + ssh-keygen -t rsa -b 4096 |
| 50 | + ``` |
| 51 | +
|
| 52 | +For more information about creating SSH keys, see [Create and manage SSH keys for authentication in Azure][ssh-keys]. |
| 53 | +
|
| 54 | +## Review the Bicep file |
| 55 | +
|
| 56 | +The Bicep file used to create an AKS cluster is from [Azure Quickstart Templates](https://azure.microsoft.com/resources/templates/aks/). For more AKS samples, see the [AKS quickstart templates][aks-quickstart-templates] site. |
| 57 | +
|
| 58 | +:::code language="bicep" source="~/quickstart-templates/quickstarts/microsoft.kubernetes/aks/main.bicep"::: |
| 59 | +
|
| 60 | +The resource defined in the Bicep file is [**Microsoft.ContainerService/managedClusters**](/azure/templates/microsoft.containerservice/managedclusters?tabs=bicep&pivots=deployment-language-bicep). |
| 61 | +
|
| 62 | +Save a copy of the file as `main.bicep` to your local computer. |
| 63 | +
|
| 64 | +## Add the application definition |
| 65 | +
|
| 66 | +A [Kubernetes manifest file][kubernetes-deployment] defines a cluster's desired state, such as which container images to run. |
| 67 | +
|
| 68 | +In this quickstart, you use a manifest to create all objects needed to run the [Azure Vote application][azure-vote-app]. This manifest includes two [Kubernetes deployments][kubernetes-deployment]: |
| 69 | +
|
| 70 | +* The sample Azure Vote Python applications |
| 71 | +* A Redis instance |
| 72 | +
|
| 73 | +Two [Kubernetes Services][kubernetes-service] are also created: |
| 74 | +
|
| 75 | +* An internal service for the Redis instance |
| 76 | +* An external service to access the Azure Vote application from the internet |
| 77 | +
|
| 78 | +Use the following procedure to add the application definition: |
| 79 | +
|
| 80 | +1. Create a file named `azure-vote.yaml` in the same folder as `main.bicep` with the following YAML definition: |
| 81 | +
|
| 82 | + ```yaml |
| 83 | + apiVersion: apps/v1 |
| 84 | + kind: Deployment |
| 85 | + metadata: |
| 86 | + name: azure-vote-back |
| 87 | + spec: |
| 88 | + replicas: 1 |
| 89 | + selector: |
| 90 | + matchLabels: |
| 91 | + app: azure-vote-back |
| 92 | + template: |
| 93 | + metadata: |
| 94 | + labels: |
| 95 | + app: azure-vote-back |
| 96 | + spec: |
| 97 | + nodeSelector: |
| 98 | + "kubernetes.io/os": linux |
| 99 | + containers: |
| 100 | + - name: azure-vote-back |
| 101 | + image: mcr.microsoft.com/oss/bitnami/redis:6.0.8 |
| 102 | + env: |
| 103 | + - name: ALLOW_EMPTY_PASSWORD |
| 104 | + value: "yes" |
| 105 | + resources: |
| 106 | + requests: |
| 107 | + cpu: 100m |
| 108 | + memory: 128Mi |
| 109 | + limits: |
| 110 | + cpu: 250m |
| 111 | + memory: 256Mi |
| 112 | + ports: |
| 113 | + - containerPort: 6379 |
| 114 | + name: redis |
| 115 | + --- |
| 116 | + apiVersion: v1 |
| 117 | + kind: Service |
| 118 | + metadata: |
| 119 | + name: azure-vote-back |
| 120 | + spec: |
| 121 | + ports: |
| 122 | + - port: 6379 |
| 123 | + selector: |
| 124 | + app: azure-vote-back |
| 125 | + --- |
| 126 | + apiVersion: apps/v1 |
| 127 | + kind: Deployment |
| 128 | + metadata: |
| 129 | + name: azure-vote-front |
| 130 | + spec: |
| 131 | + replicas: 1 |
| 132 | + selector: |
| 133 | + matchLabels: |
| 134 | + app: azure-vote-front |
| 135 | + template: |
| 136 | + metadata: |
| 137 | + labels: |
| 138 | + app: azure-vote-front |
| 139 | + spec: |
| 140 | + nodeSelector: |
| 141 | + "kubernetes.io/os": linux |
| 142 | + containers: |
| 143 | + - name: azure-vote-front |
| 144 | + image: mcr.microsoft.com/azuredocs/azure-vote-front:v1 |
| 145 | + resources: |
| 146 | + requests: |
| 147 | + cpu: 100m |
| 148 | + memory: 128Mi |
| 149 | + limits: |
| 150 | + cpu: 250m |
| 151 | + memory: 256Mi |
| 152 | + ports: |
| 153 | + - containerPort: 80 |
| 154 | + env: |
| 155 | + - name: REDIS |
| 156 | + value: "azure-vote-back" |
| 157 | + --- |
| 158 | + apiVersion: v1 |
| 159 | + kind: Service |
| 160 | + metadata: |
| 161 | + name: azure-vote-front |
| 162 | + spec: |
| 163 | + type: LoadBalancer |
| 164 | + ports: |
| 165 | + - port: 80 |
| 166 | + selector: |
| 167 | + app: azure-vote-front |
| 168 | + ``` |
| 169 | +
|
| 170 | + For a breakdown of YAML manifest files, see [Deployments and YAML manifests](../concepts-clusters-workloads.md#deployments-and-yaml-manifests). |
| 171 | +
|
| 172 | +1. Open `main.bicep` in Visual Studio Code. |
| 173 | +1. Press <kbd>Ctrl+Shift+P</kbd> to open **Command Palette**. |
| 174 | +1. Search for **bicep**, and then select **Bicep: Import Kubernetes Manifest**. |
| 175 | +
|
| 176 | + :::image type="content" source="./media/quick-kubernetes-deploy-bicep-extensibility-kubernetes-provider/bicep-extensibility-kubernetes-provider-import-kubernetes-manifest.png" alt-text="Screenshot of Visual Studio Code import Kubernetes Manifest."::: |
| 177 | +
|
| 178 | +1. Select `azure-vote.yaml` from the prompt. This process creates an `azure-vote.bicep` file in the same folder. |
| 179 | +1. Open `azure-vote.bicep` and add the following line at the end of the file to output the load balancer public IP: |
| 180 | +
|
| 181 | + ```bicep |
| 182 | + output frontendIp string = coreService_azureVoteFront.status.loadBalancer.ingress[0].ip |
| 183 | + ``` |
| 184 | +
|
| 185 | +1. Before the `output` statement in `main.bicep`, add the following Bicep to reference the newly created `azure-vote.bicep` module: |
| 186 | +
|
| 187 | + ```bicep |
| 188 | + module kubernetes './azure-vote.bicep' = { |
| 189 | + name: 'buildbicep-deploy' |
| 190 | + params: { |
| 191 | + kubeConfig: aks.listClusterAdminCredential().kubeconfigs[0].value |
| 192 | + } |
| 193 | + } |
| 194 | + ``` |
| 195 | +
|
| 196 | +1. At the bottom of `main.bicep`, add the following line to output the load balancer public IP: |
| 197 | +
|
| 198 | + ```bicep |
| 199 | + output lbPublicIp string = kubernetes.outputs.frontendIp |
| 200 | + ``` |
| 201 | +
|
| 202 | +1. Save both `main.bicep` and `azure-vote.bicep`. |
| 203 | +
|
| 204 | +## Deploy the Bicep file |
| 205 | +
|
| 206 | +1. Deploy the Bicep file using either Azure CLI or Azure PowerShell. |
| 207 | +
|
| 208 | + # [CLI](#tab/CLI) |
| 209 | +
|
| 210 | + ```azurecli |
| 211 | + az group create --name myResourceGroup --location eastus |
| 212 | + az deployment group create --resource-group myResourceGroup --template-file main.bicep --parameters clusterName=<cluster-name> dnsPrefix=<dns-previs> linuxAdminUsername=<linux-admin-username> sshRSAPublicKey='<ssh-key>' |
| 213 | + ``` |
| 214 | +
|
| 215 | + # [PowerShell](#tab/PowerShell) |
| 216 | +
|
| 217 | + ```azurepowershell |
| 218 | + New-AzResourceGroup -Name myResourceGroup -Location eastus |
| 219 | + New-AzResourceGroupDeployment -ResourceGroupName myResourceGroup -TemplateFile ./main.bicep -clusterName=<cluster-name> -dnsPrefix=<dns-prefix> -linuxAdminUsername=<linux-admin-username> -sshRSAPublicKey="<ssh-key>" |
| 220 | + ``` |
| 221 | +
|
| 222 | + --- |
| 223 | +
|
| 224 | + Provide the following values in the commands: |
| 225 | +
|
| 226 | + * **Cluster name**: Enter a unique name for the AKS cluster, such as *myAKSCluster*. |
| 227 | + * **DNS prefix**: Enter a unique DNS prefix for your cluster, such as *myakscluster*. |
| 228 | + * **Linux Admin Username**: Enter a username to connect using SSH, such as *azureuser*. |
| 229 | + * **SSH RSA Public Key**: Copy and paste the *public* part of your SSH key pair (by default, the contents of *~/.ssh/id_rsa.pub*). |
| 230 | +
|
| 231 | + It takes a few minutes to create the AKS cluster. Wait for the cluster to be successfully deployed before you move on to the next step. |
| 232 | +
|
| 233 | +2. From the deployment output, look for the `outputs` section. For example: |
| 234 | +
|
| 235 | + ```json |
| 236 | + "outputs": { |
| 237 | + "controlPlaneFQDN": { |
| 238 | + "type": "String", |
| 239 | + "value": "myaks0201-d34ae860.hcp.eastus.azmk8s.io" |
| 240 | + }, |
| 241 | + "lbPublicIp": { |
| 242 | + "type": "String", |
| 243 | + "value": "52.179.23.131" |
| 244 | + } |
| 245 | + }, |
| 246 | + ``` |
| 247 | +
|
| 248 | +3. Take note of the value of lbPublicIp. |
| 249 | +
|
| 250 | +## Validate the Bicep deployment |
| 251 | +
|
| 252 | +To see the Azure Vote app in action, open a web browser to the external IP address of your service. |
| 253 | +
|
| 254 | +:::image type="content" source="media/quick-kubernetes-deploy-rm-bicep/azure-voting-application.png" alt-text="Screenshot of browsing to Azure Vote sample application."::: |
| 255 | +
|
| 256 | +## Clean up resources |
| 257 | +
|
| 258 | +### [Azure CLI](#tab/azure-cli) |
| 259 | +
|
| 260 | +To avoid Azure charges, if you don't plan on going through the tutorials that follow, clean up your unnecessary resources. Use the [`az group delete`][az-group-delete] command to remove the resource group, container service, and all related resources. |
| 261 | +
|
| 262 | +```azurecli-interactive |
| 263 | +az group delete --name myResourceGroup --yes --no-wait |
| 264 | +``` |
| 265 | +
|
| 266 | +### [Azure PowerShell](#tab/azure-powershell) |
| 267 | + |
| 268 | +To avoid Azure charges, if you don't plan on going through the tutorials that follow, clean up your unnecessary resources. Use the [`Remove-AzResourceGroup`][remove-azresourcegroup] cmdlet to remove the resource group, container service, and all related resources. |
| 269 | + |
| 270 | +```azurepowershell-interactive |
| 271 | +Remove-AzResourceGroup -Name myResourceGroup |
| 272 | +``` |
| 273 | + |
| 274 | +--- |
| 275 | + |
| 276 | +> [!NOTE] |
| 277 | +> In this quickstart, the AKS cluster was created with a system-assigned managed identity (the default identity option). This identity is managed by the platform and doesn't require removal. |
| 278 | +
|
| 279 | +## Next steps |
| 280 | + |
| 281 | +In this quickstart, you deployed a Kubernetes cluster and then deployed a sample multi-container application to it. |
| 282 | + |
| 283 | +To learn more about AKS, and walk through a complete code to deployment example, continue to the Kubernetes cluster tutorial: |
| 284 | + |
| 285 | +> [!div class="nextstepaction"] |
| 286 | +> [Kubernetes on Azure tutorial: Prepare an application][aks-tutorial] |
| 287 | +
|
| 288 | +<!-- LINKS - external --> |
| 289 | +[azure-vote-app]: https://github.com/Azure-Samples/azure-voting-app-redis.git |
| 290 | +[kubectl]: https://kubernetes.io/docs/user-guide/kubectl/ |
| 291 | +[kubectl-apply]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply |
| 292 | +[kubectl-get]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get |
| 293 | +[azure-dev-spaces]: /previous-versions/azure/dev-spaces/ |
| 294 | +[aks-quickstart-templates]: https://azure.microsoft.com/resources/templates/?term=Azure+Kubernetes+Service |
| 295 | + |
| 296 | +<!-- LINKS - internal --> |
| 297 | +[kubernetes-concepts]: ../concepts-clusters-workloads.md |
| 298 | +[aks-monitor]: ../../azure-monitor/containers/container-insights-onboard.md |
| 299 | +[aks-tutorial]: ../tutorial-kubernetes-prepare-app.md |
| 300 | +[az-aks-browse]: /cli/azure/aks#az_aks_browse |
| 301 | +[az-aks-create]: /cli/azure/aks#az_aks_create |
| 302 | +[az-aks-get-credentials]: /cli/azure/aks#az_aks_get_credentials |
| 303 | +[import-azakscredential]: /powershell/module/az.aks/import-azakscredential |
| 304 | +[az-aks-install-cli]: /cli/azure/aks#az_aks_install_cli |
| 305 | +[install-azakskubectl]: /powershell/module/az.aks/install-azaksclitool |
| 306 | +[az-group-create]: /cli/azure/group#az_group_create |
| 307 | +[az-group-delete]: /cli/azure/group#az_group_delete |
| 308 | +[remove-azresourcegroup]: /powershell/module/az.resources/remove-azresourcegroup |
| 309 | +[azure-cli-install]: /cli/azure/install-azure-cli |
| 310 | +[install-azure-powershell]: /powershell/azure/install-az-ps |
| 311 | +[connect-azaccount]: /powershell/module/az.accounts/Connect-AzAccount |
| 312 | +[sp-delete]: ../kubernetes-service-principal.md#additional-considerations |
| 313 | +[azure-portal]: https://portal.azure.com |
| 314 | +[kubernetes-deployment]: ../concepts-clusters-workloads.md#deployments-and-yaml-manifests |
| 315 | +[kubernetes-service]: ../concepts-network.md#services |
| 316 | +[ssh-keys]: ../../virtual-machines/linux/create-ssh-keys-detailed.md |
| 317 | +[az-ad-sp-create-for-rbac]: /cli/azure/ad/sp#az_ad_sp_create_for_rbac |
0 commit comments