Create and manage custom locations on Azure Arc-enabled Kubernetes

Custom Locations provides a way for tenant or cluster administrators to configure their Azure Arc-enabled Kubernetes clusters as target locations for deploying Azure services instances i.e resources like Azure Arc-enabled SQL Managed Instance and Azure Arc-enabled PostgreSQL Hyperscale. On Azure Arc-enabled Kubernetes clusters, custom location represents an abstraction of a namespace within the Azure Arc-enabled Kubernetes cluster. Tenant or cluster administrators can assign Role-based access control (RBAC) permissions to application developers or database admins to deploy resources like Azure Arc-enabled SQL Managed Instances, Azure Arc-enabled PostgreSQL Hyperscale instances or Azure web apps on the custom location.

A conceptual overview of this feature is available in Custom locations - Azure Arc-enabled Kubernetes article.

In this article, you learn how to:

  • Enable custom locations on your Azure Arc-enabled Kubernetes cluster.
  • Create a custom location.

Prerequisites

  • Install or upgrade Azure CLI to version >= 2.16.0.

  • Install the following Azure CLI extensions:

    • connectedk8s (version 1.1.0 or later)
    • k8s-extension (version 0.2.0 or later)
    • customlocation (version 0.1.0 or later)
    az extension add --name connectedk8s
    az extension add --name k8s-extension
    az extension add --name customlocation
    

    If you've previously installed the connectedk8s, k8s-extension, and customlocation extensions, update to the latest version using the following command:

    az extension update --name connectedk8s
    az extension update --name k8s-extension
    az extension update --name customlocation
    

    Note

    We recommend using the latest version of the CLI extensions to get latest features.

  • Verify completed provider registration for Microsoft.ExtendedLocation.

    1. Enter the following commands:

      az provider register --namespace Microsoft.ExtendedLocation
      
    2. Monitor the registration process. Registration may take up to 10 minutes.

      az provider show -n Microsoft.ExtendedLocation -o table
      

      Once registered, the RegistrationState state will have the Registered value.

  • Verify you have an existing Azure Arc-enabled Kubernetes connected cluster.

Enable custom locations on cluster

If you are logged into Azure CLI as a Azure AD user, to enable this feature on your cluster, execute the following command:

az connectedk8s enable-features -n <clusterName> -g <resourceGroupName> --features cluster-connect custom-locations

If you are logged into Azure CLI using a service principal, to enable this feature on your cluster, execute the following steps:

  1. Fetch the Object ID of the Azure AD application used by Azure Arc service:

    az ad sp show --id 'bc313c14-388c-4e7d-a58e-70017303ee3b' --query objectId -o tsv
    
  2. Use the <objectId> value from above step to enable custom locations feature on the cluster:

    az connectedk8s enable-features -n <cluster-name> -g <resource-group-name> --custom-locations-oid <objectId> --features cluster-connect custom-locations
    

Note

  1. Custom Locations feature is dependent on the Cluster Connect feature. So both features have to be enabled for custom locations to work.
  2. az connectedk8s enable-features needs to be run on a machine where the kubeconfig file is pointing to the cluster on which the features are to be enabled.

Create custom location

  1. Deploy the Azure service cluster extension of the Azure service instance you intent to install on your cluster:

  2. Get the Azure Resource Manager identifier of the Azure Arc-enabled Kubernetes cluster, referenced in later steps as connectedClusterId:

    az connectedk8s show -n <clusterName> -g <resourceGroupName>  --query id -o tsv
    
  3. Get the Azure Resource Manager identifier of the cluster extension deployed on top of Azure Arc-enabled Kubernetes cluster, referenced in later steps as extensionId:

    az k8s-extension show --name <extensionInstanceName> --cluster-type connectedClusters -c <clusterName> -g <resourceGroupName>  --query id -o tsv
    
  4. Create custom location by referencing the Azure Arc-enabled Kubernetes cluster and the extension:

    az customlocation create -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds> 
    

Required parameters

Parameter name Description
--name, --n Name of the custom location
--resource-group, --g Resource group of the custom location
--namespace Namespace in the cluster bound to the the custom location being created
--host-resource-id Azure Resource Manager identifier of the Azure Arc-enabled Kubernetes cluster (connected cluster)
--cluster-extension-ids Azure Resource Manager identifiers of the cluster extension instances installed on the connected cluster. Provide a space-seperated list of the cluster extension ids

Optional parameters

Parameter name Description
--assign-identity Default is None. Creates a system-assigned managed identity if parameter is set to "SystemAssigned"
--location, --l Location of the custom location Azure Resource Manager resource in Azure. By default, this will be set to the location (or Azure region) of the connected cluster
--tags Space-separated list of tags: key[=value] [key[=value] ...]. Use '' to clear existing tags
--kubeconfig Admin Kubeconfig of Cluster. Needs to passed in as a file if the cluster is a non-AAD enabled cluster

Show details of a custom location

Show details of a custom location

    az customlocation show -n <customLocationName> -g <resourceGroupName> 

Required parameters

Parameter name Description
--name, --n Name of the custom location
--resource-group, --g Resource group of the custom location

List custom locations

Lists all custom locations in a resource group

    az customlocation show -g <resourceGroupName> 

Required parameters

Parameter name Description
--resource-group, --g Resource group of the custom location

Update a custom location

Use update command when you want to add new tags, associate new cluster extension IDs to the custom location while retaining existing tags and associated cluster extensions. --cluster-extension-ids, --tags, assign-identity can be updated.

    az customlocation update -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds> 

Required parameters

Parameter name Description
--name, --n Name of the custom location
--resource-group, --g Resource group of the custom location
--namespace Namespace in the cluster bound to the the custom location being created
--host-resource-id Azure Resource Manager identifier of the Azure Arc-enabled Kubernetes cluster (connected cluster)

Optional parameters

Parameter name Description
--assign-identity Can be updated to either None or "SystemAssigned if you want to assign a system-assigned managed identity to the custom location
--cluster-extension-ids Associate new cluster extensions to this custom location by providing Azure Resource Manager identifiers of the cluster extension instances installed on the connected cluster. Provide a space-seperated list of the cluster extension ids
--tags Add new tags in addition to existing tags.Space-separated list of tags: key[=value] [key[=value] ...].

Patch a custom location

Use patch command when you want to replace existing tags, cluster extension IDs with new tags, cluster extension IDs. --cluster-extension-ids, assign-identity, --tags can be patched.

    az customlocation patch -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds> 

Required parameters

Parameter name Description
--name, --n Name of the custom location
--resource-group, --g Resource group of the custom location

Optional parameters

Parameter name Description
--assign-identity Can be updated to either None or "SystemAssigned if you want to assign a system-assigned managed identity to the custom location
--cluster-extension-ids Associate new cluster extensions to this custom location by providing Azure Resource Manager identifiers of the cluster extension instances installed on the connected cluster. Provide a space-seperated list of the cluster extension IDs
--tags Add new tags in addition to existing tags.Space-separated list of tags: key[=value] [key[=value] ...].

Delete a custom location

   az customlocation delete -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds> 

Next steps