Skip to content

Commit eb0b033

Browse files
JnHsJnHs
committed
refresh and streamline
1 parent 96083c5 commit eb0b033

File tree

1 file changed

+28
-95
lines changed

1 file changed

+28
-95
lines changed

‎articles/azure-arc/kubernetes/custom-locations.md

Lines changed: 28 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,18 @@
11
---
22
title: "Create and manage custom locations on Azure Arc-enabled Kubernetes"
3-
ms.date: 11/01/2022
3+
ms.date: 03/26/2024
44
ms.topic: how-to
55
ms.custom: references_regions, devx-track-azurecli
66
description: "Use custom locations to deploy Azure PaaS services on Azure Arc-enabled Kubernetes clusters"
77
---
88

99
# Create and manage custom locations on Azure Arc-enabled Kubernetes
1010

11-
The *custom locations* feature provides a way for tenant or cluster administrators to configure their 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 App Services, Functions, Event Grid, Logic Apps, and API Management.
11+
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 App Services, Functions, Event Grid, Logic Apps, and API Management.
1212

13-
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 multi-tenant manner.
13+
A [custom location](conceptual-custom-locations.md) 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 multi-tenant manner.
1414

15-
A conceptual overview of this feature is available in [Custom locations - Azure Arc-enabled Kubernetes](conceptual-custom-locations.md).
16-
17-
In this article, you learn how to:
18-
> [!div class="checklist"]
19-
> - Enable custom locations on your Azure Arc-enabled Kubernetes cluster.
20-
> - Create a custom location.
15+
In this article, you learn how to enable custom locations on an Arc-enabled Kubernetes cluster, and how to create a custom location.
2116

2217
## Prerequisites
2318

@@ -43,26 +38,29 @@ In this article, you learn how to:
4338
```
4439
4540
- Verify completed provider registration for `Microsoft.ExtendedLocation`.
46-
1. Enter the following commands:
41+
42+
1. Enter the following commands:
4743
4844
```azurecli
4945
az provider register --namespace Microsoft.ExtendedLocation
5046
```
5147
52-
2. Monitor the registration process. Registration may take up to 10 minutes.
48+
1. Monitor the registration process. Registration may take up to 10 minutes.
5349
5450
```azurecli
5551
az provider show -n Microsoft.ExtendedLocation -o table
5652
```
5753
5854
Once registered, the `RegistrationState` state will have the `Registered` value.
5955
60-
- Verify you have an existing [Azure Arc-enabled Kubernetes connected cluster](quickstart-connect-cluster.md).
61-
- [Upgrade your agents](agent-upgrade.md#manually-upgrade-agents) to the latest version.
56+
- Verify you have an existing [Azure Arc-enabled Kubernetes connected cluster](quickstart-connect-cluster.md), and [upgrade your agents](agent-upgrade.md#manually-upgrade-agents) to the latest version. Confirm that the machine on which you will run the commands described in this article has a `kubeconfig` file that points to this cluster.
6257
6358
## Enable custom locations on your cluster
6459
65-
If you are signed in to Azure CLI as a Microsoft Entra user, to enable this feature on your cluster, execute the following command:
60+
> [!TIP]
61+
> The custom locations feature is dependent on the [cluster connect](cluster-connect.md) feature. Both features have to be enabled in the cluster for custom locations to work.
62+
63+
If you are signed in to Azure CLI as a Microsoft Entra user, use the following command:
6664
6765
```azurecli
6866
az connectedk8s enable-features -n <clusterName> -g <resourceGroupName> --features cluster-connect custom-locations
@@ -76,15 +74,7 @@ Unable to fetch oid of 'custom-locations' app. Proceeding without enabling the f
7674

7775
This is because a service principal doesn't have permissions to get information about the application used by the Azure Arc service. To avoid this error, complete the following steps:
7876

79-
1. Sign in to Azure CLI using your user account. Fetch the `objectId` or `id` of the Microsoft Entra application used by Azure Arc service. The command you use depends on your version of Azure CLI.
80-
81-
If you're using an Azure CLI version lower than 2.37.0, use the following command:
82-
83-
```azurecli
84-
az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query objectId -o tsv
85-
```
86-
87-
If you're using Azure CLI version 2.37.0 or higher, use the following command instead:
77+
1. Sign in to Azure CLI using your user account. Fetch the `objectId` or `id` of the Microsoft Entra application used by the Azure Arc service by using the following command:
8878

8979
```azurecli
9080
az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv
@@ -96,19 +86,14 @@ This is because a service principal doesn't have permissions to get information
9686
az connectedk8s enable-features -n <cluster-name> -g <resource-group-name> --custom-locations-oid <objectId/id> --features cluster-connect custom-locations
9787
```
9888
99-
> [!NOTE]
100-
> The custom locations feature is dependent on the [Cluster Connect](cluster-connect.md) feature. Both features have to be enabled for custom locations to work.
101-
>
102-
> `az connectedk8s enable-features` must be run on a machine where the `kubeconfig` file is pointing to the cluster on which the features are to be enabled.
103-
10489
## Create custom location
10590
10691
1. Deploy the Azure service cluster extension of the Azure service instance you want to install on your cluster:
10792
108-
- [Azure Arc-enabled Data Services](../data/create-data-controller-direct-prerequisites.md)
93+
- [Azure Arc-enabled data services](../data/create-data-controller-direct-prerequisites.md)
10994
11095
> [!NOTE]
111-
> Outbound proxy without authentication and outbound proxy with basic authentication are supported by the Azure Arc-enabled Data Services cluster extension. Outbound proxy that expects trusted certificates is currently not supported.
96+
> Outbound proxy without authentication and outbound proxy with basic authentication are supported by the Azure Arc-enabled data services cluster extension. Outbound proxy that expects trusted certificates is currently not supported.
11297
11398
- [Azure App Service on Azure Arc](../../app-service/manage-create-arc-environment.md#install-the-app-service-extension)
11499
@@ -120,7 +105,7 @@ This is because a service principal doesn't have permissions to get information
120105
az connectedk8s show -n <clusterName> -g <resourceGroupName> --query id -o tsv
121106
```
122107
123-
1. 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`:
108+
1. Get the Azure Resource Manager identifier of the cluster extension you deployed to the Azure Arc-enabled Kubernetes cluster, referenced in later steps as `extensionId`:
124109
125110
```azurecli
126111
az k8s-extension show --name <extensionInstanceName> --cluster-type connectedClusters -c <clusterName> -g <resourceGroupName> --query id -o tsv
@@ -129,26 +114,26 @@ This is because a service principal doesn't have permissions to get information
129114
1. Create the custom location by referencing the Azure Arc-enabled Kubernetes cluster and the extension:
130115
131116
```azurecli
132-
az customlocation create -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds>
117+
az customlocation create -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionId>
133118
```
134119
135120
- Required parameters:
136121
137122
| Parameter name | Description |
138123
|----------------|------------|
139-
| `--name, --n` | Name of the custom location |
140-
| `--resource-group, --g` | Resource group of the custom location |
141-
| `--namespace` | Namespace in the cluster bound to the custom location being created |
142-
| `--host-resource-id` | Azure Resource Manager identifier of the Azure Arc-enabled Kubernetes cluster (connected cluster) |
143-
| `--cluster-extension-ids` | Azure Resource Manager identifiers of the cluster extension instances installed on the connected cluster. Provide a space-separated list of the cluster extension IDs |
124+
| `--name, --n` | Name of the custom location. |
125+
| `--resource-group, --g` | Resource group of the custom location. |
126+
| `--namespace` | Namespace in the cluster bound to the custom location being created. |
127+
| `--host-resource-id` | Azure Resource Manager identifier of the Azure Arc-enabled Kubernetes cluster (connected cluster). |
128+
| `--cluster-extension-ids` | Azure Resource Manager identifier of a cluster extension instance installed on the connected cluster. For multiple extensions, provide a space-separated list of cluster extension IDs |
144129
145130
- Optional parameters:
146131
147132
| Parameter name | Description |
148133
|--------------|------------|
149-
| `--location, --l` | Location of the custom location Azure Resource Manager resource in Azure. By default it will be set to the location of the connected cluster |
150-
| `--tags` | Space-separated list of tags: key[=value] [key[=value] ...]. Use '' to clear existing tags |
151-
| `--kubeconfig` | Admin `kubeconfig` of cluster |
134+
| `--location, --l` | Location of the custom location Azure Resource Manager resource in Azure. If not specified, the location of the connected cluster is used. |
135+
| `--tags` | Space-separated list of tags in the format `key[=value]`. Use '' to clear existing tags. |
136+
| `--kubeconfig` | Admin `kubeconfig` of cluster. |
152137
153138
## Show details of a custom location
154139
@@ -158,13 +143,6 @@ To show the details of a custom location, use the following command:
158143
az customlocation show -n <customLocationName> -g <resourceGroupName>
159144
```
160145

161-
Required parameters:
162-
163-
| Parameter name | Description |
164-
|----------------|------------|
165-
| `--name, --n` | Name of the custom location |
166-
| `--resource-group, --g` | Resource group of the custom location |
167-
168146
## List custom locations
169147

170148
To list all custom locations in a resource group, use the following command:
@@ -173,58 +151,22 @@ To list all custom locations in a resource group, use the following command:
173151
az customlocation list -g <resourceGroupName>
174152
```
175153

176-
Required parameters:
177-
178-
| Parameter name | Description |
179-
|----------------|------------|
180-
| `--resource-group, --g` | Resource group of the custom location |
181-
182154
## Update a custom location
183155

184-
Use the `update` command to add new tags or 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.
156+
Use the `update` command to add new values for `--tags` or associate new `--cluster-extension-ids` to the custom location, while retaining existing values for tags and associated cluster extensions.
185157

186158
```azurecli
187159
az customlocation update -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds>
188160
```
189161

190-
Required parameters:
191-
192-
| Parameter name | Description |
193-
|----------------|------------|
194-
| `--name, --n` | Name of the custom location |
195-
| `--resource-group, --g` | Resource group of the custom location |
196-
| `--namespace` | Namespace in the cluster bound to the custom location being created |
197-
| `--host-resource-id` | Azure Resource Manager identifier of the Azure Arc-enabled Kubernetes cluster (connected cluster) |
198-
199-
Optional parameters:
200-
201-
| Parameter name | Description |
202-
|--------------|------------|
203-
| `--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-separated list of the cluster extension IDs |
204-
| `--tags` | Add new tags in addition to existing tags. Space-separated list of tags: key[=value] [key[=value] ...]. |
205-
206162
## Patch a custom location
207163

208-
Use the `patch` command to replace existing tags, cluster extension IDs with new tags, and cluster extension IDs. `--cluster-extension-ids`, `assign-identity`, `--tags` can be patched.
164+
Use the `patch` command to replace existing values for `--cluster-extension-ids` or `--tags`. Previous values are not retained.
209165

210166
```azurecli
211167
az customlocation patch -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds>
212168
```
213169

214-
Required parameters:
215-
216-
| Parameter name | Description |
217-
|----------------|------------|
218-
| `--name, --n` | Name of the custom location |
219-
| `--resource-group, --g` | Resource group of the custom location |
220-
221-
Optional parameters:
222-
223-
| Parameter name | Description |
224-
|--------------|------------|
225-
| `--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-separated list of the cluster extension IDs |
226-
| `--tags` | Add new tags in addition to existing tags. Space-separated list of tags: key[=value] [key[=value] ...]. |
227-
228170
## Delete a custom location
229171

230172
To delete a custom location, use the following command:
@@ -233,18 +175,9 @@ To delete a custom location, use the following command:
233175
az customlocation delete -n <customLocationName> -g <resourceGroupName>
234176
```
235177

236-
Required parameters:
237-
238-
| Parameter name | Description |
239-
|----------------|------------|
240-
| `--name, --n` | Name of the custom location |
241-
| `--resource-group, --g` | Resource group of the custom location |
242-
243178
## Troubleshooting
244179

245-
If custom location creation fails with the error 'Unknown proxy error occurred', it may be due to network policies configured to disallow pod-to-pod internal communication.
246-
247-
To resolve this issue, modify your network policy to allow pod-to-pod internal communication within the `azure-arc` namespace. Be sure to also add the `azure-arc` namespace as part of the no-proxy exclusion list for your configured policy.
180+
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. Be sure to also add the `azure-arc` namespace as part of the no-proxy exclusion list for your configured policy.
248181

249182
## Next steps
250183

0 commit comments

Comments
 (0)