Delen via

Creëer en beheer aangepaste locaties op Azure Arc ingeschakelde Kubernetes

The custom locations feature provides a way to configure your Azure Arc-enabled Kubernetes clusters as target locations for deploying instances of Azure offerings. Examples of Azure offerings that can be deployed on top of custom locations include databases, such as SQL Managed Instance enabled by Azure Arc and Azure Arc-enabled PostgreSQL server, or application instances, such as Container Apps, Logic Apps, Event Grid, Logic Apps, and API Management.

A custom location has a one-to-one mapping to a namespace within the Azure Arc-enabled Kubernetes cluster. The custom location Azure resource combined with Azure role-based access control (Azure RBAC) can be used to grant granular permissions to application developers or database admins, enabling them to deploy resources such as databases or application instances on top of Arc-enabled Kubernetes clusters in a multitenant environment.

In this article, you learn how to enable custom locations on an Arc-enabled Kubernetes cluster, and how to create a custom location.

Prerequisites

  • Install or upgrade Azure CLI to the latest version.

  • Installeer de nieuwste versies van de volgende Azure CLI-extensies:

    • connectedk8s

    • k8s-extension

    • customlocation

      az extension add --name connectedk8s
az extension add --name k8s-extension
az extension add --name customlocation

      Als je de connectedk8s, k8s-extension, en customlocation extensies al hebt geïnstalleerd, update dan naar de nieuwste versie met behulp van het volgende commando:

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

  • Controleer de voltooiing van de providerregistratie voor Microsoft.ExtendedLocation.

    1. Voer de volgende commando's in:

      az provider register --namespace Microsoft.ExtendedLocation

    2. Bewaak het registratieproces. De registratie kan tot maximaal 10 minuten duren.

      az provider show -n Microsoft.ExtendedLocation -o table

      Zodra geregistreerd, zal de RegistrationState status de Registered waarde hebben.

  • Controleer of u een bestaand Azure Arc-enabled Kubernetes connected cluster hebt en werk uw agents bij tot de nieuwste versie. Confirm that the machine on which you will run the commands described in this article has a kubeconfig file that points to this cluster.

Enable custom locations on your cluster

Belangrijk

De functie voor aangepaste locaties is afhankelijk van de cluster verbindingsfunctie. Both features must be enabled in the cluster for custom locations to function.

De object-ID (OID) van de aangepaste locatie is nodig om aangepaste locaties in te schakelen. Als je gebruikersaccount de vereiste machtigingen heeft, wordt de OID automatisch opgehaald tijdens het inschakelen van functies. Als u geen geldig gebruikersaccount heeft, wordt de handmatig doorgegeven OID gebruikt, maar de OID kan niet worden gevalideerd. Als de OID ongeldig is, kan de aangepaste locatie mogelijk niet correct worden ingeschakeld.

De functie aangepaste locaties moet worden ingeschakeld voordat u de aangepaste locaties maakt, omdat de activering de vereiste machtigingen biedt voor het maken van de naamruimte voor aangepaste locaties in het Kubernetes-cluster.

Om de functie Aangepaste Locaties in te schakelen als een Microsoft Entra-gebruiker, volg je de onderstaande stappen:

  1. Meld je aan bij Azure CLI als een Microsoft Entra-gebruiker en voer de volgende opdracht uit:
az connectedk8s enable-features -n <clusterName> -g <resourceGroupName> --features cluster-connect custom-locations

Om de functie voor aangepaste locaties in te schakelen met een service-principal, volgt u de onderstaande stappen:

Haal handmatig de aangepaste locatie-OID op door de volgende stappen te volgen:

  1. Sign in to Azure CLI as a Microsoft Entra user.

  2. Voer de volgende opdracht uit om de aangepaste locatie oid (object-ID) op te halen, waarbij --id verwijst naar de Custom Location-service app zelf, en vooraf gedefinieerd en ingesteld is op bc313c14-388c-4e7d-a58e-70017303ee3b:

    Important! Kopieer en voer het commando precies uit zoals hieronder weergegeven. Do not replace the value passed to the --id parameter with a different value.

    az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv

  3. Sign in to Azure CLI using the service principal. Run the following command to enable the custom locations feature on the cluster, using the oid (object ID) value from the previous step for the --custom-locations-oid parameter:

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

Maak aangepaste locatie aan

  1. Implementeer de Azure-serviceclusterextensie van de Azure-service-instantie die je wilt installeren op je cluster.

  2. Verkrijg de Azure Resource Manager-identificatie van het Azure Arc-ingeschakelde Kubernetes-cluster, in latere stappen aangeduid als connectedClusterId:

    az connectedk8s show -n <clusterName> -g <resourceGroupName>  --query id -o tsv

  3. Verkrijg de Azure Resource Manager-identificatie van de clusterextensie die u hebt ingezet op de met Azure Arc-ingeschakelde Kubernetes-cluster, in latere stappen aangeduid als extensionId:

    az k8s-extension show --name <extensionInstanceName> --cluster-type connectedClusters -c <clusterName> -g <resourceGroupName>  --query id -o tsv

  4. Maak de aangepaste locatie door te verwijzen naar de Azure Arc-ingeschakelde Kubernetes-cluster en de extensie.

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

    • Required parameters:

      Parameter naam Beschrijving
      --name, --n Naam van de aangepaste locatie.
      --resource-group, --g Resourcegroep van de aangepaste locatie.
      --namespace Namespace in de cluster verbonden met de aangepaste locatie die wordt aangemaakt.
      --host-resource-id Azure Resource Manager-identificatie van de door Azure Arc ingeschakelde Kubernetes-cluster (verbonden cluster).
      --cluster-extension-ids Azure Resource Manager-id van een clusterextensie-instantie geïnstalleerd op het verbonden cluster. Voor meerdere extensies, geef een door spaties gescheiden lijst van clusterextensie-ID's.

    • Optional parameters:

      Parameternaam Description
      --location, --l Location of the custom location Azure Resource Manager resource in Azure. Als er niets is gespecificeerd, wordt de locatie van het aangesloten cluster gebruikt.
      --tags Lijst met door spaties gescheiden tags in het formaat key[=value]. Gebruik '' om bestaande tags te wissen.
      --kubeconfig Beheerder kubeconfig van cluster.

  5. Confirm that custom location was successfully enabled by running the following command and checking that ProvisioningState is Succeeded:

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

Toon details van een aangepaste locatie

To show the details of a custom location, use the following command:

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

Lijst aangepaste locaties

Om alle aangepaste locaties binnen een resourcegroep op te sommen, gebruikt u het volgende commando:

az customlocation list -g <resourceGroupName>

Een aangepaste locatie bijwerken

Gebruik het update commando om nieuwe waarden toe te voegen voor --tags of nieuwe --cluster-extension-ids aan de aangepaste locatie te koppelen, terwijl bestaande waarden voor tags en gekoppelde clusterextensies behouden blijven.

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

Patch a custom location

Gebruik de patch opdracht om bestaande waarden voor --cluster-extension-ids of --tags te vervangen. Eerdere waarden worden niet behouden.

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

Verwijder een aangepaste locatie

Om een aangepaste locatie te verwijderen, gebruik de volgende opdracht:

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

Troubleshooting

Fout bij het verkrijgen van aanmeldingsreferenties in Azure CLI v2.70.0

You may encounter an error that contains: TypeError: get_login_credentials() got an unexpected keyword argument 'resource'. Azure CLI v2.70.0 heeft een ingrijpende wijziging doorgevoerd die deze fout veroorzaakt. Een oplossing is beschikbaar in de customlocation Az CLI-extensie v0.1.4 voor compatibiliteit met Azure CLI v2.70.0 en hoger. If you are using a customlocation Az CLI extension below v0.1.4, you need to downgrade Azure CLI to version 2.69.0. Als u het Azure CLI-installatieprogramma hebt gebruikt, kunt u de huidige versie verwijderen en Azure CLI v2.69.0 installeren vanuit de Azure CLI installation page. Als u het pip-installatieprogramma hebt gebruikt, kunt u de volgende opdracht uitvoeren om te downgraden: pip install azure-cli==2.69.0.

Onbekende proxyfout

If custom location creation fails with the error Unknown proxy error occurred, modify your network policy to allow pod-to-pod internal communication within the azure-arc namespace. Zorg ervoor dat je ook de azure-arc naamruimte toevoegt als onderdeel van de no-proxy uitsluitingslijst voor je geconfigureerde beleid.

Service principal warning

Als je probeert een aangepaste locatie in te schakelen terwijl je bent ingelogd op Azure CLI met behulp van een service-principal, kun je de volgende waarschuwing tegenkomen:

Unable to fetch oid of 'custom-locations' app. Proceeding without enabling the feature. Insufficient privileges to complete the operation.

Deze waarschuwing treedt op omdat de service-principal niet beschikt over de benodigde rechten om de oid (object-ID) van de aangepaste locatie die door de Azure Arc-dienst wordt gebruikt, op te halen. Volg de hierboven gegeven instructies om de functie voor aangepaste locaties in te schakelen met behulp van een service-principal.

Resourceprovider heeft geen vereiste machtigingen

Als u de aangepaste locatie probeert te maken voordat de functie voor aangepaste locatie is ingeschakeld in het Kubernetes-cluster, wordt mogelijk het volgende foutbericht weergegeven:

Deployment failed. Correlation ID: ... "Microsoft.ExtendedLocation" resource provider does not have the required permissions to create a namespace on the cluster. Refer to https://aka.ms/ArcK8sCustomLocationsDocsEnableFeature to provide the required permissions to the resource provider.

Volg eerst de bovenstaande instructies om de functie voor aangepaste locatie in te schakelen op het Kubernetes-cluster. Nadat de functie is ingeschakeld, kunt u de stappen volgen om de aangepaste locatie te maken.

Next steps