Skip to content

Latest commit

 

History

History
378 lines (280 loc) · 16.2 KB

AUTOMATED_INSTALLATION.md

File metadata and controls

378 lines (280 loc) · 16.2 KB

Custom Installation for Zero Trust

This guide details the automated installation of the Solution Accelerator within a Zero Trust architecture. It leverages Bicep Infrastructure as Code (IaC) for efficient deployment and management of Azure resources. The guide includes prerequisites, a comprehensive list of required resources, and a step-by-step installation process, ensuring a streamlined setup that adheres to Zero Trust principles.

Table of Contents

  1. Prerequisites
  2. Resource List
  3. Installation Procedure
  4. Optional Next Steps
  5. Extending Application Components

Prerequisites

** If you have not created an Azure AI service resource in the subscription before

Permissions required

You will also need Owner or Contributor + User Access Administrator permission in Subscription scope.

Alternatively, you can create a Custom Role.

Tools to run the setup

Resource List

Here is the complete list of resources for a standard Zero Trust deployment, including descriptions and SKUs. These defaults have been extensively tested in the automated installation. You can review them to adjust to your needs, considering usage factors like user volume and data.

Tip

Review this list before deploying to ensure you have the necessary quota for deployment in the desired subscription and region.

App Services

  • App Service Plan
    Hosts the frontend and function apps.
    • SKU: P0v3
    • Operating System: Linux
    • Zone Redundant: Disabled
  • Function App (Orchestrator)
    Orchestrates the RAG flow.
    • Operating System: Linux
    • LinuxFxVersion: python|3.11
  • Function App (Data Ingestion)
    Supports the Data Ingestion Pipeline.
    • Operating System: Linux
    • LinuxFxVersion: python|3.11
  • App Service (Frontend)
    Provides the Web User Interface.
    • Operating System: Linux
    • LinuxFxVersion: python|3.12
  • Application Insights
    Provides real-time monitoring for apps.
    • Type: Classic

Security

  • Key Vault (Application)
    Stores API keys when needed.
    • SKU: Standard
    • Soft Delete: Enabled
    • Purge Protection: Enabled
  • Key Vault (Test VM Bastion)
    Used by Bastion to store the Test VM password.
    • SKU: Standard
    • Soft Delete: Enabled
    • Purge Protection: Enabled

AI Services

  • Azure AI Services Multi-Service Account
    Reads documents (Data Ingestion) and interacts with users (Web UI).
    • SKU: Standard
  • Azure OpenAI
    Generates responses and vector embeddings.
    • SKU: Standard
    • Deployments:
      • Regional gpt-4o, 40 TPM.
      • text-embedding-3-large, 40 TPM.
  • Search Service
    Provides vector indexes for the retrieval step.
    • SKU: Standard2
    • Replicas: 1
    • Partitions: 1

Compute

  • Virtual Machine (Test VM)
    Provides access to configure and test the solution after disabling public endpoints.
    • Operating System: Windows (Windows Server 2019 Datacenter)
    • SKU: Standard_D4s_v3 (4 vCPUs, 16 GiB memory)
    • Image Publisher: microsoft-dsvm (Data Science VM)
    • Image Offer: dsvm-win-2019

Storage

  • Storage Account (Documents)
    Stores content used for grounding responses.
    • Performance: Standard
    • Replication: Locally-redundant storage (LRS)
    • Account Type: StorageV2 (general purpose v2)
  • Storage Account (Orchestrator Function App)
    Stores logs, code, and execution state for the Orchestrator Function App.
    • Performance: Standard
    • Replication: Locally-redundant storage (LRS)
    • Account Type: Storage (general purpose v1)
  • Storage Account (Data Ingestion Function App)
    Stores logs, code, and execution state for the Data Ingestion Function App.
    • Performance: Standard
    • Replication: Locally-redundant storage (LRS)
    • Account Type: Storage (general purpose v1)
  • Test VM Disk
    Disk for the Test VM.
    • Disk Size: 128 GiB
    • Storage Type: Premium SSD LRS
    • Operating System: Windows

Database

  • Azure Cosmos DB
    Stores conversation history and metadata to improve quality.
    • Kind: GlobalDocumentDB
    • Database Account Offer Type: Standard
    • Capacity Mode: Provisioned throughput

Networking

  • Virtual Network
    AI Services VNet.
    • Address Space: 10.0.0.0/23

Address range is a suggestion, you should use what works for you.

  • Subnets
    Designate network segments in the AI Services VNet to organize and secure traffic.

    • Subnets:
      • ai-subnet
        10.0.0.0/26
      • app-services-subnet
        10.0.0.192/26
      • database-subnet
        10.0.1.0/26
      • app-int-subnet
        10.0.0.128/26
      • AzureBastionSubnet
        10.0.0.64/26

    The address ranges are suggestions; please adjust them to fit your specific network requirements.

  • Private Endpoints
    Enable private, secure access to Azure services via a virtual network.

    • Private Endpoints (PEs):
      • AI Search Private Endpoint
      • AI Services Private Endpoint
      • Azure OpenAI Private Endpoint
      • CosmosDB Private Endpoint
      • Data Ingestion Function App Private Endpoint
      • Frontend App Service Private Endpoint
      • Key Vault Private Endpoint
      • Orchestrator Function App Private Endpoint
      • Storage Account (Documents) Private Endpoint

  • Private DNS Zones
    Resolve private endpoints to private IPs within a virtual network.

    • Private DNS Zones:
      • App Service and Function Apps Private DNS
        privatelink.azurewebsites.net
      • AI Services Private DNS
        privatelink.cognitiveservices.azure.com
      • Azure OpenAI Private DNS
        privatelink.openai.azure.com
      • Storage Account (Documents) Private DNS
        privatelink.blob.core.windows.net
      • CosmosDB Private DNS
        privatelink.documents.azure.com
      • AI Search Private DNS
        privatelink.search.windows.net
      • Key Vault Private DNS
        privatelink.vaultcore.azure.net

  • Network Interfaces
    Provide connectivity to private endpoints and virtual machines within the AI Services VNet.

    • Interfaces:
      • AI Search PE's Network Interface
      • AI Services PE's Network Interface
      • Azure OpenAI PE's Network Interface
      • CosmosDB PE's Network Interface
      • Data Ingestion Function App PE's Network Interface
      • Frontend App Service PE's Network Interface
      • Key Vault PE's Network Interface
      • Orchestrator Function App PE's Network Interface
      • Storage Account (Documents) PE's Network Interface
      • Test Virtual Machine Network Interface

  • Bastion
    Enables private and secure access to the Test VM without exposing the VM directly to the internet.

    • Tier: Standard

  • Public IP
    Used by Bastion to enable secure access to the Test VM.

    • SKU: Standard
    • Tier: Regional

Installation Procedure

Before You Begin

Gather Necessary Information

  • Subscription Name
  • Resource Group Name
  • Azure Location Location
  • Azure Environment Name (ex: gpt-rag-dev, gpt-rag-poc, ...)

Note

Choose a region with sufficient service quotas. Commonly tested regions include eastus, eastus2, westus3.

Review these points for potential customizations

  • Resource names (optional)

You can customize the names of the resources being created. By default, azd automatically generates a unique name based on the environment name, subscription, and location. If you prefer to define specific names, refer to this page to learn how to customize each resource name. Before running the azd provisioning command, you must execute a command like the one below to apply these custom names to each resource you want to customize:

azd env set AZURE_RESOURCE_TYPE_NAME <yourResourceNameHere>

  • Reuse pre-existing resources (optional)

In some cases, you may want to use one or more pre-existing resources in your subscription instead of creating new ones. Our Bicep template allows you to do this. For detailed instructions on how this can be achieved, please take a look at the Bring Your Own Resources page.

  • Virtual Network Configuration (optional)

Adjust network addressing to avoid overlaps with existing VNets, as overlapping address ranges prevent direct connections via VNet peering, VPN gateways, or ExpressRoute. The default address ranges are:

Network Item Address Range
AI VNet 10.0.0.0/23
ai-subnet 10.0.0.0/26
app-services-subnet 10.0.0.192/26
database-subnet 10.0.1.0/26
app-int-subnet 10.0.0.128/26
AzureBastionSubnet 10.0.0.64/26

Each /26 subnet offers 59 usable IP addresses, as Azure reserves 5 IP addresses in each subnet. The /23 VNet allows 507 usable IP addresses. To customize address ranges, set the following environment variables:

Environment Variable Network Item
AZURE_VNET_ADDRESS AI VNet
AZURE_AI_SUBNET_PREFIX AI Subnet
AZURE_APP_INT_SUBNET_PREFIX App Internal Subnet
AZURE_APP_SERVICES_SUBNET_PREFIX App Services Subnet
AZURE_BASTION_SUBNET_PREFIX Bastion Subnet
AZURE_DATABASE_SUBNET_PREFIX Database Subnet

Set the desired address range with azd env command after azd int and before az provision.

Example: azd env set AZURE_AI_SUBNET_PREFIX 10.0.0.16/26.

  • DNS Customization (optional)

The Solution Accelerator will configure default DNS settings using Azure Private DNS Zones to resolve private endpoints within the resource group. This setup ensures seamless name resolution without requiring additional configuration.

However, if your organization has specific DNS requirements or prefers a different DNS setup, you have the flexibility to customize the DNS configurations. These customizations are not included in the automated installation process and will need to be configured separately.

Customization options include creating and managing your own private DNS zones, integrating with on-premises DNS servers, or setting up conditional forwarders to handle name resolution across various network environments. For detailed guidance on these customization strategies, please refer to our comprehensive Private Endpoint DNS Integration scenarios.

Installation Steps

Before starting the Zero Trust architecture deployment, review the prerequisites. Note that Node.js and Python are only required for the second phase, which you will perform on the VM created during the deployment. To deploy this architecture, follow these steps using Azure Developer CLI (azd) in your terminal:

1 Download the Repository

azd init -t azure/gpt-rag

Note: Add -b agentic if using the Agentic AutoGen-based orchestrator.

azd init -t azure/gpt-rag -b agentic

2 Enable network isolation

azd env set AZURE_NETWORK_ISOLATION true

2 Login to Azure:

2.a Azure Developer CLI:

azd auth login

2.b Azure CLI:

az login

3 Set environment variable values

Run the azd env set commands if you want to customize the installation as indicated in the previous section.

4 Start Building the infrastructure and components deployment:

azd provision

Tip

The regions we test most often are eastus, eastus2, westus3.

5 Use the Virtual Machine with the Bastion connection (created in step 4) to proceed with the deployment.

Log into the created VM with the user gptrag and authenticate with the password stored in the key vault, similar to the figure below:


Keyvault Login

6 Upon accessing Windows, install Powershell, as the other prerequisites are already installed on the VM.

7 Open the command prompt and run the following command to update azd to the latest version:

choco upgrade azd

After updating azd, simply close and reopen the terminal.

8 Create a new directory, for example, deploy then enter the created directory.

mkdir deploy  
cd deploy

To finalize the procedure, execute the subsequent commands in the command prompt to successfully complete the deployment:

azd init -t azure/gpt-rag  
azd auth login
az login
azd env refresh  
azd deploy

Important

Note: when running the azd init ... and azd env refresh, use the same environment name, subscription, and region used in the initial provisioning of the infrastructure.

Note: Add -b agentic if using the Agentic AutoGen-based orchestrator.

azd init -t azure/gpt-rag -b agentic

Done! Zero trust deployment is completed.

Optional Next Steps

9 Add app authentication. Watch this quick tutorial for step-by-step guidance.

10 Configure Azure Front Door to allow external access to your app only through Azure Front Door.

11. Configure Outbound Rules for External Services

The solution accelerator allows integration with other services to enhance the data sources used for grounding the solution. If you plan to connect to these external services as described in the AI Integration HUB section, you'll need to configure outbound rules for specific public endpoints, as shown in the table below.

Service Source Destination
Bing Custom Search Orchestrator Function App https://api.bing.microsoft.com
MS Graph API Data Ingestion Function App https://graph.microsoft.com

Tip

Use Azure API Management to secure API requests when connecting to external services.

Extending Application Components

After installing the solution accelerator, you may want to customize its application components. For example, you can modify the orchestrator for a specific scenario or adjust the data ingestion app for different chunk generation. See Extending App Components for details.