Virtual Event
Join us for the next HashiConf Digital October 12-15, 2020 Register for Free

Manage Kubernetes with Terraform

Provision an AKS Cluster (Azure)

The Azure Kubernetes Service (AKS) is a fully managed Kubernetes service for deploying, managing, and scaling containerized applications on Azure.

In this guide, you will deploy a 2 node AKS cluster on your default VPC using Terraform then access its Kubernetes dashboard.

»Why deploy with Terraform?

While you could use the built-in Azure provisioning processes (UI, CLI) for AKS clusters, Terraform provides you with several benefits:

  • Unified Workflow - If you are already deploying infrastructure to Azure with Terraform, your AKS cluster can fit into that workflow. You can also deploy applications into your AKS cluster using Terraform.

  • Full Lifecycle Management - Terraform doesn't only create resources, it updates, and deletes tracked resources without requiring you to inspect the API to identify those resources.

  • Graph of Relationships - Terraform understands dependency relationships between resources. For example, an Azure Kubernetes cluster needs to be associated with a resource group, Terraform won't attempt to create the cluster if the resource group failed to create.


The guide assumes some basic familiarity with Kubernetes and kubectl but does not assume any pre-existing deployment.

It also assumes that you are familiar with the usual Terraform plan/apply workflow. If you're new to Terraform itself, refer first to the Getting Started guide.

For this guide, you will need

In order for Terraform to run operations on your behalf, you must install and configure the Azure CLI tool. To install the Azure CLI, follow these instructions or choose a package manager based on your operating system.

You can also use the package manager homebrew to install the Azure CLI.

$ brew install azure-cli

After you've installed the Azure CLI, login into Azure by running:

$ az login

»Set up and initialize your Terraform workspace

In your terminal, clone the following repository. It contains the example configuration used in this guide.

$ git clone

You can explore this repository by changing directories or navigating in your UI.

$ cd learn-terraform-provision-aks-cluster

In here, you will find three files used to provision the AKS cluster.

  1. provisions a resource group and an AKS cluster. The agent_pool_profile defines the types of VMs used to create the cluster.

    resource "azurerm_kubernetes_cluster" "default" {
      name                = "${}-aks"
      location            = azurerm_resource_group.default.location
      resource_group_name =
      dns_prefix          = "${}-k8s"
      agent_pool_profile {
        name            = "default"
        count           = 2
        vm_size         = "Standard_D2_v2"
        os_type         = "Linux"
        os_disk_size_gb = 30
      service_principal {
        client_id     = var.appId
        client_secret = var.password
      role_based_access_control {
        enabled = true
      tags = {
        environment = "Demo"
  2. terraform.tfvars is template for the appId and password variables to authenticate to Azure

  3. sets the Terraform version to at least 0.12

»Create an Active Directory service principal account

There are many ways to authenticate to the Azure provider. In this guide, you will use an Active Directory service principal account. You can learn how to authenticate using a different method here.

First, you need to create an Active Directory service principal account using the Azure CLI. You should see something like the following.

$ az ad sp create-for-rbac --skip-assignment
  "appId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "displayName": "azure-cli-2019-04-11-00-46-05",
  "name": "http://azure-cli-2019-04-11-00-46-05",
  "password": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "tenant": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"

»Update your terraform.tfvars file

Replace the values in your terraform.tfvars file with your appId and password. Terraform will use these values to authenticate to Azure before provisioning your resources. Your terraform.tfvars file should look like the following.

# terraform.tfvars
appId    = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
password = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"

»Initialize Terraform

After you have saved your customized variables file, initialize your Terraform workspace, which will download the provider and initialize it with the values provided in your terraform.tfvars file.

$ terraform init
Initializing provider plugins...
- Checking for available provider plugins on
- Downloading plugin for provider "azurerm" (1.27.0)...

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

»Provision the AKS cluster

In your initialized directory, run terraform apply and review the planned actions. Your terminal output should indicate the plan is running and what resources will be created.

$ terraform apply
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

## output truncated ...

Plan: 3 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

You can see this terraform apply will provision an Azure resource group and an AKS cluster. If you're comfortable with this, confirm the run with a yes.

This process should take approximately 10 minutes. Upon successful application, your terminal prints the outputs defined in

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.


kubernetes_cluster_name = light-eagle-aks
resource_group_name = light-eagle-rg

»Configure kubectl

Now that you've provisioned your AKS cluster, you need to configure kubectl. Customize the following command with your resource group and cluster name, the values from Terraform's output. It will get the access credentials for your cluster and automatically configure kubectl.

$ az aks get-credentials --resource-group light-eagle-rg --name light-eagle-aks
Merged "light-eagle-aks" as current context in /Users/dos/.kube/config

The resource group name and AKS name correspond to the output variables showed after the successful Terraform run.

You can view these outputs again by running:

$ terraform output

»Access Kubernetes Dashboard

To verify that your cluster is configured correctly and running, you will navigate to it in your local browser.

We need to create a ClusterRoleBinding to use the Kubernetes dashboard. This gives the cluster-admin permission to access the kubernetes-dashboard. While you can create this using Terraform, kubectl is used in this guide so you don't need to configure your Terraform Kubernetes Provider.

$ kubectl create clusterrolebinding kubernetes-dashboard --clusterrole=cluster-admin --serviceaccount=kube-system:kubernetes-dashboard created

Finally, to access the Kubernetes dashboard, run the following command, customized with your cluster name instead of light-eagle-. This will continue running until you stop the process by pressing CTRL + C.

$ az aks browse --resource-group light-eagle-rg --name light-eagle-aks
Merged "light-eagle-aks" as current context in /var/folders/s6/m22_k3p11z104k2vx1jkqr2c0000gp/T/tmpcrh3pjs_
Proxy running on
Press CTRL+C to close the tunnel...

You should be able to access the Kubernetes dashboard at

AKS Dashboard

»Clean up your workspace

Congratulations, you have provisioned an AKS cluster, configured kubectl, and visited the Kubernetes dashboard.

If you'd like to learn how to manage your AKS cluster using the Terraform Kubernetes Provider, leave your cluster running and continue to the Kubernetes provider Learn guide.

If not, remember to destroy any resources you create once you are done with this guide. Run the destroy command and confirm with yes in your terminal.

$ terraform destroy

»Next steps

For more information on the AKS resource, visit the Azure provider documentation.

For steps on how to manage Kubernetes resources your AKS cluster or any other already created Kubernetes cluster, visit the Kubernetes provider Learn guide.

To steps on using run triggers to deploy a Kubernetes Cluster, Consul and Vault on Google Cloud, visit the Deploy Consul and Vault on a Kubernetes Cluster using Run Triggers Learn scenario.