Edit

Quickstart: Deploy Azure applications to Azure Kubernetes Service (AKS) clusters using Bicep extensibility Kubernetes provider (Preview)

  • Article

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.

This quickstart assumes a basic understanding of Kubernetes concepts. For more information, see Kubernetes core concepts for Azure Kubernetes Service (AKS).

Bicep is a domain-specific language (DSL) that uses declarative syntax to deploy Azure resources. It provides concise syntax, reliable type safety, and support for code reuse. Bicep offers the best authoring experience for your infrastructure-as-code solutions in Azure.

Important

The Bicep Kubernetes provider is currently in preview. You can enable the feature from the Bicep configuration file by adding:

{
 "experimentalFeaturesEnabled": {
   "extensibility": true,
 }
}

Prerequisites

If you don't have an Azure subscription, create an Azure free account before you begin.

Create an SSH key pair

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.

  1. Go to https://shell.azure.com to open Cloud Shell in your browser.

  2. Run the ssh-keygen command. The following example creates an SSH key pair using RSA encryption and a bit length of 4096:

    ssh-keygen -t rsa -b 4096

For more information about creating SSH keys, see Create and manage SSH keys for authentication in Azure.

Review the Bicep file

The Bicep file used to create an AKS cluster is from Azure Quickstart Templates. For more AKS samples, see the AKS quickstart templates site.

@description('The name of the Managed Cluster resource.')
param clusterName string = 'aks101cluster'

@description('The location of the Managed Cluster resource.')
param location string = resourceGroup().location

@description('Optional DNS prefix to use with hosted Kubernetes API server FQDN.')
param dnsPrefix string

@description('Disk size (in GB) to provision for each of the agent pool nodes. This value ranges from 0 to 1023. Specifying 0 will apply the default disk size for that agentVMSize.')
@minValue(0)
@maxValue(1023)
param osDiskSizeGB int = 0

@description('The number of nodes for the cluster.')
@minValue(1)
@maxValue(50)
param agentCount int = 3

@description('The size of the Virtual Machine.')
param agentVMSize string = 'standard_d2s_v3'

@description('User name for the Linux Virtual Machines.')
param linuxAdminUsername string

@description('Configure all linux machines with the SSH RSA public key string. Your key should include three parts, for example \'ssh-rsa AAAAB...snip...UcyupgH azureuser@linuxvm\'')
param sshRSAPublicKey string

resource aks 'Microsoft.ContainerService/managedClusters@2022-05-02-preview' = {
  name: clusterName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    dnsPrefix: dnsPrefix
    agentPoolProfiles: [
      {
        name: 'agentpool'
        osDiskSizeGB: osDiskSizeGB
        count: agentCount
        vmSize: agentVMSize
        osType: 'Linux'
        mode: 'System'
      }
    ]
    linuxProfile: {
      adminUsername: linuxAdminUsername
      ssh: {
        publicKeys: [
          {
            keyData: sshRSAPublicKey
          }
        ]
      }
    }
  }
}

output controlPlaneFQDN string = aks.properties.fqdn

The resource defined in the Bicep file is Microsoft.ContainerService/managedClusters.

Save a copy of the file as main.bicep to your local computer.

Add the application definition

A Kubernetes manifest file defines a cluster's desired state, such as which container images to run.

In this quickstart, you use a manifest to create all objects needed to run the Azure Vote application. This manifest includes two Kubernetes deployments:

  • The sample Azure Vote Python applications
  • A Redis instance

Two Kubernetes Services are also created:

  • An internal service for the Redis instance
  • An external service to access the Azure Vote application from the internet

Use the following procedure to add the application definition:

  1. Create a file named azure-vote.yaml in the same folder as main.bicep with the following YAML definition:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: azure-vote-back
spec:
  replicas: 1
  selector:
    matchLabels:
      app: azure-vote-back
  template:
    metadata:
      labels:
        app: azure-vote-back
    spec:
      nodeSelector:
        "kubernetes.io/os": linux
      containers:
      - name: azure-vote-back
        image: mcr.microsoft.com/oss/bitnami/redis:6.0.8
        env:
        - name: ALLOW_EMPTY_PASSWORD
          value: "yes"
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 250m
            memory: 256Mi
        ports:
        - containerPort: 6379
          name: redis
---
apiVersion: v1
kind: Service
metadata:
  name: azure-vote-back
spec:
  ports:
  - port: 6379
  selector:
    app: azure-vote-back
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: azure-vote-front
spec:
  replicas: 1
  selector:
    matchLabels:
      app: azure-vote-front
  template:
    metadata:
      labels:
        app: azure-vote-front
    spec:
      nodeSelector:
        "kubernetes.io/os": linux
      containers:
      - name: azure-vote-front
        image: mcr.microsoft.com/azuredocs/azure-vote-front:v1
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 250m
            memory: 256Mi
        ports:
        - containerPort: 80
        env:
        - name: REDIS
          value: "azure-vote-back"
---
apiVersion: v1
kind: Service
metadata:
  name: azure-vote-front
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: azure-vote-front

    For a breakdown of YAML manifest files, see Deployments and YAML manifests.

  2. Open main.bicep in Visual Studio Code.

  3. Press Ctrl+Shift+P to open Command Palette.

  4. Search for bicep, and then select Bicep: Import Kubernetes Manifest.

    Screenshot of Visual Studio Code import Kubernetes Manifest.

  5. Select azure-vote.yaml from the prompt. This process creates an azure-vote.bicep file in the same folder.

  6. Open azure-vote.bicep and add the following line at the end of the file to output the load balancer public IP:

    output frontendIp string = coreService_azureVoteFront.status.loadBalancer.ingress[0].ip

  7. Before the output statement in main.bicep, add the following Bicep to reference the newly created azure-vote.bicep module:

    module kubernetes './azure-vote.bicep' = {
  name: 'buildbicep-deploy'
  params: {
    kubeConfig: aks.listClusterAdminCredential().kubeconfigs[0].value
  }
}

  8. At the bottom of main.bicep, add the following line to output the load balancer public IP:

    output lbPublicIp string = kubernetes.outputs.frontendIp

  9. Save both main.bicep and azure-vote.bicep.

Deploy the Bicep file

  1. Deploy the Bicep file using either Azure CLI or Azure PowerShell.

    az group create --name myResourceGroup --location eastus
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>'

    Provide the following values in the commands:

    • Cluster name: Enter a unique name for the AKS cluster, such as myAKSCluster.
    • DNS prefix: Enter a unique DNS prefix for your cluster, such as myakscluster.
    • Linux Admin Username: Enter a username to connect using SSH, such as azureuser.
    • SSH RSA Public Key: Copy and paste the public part of your SSH key pair (by default, the contents of ~/.ssh/id_rsa.pub).

    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.

  2. From the deployment output, look for the outputs section. For example:

    "outputs": {
  "controlPlaneFQDN": {
    "type": "String",
    "value": "myaks0201-d34ae860.hcp.eastus.azmk8s.io"
  },
  "lbPublicIp": {
    "type": "String",
    "value": "52.179.23.131"
  }
},

  3. Take note of the value of lbPublicIp.

Validate the Bicep deployment

To see the Azure Vote app in action, open a web browser to the external IP address of your service.

Screenshot of browsing to Azure Vote sample application.

Clean up resources

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 command to remove the resource group, container service, and all related resources.

az group delete --name myResourceGroup --yes --no-wait

Note

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.

Next steps

In this quickstart, you deployed a Kubernetes cluster and then deployed a sample multi-container application to it.

To learn more about AKS, and walk through a complete code to deployment example, continue to the Kubernetes cluster tutorial:

Kubernetes on Azure tutorial: Prepare an application