Deploy Kubernetes cluster for Linux containers

The Azure CLI is used to create and manage Azure resources from the command line or in scripts. This guide details using the Azure CLI to deploy a Kubernetes cluster in Azure Container Service. Once the cluster is deployed, you connect to it with the Kubernetes kubectl command-line tool, and you deploy your first Linux container.

This tutorial requires the Azure CLI version 2.0.4 or later. Run az --version to find the version. If you need to upgrade, see Install Azure CLI 2.0.

Launch Azure Cloud Shell

The Azure Cloud Shell is a free Bash shell that you can run directly within the Azure portal. It has the Azure CLI preinstalled and configured to use with your account. Click the Cloud Shell button on the menu in the upper-right of the Azure portal.

Cloud Shell

The button launches an interactive shell that you can use to run all of the steps in this topic:

Screenshot showing the Cloud Shell window in the portal

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

Log in to Azure

Log in to your Azure subscription with the az login command and follow the on-screen directions.

az login

Create a resource group

Create a resource group with the az group create command. An Azure resource group is a logical group in which Azure resources are deployed and managed.

The following example creates a resource group named myResourceGroup in the eastus location.

az group create --name myResourceGroup --location eastus

Create Kubernetes cluster

Create a Kubernetes cluster in Azure Container Service with the az acs create command.

The following example creates a cluster named myK8sCluster with one Linux master node and two Linux agent nodes. This example creates SSH keys if they don't already exist in the default locations. To use a specific set of keys, use the --ssh-key-value option. Update the cluster name to something appropriate to your environment.

az acs create --orchestrator-type=kubernetes \
    --resource-group myResourceGroup \
    --name=myK8sCluster \
    --agent-count=2 \

After several minutes, the command completes, and shows you information about your deployment.

Install kubectl

To connect to the Kubernetes cluster from your client computer, use kubectl, the Kubernetes command-line client.

If you're using Azure CloudShell, kubectl is already installed. If you want to install it locally, you can use the az acs kubernetes install-cli command.

The following Azure CLI example installs kubectl to your system. If you are running the Azure CLI on macOS or Linux, you might need to run the command with sudo.

az acs kubernetes install-cli 

Connect with kubectl

To configure kubectl to connect to your Kubernetes cluster, run the az acs kubernetes get-credentials command. The following example downloads the cluster configuration for your Kubernetes cluster.

az acs kubernetes get-credentials --resource-group=myResourceGroup --name=myK8sCluster

To verify the connection to your cluster from your machine, try running:

kubectl get nodes

kubectl lists the master and agent nodes.

NAME                    STATUS                     AGE       VERSION
k8s-agent-98dc3136-0    Ready                      5m        v1.5.3
k8s-agent-98dc3136-1    Ready                      5m        v1.5.3
k8s-master-98dc3136-0   Ready,SchedulingDisabled   5m        v1.5.3

Deploy an NGINX container

You can run a Docker container inside a Kubernetes pod, which contains one or more containers.

The following command starts the NGINX Docker container in a Kubernetes pod on one of the nodes. In this case, the container runs the NGINX web server pulled from an image in Docker Hub.

kubectl run nginx --image nginx

To see that the container is running, run:

kubectl get pods

View the NGINX welcome page

To expose the NGINX server to the world with a public IP address, type the following command:

kubectl expose deployments nginx --port=80 --type=LoadBalancer

With this command, Kubernetes creates a service and an Azure load balancer rule with a public IP address for the service.

Run the following command to see the status of the service.

kubectl get svc

Initially the IP address appears as pending. After a few minutes, the external IP address of the service is set:

NAME         CLUSTER-IP     EXTERNAL-IP     PORT(S)        AGE       
kubernetes       <none>          443/TCP        21h       
nginx     80/TCP         22m

You can use a web browser of your choice to see the default NGINX welcome page at the external IP address:

Image of browsing to Nginx

Delete cluster

When the cluster is no longer needed, you can use the az group delete command to remove the resource group, container service, and all related resources.

az group delete --name myResourceGroup

Next steps

In this quick start, you deployed a Kubernetes cluster, connected with kubectl, and deployed a pod with an NGINX container. To learn more about Azure Container Service, continue to the Kubernetes cluster tutorial.