Quickstart: Connect an existing Kubernetes cluster to Azure Arc

• 02/19/2021
• 5 minutes to read
• • s
  • S
  • v

In this quickstart, we'll reap the benefits of Azure Arc enabled Kubernetes and connect an existing Kubernetes cluster to Azure Arc. For a conceptual take on connecting clusters to Azure Arc, see the Azure Arc enabled Kubernetes Agent Architecture article.

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

Prerequisites

• Use the Bash environment in Azure Cloud Shell.

  

• If you prefer, install the Azure CLI to run CLI reference commands.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For additional sign-in options, see Sign in with the Azure CLI.

  • When you're prompted, install Azure CLI extensions on first use. For more information about extensions, see Use extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

• Verify you have:

  • An up-and-running Kubernetes cluster.
  • A kubeconfig file.
  • 'Read' and 'Write' permissions for the user or service principal used with az login and az connectedk8s connect commands on the Microsoft.Kubernetes/connectedclusters resource type.

• Install the latest release of Helm 3.

• Install the following Azure Arc enabled Kubernetes CLI extensions:

  az extension add --name connectedk8s
  az extension add --name k8sconfiguration
  

  • To update these extensions to the latest version, run the following commands:

  az extension update --name connectedk8s
  az extension update --name k8sconfiguration
  

Meet network requirements

Install the Azure Arc enabled Kubernetes CLI extensions

Enter the following commands:

```azurecli
az extension add --name connectedk8s
az extension add --name k8sconfiguration
```

Register the two providers for Azure Arc enabled Kubernetes

1. Enter the following commands:

   az provider register --namespace Microsoft.Kubernetes
   az provider register --namespace Microsoft.KubernetesConfiguration
   

2. Monitor the registration process. Registration may take up to 10 minutes.

   az provider show -n Microsoft.Kubernetes -o table
   az provider show -n Microsoft.KubernetesConfiguration -o table    
   

Create a resource group

Create a resource group:

az group create --name AzureArcTest -l EastUS -o table

Location    Name
----------  ------------
eastus      AzureArcTest

Connect an existing Kubernetes cluster

1. Verify connectivity to your Kubernetes cluster using kubectl cluster-info.

2. Connect your Kubernetes cluster to Azure Arc using the following command:

   az connectedk8s connect --name AzureArcTest1 --resource-group AzureArcTest
   

   Command group 'connectedk8s' is in preview. It may be changed/removed in a future release.
   Helm release deployment succeeded
   
   {
     "aadProfile": {
       "clientAppId": "",
       "serverAppId": "",
       "tenantId": ""
     },
     "agentPublicKeyCertificate": "xxxxxxxxxxxxxxxxxxx",
     "agentVersion": null,
     "connectivityStatus": "Connecting",
     "distribution": "gke",
     "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/AzureArcTest/providers/Microsoft.Kubernetes/connectedClusters/AzureArcTest1",
     "identity": {
       "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "type": "SystemAssigned"
     },
     "infrastructure": "gcp",
     "kubernetesVersion": null,
     "lastConnectivityTime": null,
     "location": "eastus",
     "managedIdentityCertificateExpirationTime": null,
     "name": "AzureArcTest1",
     "offering": null,
     "provisioningState": "Succeeded",
     "resourceGroup": "AzureArcTest",
     "tags": {},
     "totalCoreCount": null,
     "totalNodeCount": null,
     "type": "Microsoft.Kubernetes/connectedClusters"
   }
   

Verify cluster connection

View a list of your connected clusters with the following command:

az connectedk8s list -g AzureArcTest -o table

Command group 'connectedk8s' is in preview. It may be changed/removed in a future release.
Name           Location    ResourceGroup
-------------  ----------  ---------------
AzureArcTest1  eastus      AzureArcTest

Connect using an outbound proxy server

If your cluster is behind an outbound proxy server, Azure CLI and the Azure Arc enabled Kubernetes agents need to route their requests via the outbound proxy server.

1. Verify you have the 0.2.5+ version of the connectedk8s extension installed on your machine.

   az -v
   

   • Run the prerequisite extension update commands to get the latest version of the necessary extensions on your machine.

2. Set the environment variables needed for Azure CLI to use the outbound proxy server:

   • If you are using bash, run the following command with appropriate values:

     export HTTP_PROXY=<proxy-server-ip-address>:<port>
     export HTTPS_PROXY=<proxy-server-ip-address>:<port>
     export NO_PROXY=<cluster-apiserver-ip-address>:<port>
     

   • If you are using PowerShell, run the following command with appropriate values:

     $Env:HTTP_PROXY = "<proxy-server-ip-address>:<port>"
     $Env:HTTPS_PROXY = "<proxy-server-ip-address>:<port>"
     $Env:NO_PROXY = "<cluster-apiserver-ip-address>:<port>"
     

3. Run the connect command with proxy parameters specified:

   az connectedk8s connect -n <cluster-name> -g <resource-group> --proxy-https https://<proxy-server-ip-address>:<port> --proxy-http http://<proxy-server-ip-address>:<port> --proxy-skip-range <excludedIP>,<excludedCIDR> --proxy-cert <path-to-cert-file>
   

View Azure Arc agents for Kubernetes

Azure Arc enabled Kubernetes deploys a few operators into the azure-arc namespace.

1. View these deployments and pods using:

   kubectl -n azure-arc get deployments,pods
   

2. Verify all pods are in a Running state.

   NAME                                        READY      UP-TO-DATE  AVAILABLE  AGE
   deployment.apps/cluster-metadata-operator     1/1             1        1      16h
   deployment.apps/clusteridentityoperator       1/1             1        1      16h
   deployment.apps/config-agent                  1/1             1        1      16h
   deployment.apps/controller-manager            1/1             1        1      16h
   deployment.apps/flux-logs-agent               1/1             1        1      16h
   deployment.apps/metrics-agent                 1/1             1        1      16h
   deployment.apps/resource-sync-agent           1/1             1        1      16h
   
   NAME                                           READY    STATUS   RESTART AGE
   pod/cluster-metadata-operator-7fb54d9986-g785b  2/2     Running  0       16h
   pod/clusteridentityoperator-6d6678ffd4-tx8hr    3/3     Running  0       16h
   pod/config-agent-544c4669f9-4th92               3/3     Running  0       16h
   pod/controller-manager-fddf5c766-ftd96          3/3     Running  0       16h
   pod/flux-logs-agent-7c489f57f4-mwqqv            2/2     Running  0       16h
   pod/metrics-agent-58b765c8db-n5l7k              2/2     Running  0       16h
   pod/resource-sync-agent-5cf85976c7-522p5        3/3     Running  0       16h
   

Clean up resources

You can delete the Microsoft.Kubernetes/connectedcluster resource, any associated sourcecontrolConfiguration resources, and any agents running on the cluster using Azure CLI using the following command:

az connectedk8s delete --name AzureArcTest1 --resource-group AzureArcTest

Next steps

Advance to the next article to learn how to deploy configurations to your connected Kubernetes cluster using GitOps.