sdk/python/resources/connections/connections.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Managing Azure Machine Learning Workspace Connections\n",
    "\n",
    "**Requirements** - In order to benefit from this tutorial, you will need:\n",
    "- A basic understanding of Machine Learning\n",
    "- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F)\n",
    "- A python environment\n",
    "- Installed Azure Machine Learning Python SDK v2 - [install instructions](../../README.md) - check the getting started section\n",
    "\n",
    "**Learning Objectives** - By the end of this tutorial, you should be able to:\n",
    "- Create Azure Machine Learning workspace Connection from Python SDK\n",
    "\n",
    "**Motivations** - Azure Machine Learning Workspace Connection provides secure and trustworthy way to access external resources from AML."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. Connect to Azure Machine Learning Workspace\n",
    "\n",
    "The [workspace](https://docs.microsoft.com/en-us/azure/machine-learning/concept-workspace) is the top-level resource for Azure Machine Learning, providing a centralized place to work with all the artifacts you create when you use Azure Machine Learning. In this section we will connect to the workspace in which the compute will be created.\n",
    "\n",
    "## 1.1. Import the required libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import required libraries\n",
    "import os\n",
    "from azure.ai.ml import MLClient\n",
    "from azure.ai.ml.entities import WorkspaceConnection\n",
    "from azure.identity import DefaultAzureCredential"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.2. Configure workspace details and get a handle to the workspace\n",
    "\n",
    "To connect to a workspace, we need identifier parameters - a subscription, resource group and workspace name. We will use these details in the `MLClient` from `azure.ai.ml` to get a handle to the required Azure Machine Learning workspace. We use the default [default azure authentication](https://docs.microsoft.com/en-us/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python) for this tutorial. Check the [configuration notebook](../../jobs/configuration.ipynb) for more details on how to configure credentials and connect to a workspace."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Enter details of your AML workspace\n",
    "subscription_id = \"<SUBSCRIPTION_ID>\"\n",
    "resource_group = \"<RESOURCE_GROUP>\"\n",
    "workspace = \"<AML_WORKSPACE_NAME>\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get a handle to the workspace\n",
    "from azure.ai.ml import MLClient\n",
    "from azure.identity import DefaultAzureCredential\n",
    "\n",
    "ml_client = MLClient(\n",
    "    DefaultAzureCredential(), subscription_id, resource_group, workspace\n",
    ")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2 Create Workspace Connection\n",
    "An Azure Machine Learning workspace is secure and trustworthy way for AML users to store credentials to access external resources from AML\n",
    "\n",
    "Workspace Connection can be created using the `WorkspaceConnection` class. This class accepts the following key parameters:\n",
    "- `name` - Name of connection.\n",
    "- `target` - The URL or ARM resource ID of the external resource.\n",
    "- `credentials` - The credentials for authenticating to the external resource.\n",
    "- `type` - The category of external resource for this connection.\n",
    "\n",
    "## 2.1 Create a Workspace Connection\n",
    "In this example we will create a **Workspace Connection** to an [**Azure Container Registry**]([ACR](https://azure.microsoft.com/en-us/products/container-registry/)) and use **username/password** credentials\n",
    "\n",
    "Once connection is successfully created you can reference images from [Azure Container Registry]([ACR](https://azure.microsoft.com/en-us/products/container-registry/)) in AML environment and AML will automatically fetch these credentials while building the environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from azure.ai.ml.entities import WorkspaceConnection\n",
    "from azure.ai.ml.entities import UsernamePasswordConfiguration\n",
    "\n",
    "# fetching secrets from env var to secure access, these secrets can be set outside or source code\n",
    "acr_username = os.environ[\"ACR_USERNAME\"]\n",
    "acr_password = os.environ[\"ACR_PASSWORD\"]\n",
    "\n",
    "credentials = UsernamePasswordConfiguration(\n",
    "    username=acr_username, password=acr_password\n",
    ")\n",
    "\n",
    "ws_connection = WorkspaceConnection(\n",
    "    name=\"<workspace_connection_name>\",\n",
    "    target=\"<acr_url>\",  # testacr.azurecr.io,\n",
    "    type=\"container_registry\",\n",
    "    credentials=credentials,\n",
    ")\n",
    "\n",
    "ml_client.connections.create_or_update(ws_connection)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.2 Create a Workspace Connection for private feeds\n",
    "In this example we will create a **Workspace Connection** to **private git feed** and use **Personal Access Token (PAT)** credentials\n",
    "\n",
    "Once connection is successfully created you can reference feeds from **private git feed** in AML environment and AML will automatically fetch these credentials while building the environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from azure.ai.ml.entities import WorkspaceConnection\n",
    "from azure.ai.ml.entities import PatTokenConfiguration\n",
    "\n",
    "# fetching secrets from env var to secure access, these secrets can be set outside or source code\n",
    "git_pat = os.environ[\"GIT_PAT\"]\n",
    "\n",
    "credentials = PatTokenConfiguration(pat=git_pat)\n",
    "\n",
    "ws_connection = WorkspaceConnection(\n",
    "    name=\"<workspace_connection_name>\",\n",
    "    target=\"<git_url>\",\n",
    "    type=\"git\",\n",
    "    credentials=credentials,\n",
    ")\n",
    "\n",
    "ml_client.connections.create_or_update(ws_connection)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.3 Create a Workspace Connection for private python feeds\n",
    "In this example we will create a **Workspace Connection** to **private python feed** and use **SAS Token** credentials\n",
    "\n",
    "Once connection is successfully created you can reference feeds from **private python feed** in AML environment and AML will automatically fetch these credentials while building the environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from azure.ai.ml.entities import WorkspaceConnection\n",
    "from azure.ai.ml.entities import SasTokenConfiguration\n",
    "\n",
    "# fetching secrets from env var to secure access, these secrets can be set outside or source code\n",
    "python_feed_sas = os.environ[\"PYTHON_FEED_SAS\"]\n",
    "\n",
    "credentials = SasTokenConfiguration(sas_token=python_feed_sas)\n",
    "\n",
    "ws_connection = WorkspaceConnection(\n",
    "    name=\"<workspace_connection_namename>\",\n",
    "    target=\"<python_feed_url>\",\n",
    "    type=\"python_feed\",\n",
    "    credentials=credentials,\n",
    ")\n",
    "\n",
    "ml_client.connections.create_or_update(ws_connection)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10 - SDK V2",
   "language": "python",
   "name": "python310-sdkv2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.12"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "4c439adbb519efcfe168a123b2556c8f2fe0361cd3d8ea3ca94917232d9ad346"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}