Skip to content

Latest commit

 

History

History
174 lines (115 loc) · 14.5 KB

deployment.md

File metadata and controls

174 lines (115 loc) · 14.5 KB

Deploying IA Accelerator to Azure

⚠️ IMPORTANT: Please ensure you have met the Azure account requirements before continuing.

Follow these steps to get the accelerator up and running in a subscription of your choice. Note that there may be specific instructions for deploying to Azure Government or other Sovereign regions.

If you prefer to have a more guided experience, you may choose to view the click-through deployment guide for this accelerator.

Development Environment Configuration

The deployment process for the IA Accelerator, uses a concept of Developing inside a Container to containerize all the necessary pre-requisite component without requiring them to be installed on the local machine. The environment you will work in will be created using a development container or dev container hosted on a virtual machine using GitHub Codespaces.

Begin by first forking the Information Assistant repository into your own repository. This can be useful for managing any changes you may require for your local environment. It will also enable you to accept and merge changes from the Information Assistant repo as future releases and hotfixes are made available.

To fork the repo simply click the Fork button at the top of the Information Assistant Repo page and follow the steps to set up your new fork. Fork the Information Assistant Repo

Once you have forked the repo, you can then use the following button to open the Information Assistant GitHub Codespaces. You will need to select your forked repo and the location for your GitHub Codespaces to run in.

Open in GitHub Codespaces

Begin by setting up your own GitHub Codespaces using our Developing in Codespaces documentation.

If you want to configure your local desktop for development container or you do not have access to GitHub Codespaces, follow our Configuring your System for Development Containers guide. More information can be found at Developing inside a Container.

Once you have the completed setting up a GitHub Codespaces, please move on to the Sizing Estimation step.

Sizing Estimator

The IA Accelerator needs to be sized appropriately based on your use case. Please review our Sizing Estimator to help find the configuration that fits your needs.

To change the size of components deployed, make changes in the Main Bicep file.

Once you have completed the Sizing Estimator and sized your deployment appropriately, please move on to the Configuring your Environment step.

Configure ENV files

You now need to set up your local environment variables file in preparation for deployment.

Inside your Development environment (GitHub Codespaces or Container), do the following:

  1. Open scripts/environments and copy local.env.example to local.env.
  2. Then open local.env and update values as needed:
Variable Required Description
LOCATION Yes The location (West Europe is the default). The BICEP templates use this value. To get a list of all the current Azure regions you can run az account list-locations -o table. The value here needs to be the Name value and not Display Name.
WORKSPACE Yes The workspace name (use something simple and unique to you). This will appended to infoasst-????? as the name of the resource group created in your subscription.
SUBSCRIPTION_ID Yes The GUID that represents the Azure Subscription you want the Accelerator to be deployed into. This can be obtained from the Subscription blade in the Azure Portal.
TENANT_ID Yes The GUID that represents the Azure Active Directory Tenant for the Subscription you want the accelerator to be deployed into. This can be obtained from the Tenant Info blade in the Azure Portal.
IS_USGOV_DEPLOYMENT Yes Defaults to false. This value should be set to true only if you are deploying to one of the US Sovereign regions. Find more information on Sovereign Deployment
REQUIRE_WEBSITE_SECURITY_MEMBERSHIP Yes Use this setting to determine whether a user needs to be granted explicit access to the website via an Azure AD Enterprise Application membership (true) or allow the website to be available to anyone in the Azure tenant (false). Defaults to false. If set to true, A tenant level administrator will be required to grant the implicit grant workflow for the Azure AD App Registration manually.
SKIP_PLAN_CHECK No If this value is set to 1, then the BICEP deployment will not stop to allow you to review the planned changes. The default value is 0 in the scripts, which will allow the deployment to stop and confirm you accept the proposed changes before continuing.
USE_EXISTING_AOAI Yes Defaults to false. Set this value to "true" if you want to use an existing Azure Open AI service instance in your subscription. This can be useful when there are limits to the number of AOAI instances you can have in one subscription. When the value is set to "false" and BICEP will create a new Azure Open AI service instance in your resource group.
AZURE_OPENAI_RESOURCE_GROUP No If you have set USE_EXISTING_AOAI to "true" then use this parameter to provide the name of the resource group that hosts the Azure Open AI service instance in your subscription.
AZURE_OPENAI_SERVICE_NAME No If you have set USE_EXISTING_AOAI to "true" then use this parameter to provide the name of the Azure Open AI service instance in your subscription.
AZURE_OPENAI_SERVICE_KEY No If you have set USE_EXISTING_AOAI to "true" then use this parameter to provide the Key for the Azure Open AI service instance in your subscription.
AZURE_OPENAI_CHATGPT_DEPLOYMENT No If you have set USE_EXISTING_AOAI to "true" then use this parameter to provide the name of a deployment of the "gpt-35-turbo" model in the Azure Open AI service instance in your subscription.
USE_AZURE_OPENAI_EMBEDDINGS Yes Defaults to "true". When set to "true" this value indicates to Information Assistant to use Azure OpenAI models for embedding text values. If set to "false", Information Assistant will use the open source language model that is provided in the values below.
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME No If you have set USE_AZURE_OPENAI_EMBEDDINGS to "true" then use this parameter to provide the name of a deployment of the "text-embedding-ada-002" model in the Azure Open AI service instance in your subscription.
OPEN_SOURCE_EMBEDDING_MODEL No A valid open source language model that Information Assistant will use for text embeddings. The model needs to be downloadable and available through Sentence Transformer. This setting will be used when USE_AZURE_OPENAI_EMBEDDINGS is set to "false".
OPEN_SOURCE_EMBEDDING_MODEL_VECTOR_SIZE No When specifying an open source language model the vector size the model's embedding produces must be specified so that the Azure AI Search hybrid index's vector columns can be set to the matching size. This setting will be used when USE_AZURE_OPENAI_EMBEDDINGS is set to "false".
AZURE_OPENAI_CHATGPT_MODEL_NAME No This can be used to select a different GPT model to be deployed to Azure OpenAI when the default (gpt-35-turbo-16k) isn't available to you.
AZURE_OPENAI_CHATGPT_MODEL_VERSION No This can be used to select a specific version of the GPT model above when the default (0613) isn't available to you.
AZURE_OPENAI_EMBEDDINGS_MODEL_NAME No This will display in the Info panel in the UX if you don't have access to the resource group where the Azure OpenAI embeddings models are deployed. See local.env.example for specific guidance.
AZURE_OPENAI_EMBEDDINGS_MODEL_VERSION No This will display in the Info panel in the UX if you don't have access to the resource group where the Azure OpenAI embeddings models are deployed. See local.env.example for specific guidance.
AZURE_OPENAI_CHATGPT_MODEL_CAPACITY Yes This value can be used to provide the provisioned capacity of the GPT model deployed to Azure OpenAI when you have reduced capacity.
CHAT_WARNING_BANNER_TEXT No Defaults to "". Provide a value in this parameter to display a header and footer to the UX of Information Assistant with the included warning banner text.
DEFAULT_LANGUAGE Yes Use the parameter to specify the matching ENV file located in the scripts/environments/languages folder. You can then use this file to customize the language settings of the search index, search skillsets, and Azure OpenAI prompts. See Configuring your own language ENV file more information.
ENABLE_CUSTOMER_USAGE_ATTRIBUTION
CUSTOMER_USAGE_ATTRIBUTION_ID
No By default, ENABLE_CUSTOMER_USAGE_ATTRIBUTION is set to true. The CUA GUID which is pre-configured will tell Microsoft about the usage of this software. Please see Data Collection Notice for more information.

You may provide your own CUA GUID by changing the value in CUSTOMER_USAGE_ATTRIBUTION_ID. Ensure you understand how to properly notify your customers by reading https://learn.microsoft.com/en-us/partner-center/marketplace/azure-partner-customer-usage-attribution#notify-your-customers.

To disable data collection, set ENABLE_CUSTOMER_USAGE_ATTRIBUTION to false.
ENABLE_DEV_CODE No Defaults to false. It is not recommended to enable this flag, it is for development testing scenarios only.
APPLICATION_TITLE No Defaults to "". Providing a value for this parameter will replace the Information Assistant's title in the black banner at the top of the UX.

Log into Azure using the Azure CLI

You can use the bash prompt in your GitHub Codespaces to issue the following commands:

    az login

This will launch a browser session where you can complete you login. If you get an error on this step, we suggest you use the device code option for login.

NOTICE: if your organization requires managed devices, ensure that you are running the GitHub Codespaces from your managed device's VS Code installation. For more information, please see the Developing in a Codespace documentation.

Next from the bash prompt run:

    az account show

The output here should show that you're logged into the intended Azure subscription. If this isn't showing the right subscription then you can list all the subscriptions you have access to with:

    az account list

If you're a part of multiple tenants, ensure you're in the right tenant by setting the tenantID

    az login --tenant tenantID

From this output, grab the Subscription ID of the subscription you intend to deploy to and run:

    az account set --subscription mysubscriptionID

Deploy and Configure Azure resources

Now that your GitHub Codespaces/Container and ENV files are configured, it is time to deploy the Azure resources. This is done using a Makefile.

To deploy everything run the following command from the GitHub Codespaces/Dev Container prompt:

    make deploy

This will deploy the infrastructure and the application code.

This command can be run as many times as needed in the event you encounter any errors. A set of known issues and their workarounds that we have found can be found in Known Issues

Additional Information

For a full set of Makefile rules, run make help.

vscode ➜ /workspaces/<accelerator> (main ✗) $ make help
help                         Show this help
deploy                       Deploy infrastructure and application code
build                        Build application code
infrastructure               Deploy infrastructure
extract-env                  Extract infrastructure.env file from BICEP output
deploy-webapp                Deploys the web app code to Azure App Service
deploy-functions             Deploys the function code to Azure Function Host
deploy-enrichments           Deploys the web app code to Azure App Service
deploy-search-indexes        Deploy search indexes
extract-env-debug-webapp     Extract infrastructure.debug.env file from BICEP output
extract-env-debug-functions  Extract local.settings.json to debug functions from BICEP output
functional-tests             Run functional tests to check the processing pipeline is working

Configure authentication and authorization

If you have chosen to enable authentication and authorization for your deployment by setting the environment variable REQUIRE_WEBSITE_SECURITY_MEMBERSHIP to true, you will need to configure it at this point. Please see Known Issues section for guidance on how to configure.

NOTICE: If you haven't enabled this, but your Tenant requires this, you may still need to configure as noted above.

Find your deployment URL

Once deployed, you can find the URL of your installation by:

  1. Browse to your new Resource Group at https://portal.azure.com and locate the "App Service" with the name that starts with "infoasst-web" Location of App Service in Portal

  2. After clicking on the App Service, you will see the "Default domain" listed. This is the link to your installation. Default Domain of App Service in Portal

Next steps

At this point deployment is complete. Please go to the Using the IA Accelerator for the first time section and complete the following steps.

Additional Considerations for a Production Adoption

There are considerations for adopting the Information Assistant (IA) accelerator into a production environment. See this documentation.

Need Help?

To review logs try Using the Workbook Template

If you need assistance with deployment or configuration of this accelerator, please leverage the Discussion forum in this repository, or reach out to your Microsoft Unified Support account manager.