Merge pull request #274138 from HeidiSteen/heidist-bug

[azure search] Service tag doc updates

Author: v-dirichards

articles/search/search-indexer-securing-resources.md

@@ -15,13 +15,13 @@ ms.date: 05/01/2024
 
 # Indexer access to content protected by Azure network security
 
-If your search solution requirements include an Azure virtual network, this concept article explains how a search indexer can access content that's protected by network security. It describes the outbound traffic patterns and indexer execution environments. It also covers the network protections supported by Azure AI Search and factors that might influence your security strategy. Finally, because Azure Storage is used for both data access and persistent storage, this article also covers network considerations that are specific to search and storage connectivity.
+If your Azure resources are deployed in an Azure virtual network, this concept article explains how a search indexer can access content that's protected by network security. It describes the outbound traffic patterns and indexer execution environments. It also covers the network protections supported by Azure AI Search and factors that might influence your security strategy. Finally, because Azure Storage is used for both data access and persistent storage, this article also covers network considerations that are specific to [search and storage connectivity](#access-to-a-network-protected-storage-account).
 
 Looking for step-by-step instructions instead? See [How to configure firewall rules to allow indexer access](search-indexer-howto-access-ip-restricted.md) or [How to make outbound connections through a private endpoint](search-indexer-howto-access-private.md).
 
 ## Resources accessed by indexers
 
-Azure AI Search indexers can make outbound calls to various Azure resources during execution. An indexer makes outbound calls in three situations:
+Azure AI Search indexers can make outbound calls to various Azure resources in three situations:
 
 - Connections to external data sources during indexing
 - Connections to external, encapsulated code through a skillset that includes custom skills
@@ -42,6 +42,15 @@ A list of all possible Azure resource types that an indexer might access in a ty
 > [!NOTE]
 > An indexer also connects to Azure AI services for built-in skills. However, that connection is made over the internal network and isn't subject to any network provisions under your control.
 
+Indexers connect to resources using the following approaches:
+
+- A public endpoint with credentials
+- A private endpoint, using Azure Private Link
+- Connect as a trusted service
+- Connect through IP addressing
+
+If your Azure resource is on a virtual network, you should use either a private endpoint or IP addressing to admit indexer connections to the data.
+
 ## Supported network protections
 
 Your Azure resources could be protected using any number of the network isolation mechanisms offered by Azure. Depending on the resource and region, Azure AI Search indexers can make outbound connections through IP firewalls and private endpoints, subject to the limitations indicated in the following table.
@@ -60,29 +69,28 @@ Your Azure resources could be protected using any number of the network isolatio
 
 ## Indexer execution environment
 
-Azure AI Search has the concept of an *indexer execution environment* that optimizes processing based on the characteristics of the job. There are two environments. If you're using an IP firewall to control access to Azure resources, knowing about execution environments will help you set up an IP range that is inclusive of both.
-
-For any given indexer run, Azure AI Search determines the best environment in which to run the indexer. Depending on the number and types of tasks assigned, the indexer will run in one of two environments:
-
-- A *private execution environment* that's internal to a search service. 
+Azure AI Search has the concept of an *indexer execution environment* that optimizes processing based on the characteristics of the job. There are two environments. If you're using an IP firewall to control access to Azure resources, knowing about execution environments will help you set up an IP range that is inclusive of both environments.
 
-  Indexers running in the private environment share computing resources with other indexing and query workloads on the same search service. Typically, only indexers that perform text-based indexing (without skillsets) run in this environment.
-
-- A *multitenant environment* that's managed and secured by Microsoft at no extra cost. It isn't subject to any network provisions under your control. 
-
-  This environment is used to offload computationally intensive processing, leaving service-specific resources available for routine operations. Examples of resource-intensive indexer jobs include attaching skillsets, processing large documents, or processing a high volume of documents.
+For any given indexer run, Azure AI Search determines the best environment in which to run the indexer. Depending on the number and types of tasks assigned, the indexer will run in one of two environments.
 
+| Execution environment | Description |
+|-----------------------|-------------|
+| Private | Internal to a search service. Indexers running in the private environment share computing resources with other indexing and query workloads on the same search service. Typically, only indexers that perform text-based indexing (without skillsets) run in this environment. If you set up a private connection between an indexer and your data, this is the only execution enriovnment you can use. |
+|  multitenant | Managed and secured by Microsoft at no extra cost. It isn't subject to any network provisions under your control. This environment is used to offload computationally intensive processing, leaving service-specific resources available for routine operations. Examples of resource-intensive indexer jobs include attaching skillsets, processing large documents, or processing a high volume of documents. |
+  
 The following section explains the IP configuration for admitting requests from either execution environment.
 
 ### Setting up IP ranges for indexer execution
 
-If the Azure resource that provides source data exists behind a firewall, you need [inbound rules that admit indexer connections](search-indexer-howto-access-ip-restricted.md) for all of the IPs from which an indexer request can originate. The IPs include the one used by the search service and the multitenant environment.
+If your Azure resource is behind a firewall, set up [inbound rules that admit indexer connections](search-indexer-howto-access-ip-restricted.md) for all of the IPs from which an indexer request can originate. This includes the IP address used by the search service, and the IP addresses used by the multitenant environment.
 
 - To obtain the IP address of the search service (and the private execution environment), use `nslookup` (or `ping`) to find the fully qualified domain name (FQDN) of your search service. The FQDN of a search service in the public cloud would be `<service-name>.search.windows.net`.
 
 - To obtain the IP addresses of the multitenant environments within which an indexer might run, use the `AzureCognitiveSearch` service tag. 
 
-  [Azure service tags](../virtual-network/service-tags-overview.md) have a published range of IP addresses for each service. You can find these IPs using the [discovery API](../virtual-network/service-tags-overview.md#use-the-service-tag-discovery-api) or a [downloadable JSON file](../virtual-network/service-tags-overview.md#discover-service-tags-by-using-downloadable-json-files). IP ranges are allocated by region, so check your search service region before you start.
+  [Azure service tags](../virtual-network/service-tags-overview.md) have a published range of IP addresses of the multitenant environments for each region. You can find these IPs using the [discovery API](../virtual-network/service-tags-overview.md#use-the-service-tag-discovery-api) or a [downloadable JSON file](../virtual-network/service-tags-overview.md#discover-service-tags-by-using-downloadable-json-files). IP ranges are allocated by region, so check your search service region before you start.
+
+#### Setting up IP rules for Azure SQL
 
 When setting the IP rule for the multitenant environment, certain SQL data sources support a simple approach for IP address specification. Instead of enumerating all of the IP addresses in the rule, you can create a [Network Security Group rule](../virtual-network/network-security-groups-overview.md) that specifies the `AzureCognitiveSearch` service tag. 
 
@@ -94,84 +102,65 @@ You can specify the service tag if your data source is either:
 
 Notice that if you specified the service tag for the multitenant environment IP rule, you'll still need an explicit inbound rule for the private execution environment (meaning the search service itself), as obtained through `nslookup`.
 
-## Supplement network security with authorization
-
-Firewalls and network security are a first step in preventing unauthorized access to data and operations. Authorization should be your next step. 
-
-We recommend role-based access, where Microsoft Entra ID users and groups are assigned to roles that determine read and write access to your service. See [Connect to Azure AI Search using role-based access controls](search-security-rbac.md) for a description of built-in roles and instructions for creating custom roles.
-
-If you don't need key-based authentication, we recommend that you disable API keys and use role assignments exclusively.
-
-## Choosing a connectivity approach
-
-When integrating Azure AI Search into a solution that runs on a virtual network, consider the following constraints:
-
-- An indexer can't make a direct connection to a [virtual network service endpoint](../virtual-network/virtual-network-service-endpoints-overview.md). Public endpoints with credentials, private endpoints, trusted service, and IP addressing are the only supported methodologies for indexer connections.
+## Choose a connectivity approach
 
-- A search service always runs in the cloud and can't be provisioned into a specific virtual network, running natively on a virtual machine. This functionality won't be offered by Azure AI Search.
+A search service can't be provisioned into a specific virtual network, running natively on a virtual machine. Although some Azure resources offer [virtual network service endpoints](/azure/virtual-network/virtual-network-service-endpoints-overview), this functionality won't be offered by Azure AI Search. You should plan on implementing one of the following approaches.
 
-Given the above constrains, your choices for achieving search integration in a virtual network are:
+| Approach | Details |
+|----------|---------|
+| Inbound connection to your Azure resource | Configure an inbound firewall rule on your Azure resource that admits indexer requests for your data. Your firewall configuration should include the service tag for multitenant execution and the IP address of your search service. |
+| Private connection between Azure AI Search and your Azure resource | Configure a shared private link used exclusively by your search service for connections to your resource. Connections travel over the internal network and bypass the public internet. If your resources are fully locked down (running on a protected virtual network, or otherwise not available over a public connection), a private endpoint is your only choice. See [Make outbound connections through a private endpoint](search-indexer-howto-access-private.md).|
 
-- Configure an inbound firewall rule on your Azure PaaS resource that admits indexer requests for data. Follow that up with role assignments that specify which users and groups have read and write access to your data and operations.
+Connections through a private endpoint must originate from the search service's private execution environment. 
 
-- Configure an outbound connection from Search that makes indexer connections using a [private endpoint](../private-link/private-endpoint-overview.md). 
+Configuring an IP firewall is free. A private endpoint, which is based on Azure Private Link, has a billing impact. See [Azure Private Link pricing](https://azure.microsoft.com/pricing/details/private-link/) for details.
 
-  For a private endpoint, the search service connection to your protected resource is through a *shared private link*. A shared private link is an [Azure Private Link](../private-link/private-link-overview.md) resource that's created, managed, and used from within Azure AI Search. If your resources are fully locked down (running on a protected virtual network, or otherwise not available over a public connection), a private endpoint is your only choice.
+After you configure network security, follow up with role assignments that specify which users and groups have read and write access to your data and operations. 
 
-  Connections through a private endpoint must originate from the search service's private execution environment. To meet this requirement, you'll have to disable multitenant execution. This step is described in [Make outbound connections through a private endpoint](search-indexer-howto-access-private.md).
+### Considerations for using a private endpoint
 
-Configuring an IP firewall is free. A private endpoint, which is based on Azure Private Link, has a billing impact.
+This section narrows in on the private connection option.
 
-### Working with a private endpoint
++ A shared private link requires a billable search service, where the minimum tier is either Basic for text-based indexing or Standard 2 (S2) for skills-based indexing. See [tier limits on the number of private endpoints](search-limits-quotas-capacity.md#shared-private-link-resource-limits) for details.
 
-This section summarizes the main steps for setting up a private endpoint for outbound indexer connections. This summary might help you decide whether a private endpoint is the best choice for your scenario. Detailed steps are covered in [How to make outbound connections through a private endpoint](search-indexer-howto-access-private.md).
+- Once a shared private link is created, the search service always uses it for every indexer connection to that specific Azure resource. The private connection is locked and enforced internally. You can't bypass the private connection for a public connection.
 
-#### Billing impact of Azure Private Link
+- Requires a billable Azure Private Link resource.
 
-- A shared private link requires a billable search service, where the minimum tier is either Basic for text-based indexing or Standard 2 (S2) for skills-based indexing. See [tier limits on the number of private endpoints](search-limits-quotas-capacity.md#shared-private-link-resource-limits) for details. 
+- Requires that a subscription owner approve the private endpoint connection.
 
-- Inbound and outbound connections are subject to [Azure Private Link pricing](https://azure.microsoft.com/pricing/details/private-link/).
+- Requires that you turn off the multitenant execution environment for the indexer.
 
-#### Step 1: Create a private endpoint to the secure resource
-
-You'll create a shared private link using either the portal pages of your search service or through the [Management API](/rest/api/searchmanagement/shared-private-link-resources/create-or-update).
-
-In Azure AI Search, your search service must be at least the Basic tier for text-based indexers, and S2 for indexers with skillsets.
-
-A private endpoint connection will accept requests from the private indexer execution environment, but not the multitenant environment. You'll need to disable multitenant execution as described in step 3 to meet this requirement.
-
-#### Step 2: Approve the private endpoint connection
-
-When the (asynchronous) operation that creates a shared private link resource completes, a private endpoint connection will be created in a "Pending" state. No traffic flows over the connection yet.
-
-You'll need to locate and approve this request on your secure resource. Depending on the resource, you can complete this task using Azure portal. Otherwise, use the [Private Link Service REST API](/rest/api/virtualnetwork/privatelinkservices/updateprivateendpointconnection).
-
-#### Step 3: Force indexers to run in the "private" environment
-
-For private endpoint connections, it's mandatory to set the `executionEnvironment` of the indexer to `"Private"`. This step ensures that all indexer execution is confined to the private environment provisioned within the search service.
-
-This setting is scoped to an indexer and not the search service. If you want all indexers to connect over private endpoints, each one must have the following configuration:
-
-```json
-    {
-      "name" : "myindexer",
-      ... other indexer properties
-      "parameters" : {
-          ... other parameters
-          "configuration" : {
-            ... other configuration properties
-            "executionEnvironment": "Private"
+  You do this by setting the `executionEnvironment` of the indexer to `"Private"`. This step ensures that all indexer execution is confined to the private environment provisioned within the search service. This setting is scoped to an indexer and not the search service. If you want all indexers to connect over private endpoints, each one must have the following configuration:
+  
+  ```json
+      {
+        "name" : "myindexer",
+        ... other indexer properties
+        "parameters" : {
+            ... other parameters
+            "configuration" : {
+              ... other configuration properties
+              "executionEnvironment": "Private"
+            }
           }
-        }
-    }
-```
+      }
+  ```
 
 Once you have an approved private endpoint to a resource, indexers that are set to be *private* attempt to obtain access via the private link that was created and approved for the Azure resource. 
 
 Azure AI Search will validate that callers of the private endpoint have appropriate role assignments. For example, if you request a private endpoint connection to a storage account with read-only permissions, this call will be rejected.
 
 If the private endpoint isn't approved, or if the indexer didn't use the private endpoint connection, you'll find a `transientFailure` error message in indexer execution history.
 
+## Supplement network security with token authentication
+
+Firewalls and network security are a first step in preventing unauthorized access to data and operations. Authorization should be your next step. 
+
+We recommend role-based access, where Microsoft Entra ID users and groups are assigned to roles that determine read and write access to your service. See [Connect to Azure AI Search using role-based access controls](search-security-rbac.md) for a description of built-in roles and instructions for creating custom roles.
+
+If you don't need key-based authentication, we recommend that you disable API keys and use role assignments exclusively.
+
 ## Access to a network-protected storage account
 
 A search service stores indexes and synonym lists. For other features that require storage, Azure AI Search takes a dependency on Azure Storage. Enrichment caching, debug sessions, and knowledge stores fall into this category. The location of each service, and any network protections in place for storage, will determine your data access strategy.