Deploy the MySQL resource provider on Azure Stack Hub

Use the MySQL Server resource provider to expose MySQL databases as an Azure Stack Hub service.

Only the resource provider should create items on servers that host SQL or MySQL. Items created on a host server that aren't created by the resource provider are unsupported, and might result in a mismatched state.

Prerequisites

If you already installed a resource provider, you likely completed the following prerequisites and can skip this section. Otherwise, complete these steps before continuing:

1. Register your Azure Stack Hub instance with Azure, if you haven't done so. You need to register your Azure Stack Hub instance with Azure because you'll be connecting to Azure and downloading items from the marketplace.

2. If you're not familiar with the Marketplace Management feature of the Azure Stack Hub administrator portal, review Download marketplace items from Azure and publish to Azure Stack Hub. The article walks you through the process of downloading items from Azure to the Azure Stack Hub marketplace. It covers both connected and disconnected scenarios. If your Azure Stack Hub instance is disconnected or partially connected, there are additional prerequisites to complete in preparation for installation.

3. Update your Microsoft Entra home directory. Starting with build 1910, you must register a new application in your home directory tenant. This app enables Azure Stack Hub to successfully create and register newer resource providers (like Event Hubs and others) with your Microsoft Entra tenant. This action is required after upgrading to build 1910 or newer. If you don't complete this step, marketplace resource provider installations fail.

   • After you successfully update your Azure Stack Hub instance to 1910 or greater, follow the instructions for cloning/downloading the Azure Stack Hub Tools repository.
   • Then, follow the instructions for Updating the Azure Stack Hub Microsoft Entra Home Directory (after installing updates or new Resource Providers).

MySQL Server resource provider prerequisites

• You need a computer and account that can access:

  • the Azure Stack Hub administrator portal.
  • the privileged endpoint (needed only when you're deploying MySQL Server resource provider V1 or upgrading from MySQL Server resource provider V1 to MySQL Server resource provider V2).
  • the Azure Resource Manager admin endpoint, https://adminmanagement.region.<fqdn>, where <fqdn> is your fully qualified domain name.
  • the Internet, if your Azure Stack Hub was deployed to use Microsoft Entra ID as your identity provider.

• Download the supported version of MySQL resource provider binary according to the version mapping table in the following section. For V2 MySQL resource provider, download the marketplace item to Azure Stack Hub.

  Supported Azure Stack Hub version	MySQL RP version	Windows Server that RP service is running on
  2206, 2301, 2306, 2311	MySQL RP version 2.0.13.x	Microsoft AzureStack Add-on RP Windows Server 1.2009.0
  2108, 2206	MySQL RP version 2.0.6.x	Microsoft AzureStack Add-on RP Windows Server 1.2009.0

• Make sure that the required Windows Server VM is downloaded to Azure Stack Hub Marketplace. Manually download the image according to the version mapping table if needed.

• Ensure datacenter integration prerequisites are met:

  Prerequisite	Reference
  Conditional DNS forwarding is set correctly.	Azure Stack Hub datacenter integration - DNS
  Inbound ports for resource providers are open.	Azure Stack Hub datacenter integration - Publish endpoints
  PKI certificate subject and SAN are set correctly.	Azure Stack Hub deployment mandatory PKI prerequisitesAzure Stack Hub deployment PaaS certificate prerequisites

• Prepare the certificate. (For integrated systems installations only.)

  • You must provide the SQL PaaS PKI certificate described in the optional PaaS certificates section of Azure Stack Hub deployment PKI requirements. The Subject Alternative Name (SAN) must adhere to the following naming pattern: CN=*.dbadapter.<region>.<fqdn>, with password protected.
  • When deploying MySQL Server resource provider V1, place the .pfx file in the location specified by the DependencyFilesLocalPath parameter. Don't provide a certificate for ASDK systems.
  • When deploying MySQL Server resource provider V2, prepare the certificate for the following installation steps.

Disconnected scenario

When deploying MySQL Server resource provider V2 in a disconnected scenario, follow the download marketplace items to Azure Stack Hub instruction to download the MySQL Server resource provider item and Add-on RP Windows Server item to your Azure Stack Hub environment.

When deploying MySQL Server resource provider V1 in a disconnected scenario, complete the following steps to download the required PowerShell modules and register the repository manually.

1. Sign in to a computer with internet connectivity and use the following scripts to download the PowerShell modules.

   Import-Module -Name PowerShellGet -ErrorAction Stop
   Import-Module -Name PackageManagement -ErrorAction Stop
   
   # path to save the packages, c:\temp\azs1.6.0 as an example here
   $Path = "c:\temp\azs1.6.0"
   

2. Depending on the version of resource provider that you are deploying, run one of the scripts.

   # for resource provider version >= 1.1.93.0
   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureRM -Path $Path -Force -RequiredVersion 2.5.0
   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $Path -Force -RequiredVersion 1.8.2
   

   # for resource provider version <= 1.1.47.0
   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureRM -Path $Path -Force -RequiredVersion 2.3.0
   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $Path -Force -RequiredVersion 1.6.0
   

3. Then you copy the downloaded packages to a USB device.

4. Sign in to the disconnected workstation and copy the packages from the USB device to a location on the workstation.

5. Register this location as a local repository.

   # requires -Version 5
   # requires -RunAsAdministrator
   # requires -Module PowerShellGet
   # requires -Module PackageManagement
   
   $SourceLocation = "C:\temp\azs1.6.0"
   $RepoName = "azs1.6.0"
   
   Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted
   
   New-Item -Path $env:ProgramFiles -name "SqlMySqlPsh" -ItemType "Directory" 
   

Deploy the MySQL resource provider V2

If you are upgrading from a V1 version, refer to the doc Update the MySQL Server resource provider.

Start installation

1. If you didn't already, sign in to the Azure Stack Hub administrator portal, select Marketplace Management on the left, and select Resource providers.

2. After downloading the MySQL resource provider and other required software, Marketplace Management shows the "MySQL Server resource provider" packages with a status of "Not Installed". You might see other packages that show a status of "Downloaded".

   

3. Select the row you want to install. The MySQL Server resource provider install package page shows a blue banner across the top. Select the banner to start the installation.

Install prerequisites

1. Next, you're transferred to the install page. Select Install Prerequisites to begin the installation process.

2. Wait until the installation of prerequisites succeeds. You should see a green checkmark next to Install prerequisites before proceeding to the next step.

Prepare secrets

1. Under the 2. Prepare secrets step, select Add certificate. The Add a certificate panel appears.

2. Select the browse button on Add a certificate, just to the right of the certificate filename field. Select the .pfx certificate file you procured when completing the prerequisites.

3. Enter the password you provided to create a secure string for SQL Server resource provider SSL Certificate. Then select Add.

Configure and install resource provider

1. When the installation of the certificate succeeds, you see a green checkmark next to Prepare secrets. Now select the Configure + Install button next to 3 Install resource provider.

2. Next, provide an Azure Stack Hub Blob URI for MySQL Connector.

   • Review the GPL license of MySQL Connector here and download version 8.0.21 to a local folder.

   • Create a storage account with your default operator subscription, and create a container with the access level "Blob" or "Container".

   • Upload the mysql-connector-net-8.0.21.msi file from your local folder to the newly created storage container.

   Important

   Make sure the version of the MySQL Connector is 8.0.21.

   • Copy the blob URI.

   • Go back to the MySQL RP configuration page. Paste the blob URI (for example, https://<storageAccountName>.blob.<region>.<FQDN>/<containerName>/mysql-connector-net-8.0.21.msi) to the text box and select OK.

3. Next, you see the following page, which indicates that MySQL resource provider is being installed.

4. Wait for the installation complete notification. This process usually takes one or more hours, depending on your Azure Stack Hub type.

5. Verify that the installation of MySQL Server resource provider succeeded by returning to the Marketplace Management, Resource Providers page. The status of MySQL Server resource provider should show "Installed".

Deploy the SQL resource provider V1

After you complete all the prerequisites, run the self-extractor to extract the downloaded installation package to a temporary directory. Run the DeployMySqlProvider.ps1 script from a computer that can access both the Azure Stack Hub Azure Resource Manager admin endpoint and the privileged endpoint, to deploy the MySQL resource provider. The DeployMySqlProvider.ps1 script is extracted as part of the MySQL resource provider installation files that you downloaded for your version of Azure Stack Hub.

To deploy the MySQL resource provider, open a new elevated PowerShell window (not PowerShell ISE) and change to the directory where you extracted the MySQL resource provider binary files.

Run the DeployMySqlProvider.ps1 script, which completes the following tasks:

• Uploads the certificates and other artifacts to a storage account on Azure Stack Hub.
• Publishes gallery packages so that you can deploy MySQL databases by using the gallery.
• Publishes a gallery package for deploying hosting servers.
• Deploys a VM by using the Windows Server 2016 core image or Microsoft AzureStack Add-on RP Windows Server image you downloaded, and then installs the MySQL resource provider.
• Registers a local DNS record that maps to your resource provider VM.
• Registers your resource provider with the local Azure Resource Manager for the operator account.

DeployMySqlProvider.ps1 parameters

Specify these parameters from the command line. If you don't specify them, or if any parameter validation fails, the script prompts you to provide the required parameters.

Deploy the MySQL resource provider by using a custom script

If you're deploying the MySQL resource provider version 1.1.47.0 or later, the deployment script automatically downloads and installs the necessary PowerShell modules for you to path C:\Program Files\SqlMySqlPsh.

# Install the AzureRM.Bootstrapper module, set the profile and install the AzureStack module
# Note that this might not be the most currently available version of Azure Stack Hub PowerShell
Install-Module -Name AzureRm.BootStrapper -Force
Use-AzureRmProfile -Profile 2018-03-01-hybrid -Force
Install-Module -Name AzureStack -RequiredVersion 1.6.0

To eliminate any manual configuration when deploying the resource provider, customize the following script. Change the default account information and passwords as needed for your Azure Stack Hub deployment.

# Use the NetBIOS name for the Azure Stack Hub domain. On the Azure Stack Hub SDK, the default is AzureStack but could have been changed at install time.
$domain = "AzureStack"  

# For integrated systems, use the IP address of one of the ERCS VMs.
$privilegedEndpoint = "AzS-ERCS01"

# Provide the Azure environment used for deploying Azure Stack Hub. Required only for Azure AD deployments. Supported environment names are AzureCloud, AzureUSGovernment, or AzureChinaCloud. 
$AzureEnvironment = "<EnvironmentName>"

# Point to the directory where the resource provider installation files were extracted.
$tempDir = 'C:\TEMP\MYSQLRP'

# The service admin account (can be Azure Active Directory or Active Directory Federation Services).
$serviceAdmin = "admin@mydomain.onmicrosoft.com"
$AdminPass = ConvertTo-SecureString 'P@ssw0rd1' -AsPlainText -Force
$AdminCreds = New-Object System.Management.Automation.PSCredential ($serviceAdmin, $AdminPass)

# Set the credentials for the new resource provider VM local admin account
$vmLocalAdminPass = ConvertTo-SecureString 'P@ssw0rd1' -AsPlainText -Force
$vmLocalAdminCreds = New-Object System.Management.Automation.PSCredential ("mysqlrpadmin", $vmLocalAdminPass)

# And the cloudadmin credential required for privileged endpoint access.
$CloudAdminPass = ConvertTo-SecureString 'P@ssw0rd1' -AsPlainText -Force
$CloudAdminCreds = New-Object System.Management.Automation.PSCredential ("$domain\cloudadmin", $CloudAdminPass)

# Change the following as appropriate.
$PfxPass = ConvertTo-SecureString 'P@ssw0rd1' -AsPlainText -Force

# For version 1.1.47.0 or later, the PowerShell modules used by the RP deployment are placed in C:\Program Files\SqlMySqlPsh,
# The deployment script adds this path to the system $env:PSModulePath to ensure correct modules are used.
$rpModulePath = Join-Path -Path $env:ProgramFiles -ChildPath 'SqlMySqlPsh'
$env:PSModulePath = $env:PSModulePath + ";" + $rpModulePath

# Change to the directory folder where you extracted the installation files. Don't provide a certificate on ASDK!
. $tempDir\DeployMySQLProvider.ps1 `
    -AzCredential $AdminCreds `
    -VMLocalCredential $vmLocalAdminCreds `
    -CloudAdminCredential $cloudAdminCreds `
    -PrivilegedEndpoint $privilegedEndpoint `
    -AzureEnvironment $AzureEnvironment `
    -DefaultSSLCertificatePassword $PfxPass `
    -DependencyFilesLocalPath $tempDir\cert `
    -AcceptLicense

When the resource provider installation script finishes, refresh your browser to make sure you can see the latest updates and close the current PowerShell session.

Verify the V1 deployment by using the Azure Stack Hub portal

1. Sign in to the administrator portal as the service admin.
2. Select Resource Groups.
3. Select the system.<location>.mysqladapter resource group.
4. On the summary page for Resource group Overview, there should be no failed deployments.
5. Finally, select Virtual machines in the administrator portal to verify that the MySQL resource provider VM was successfully created and is running.

Important configuration for Microsoft Entra ID

If your Azure Stack Hub is using Microsoft Entra ID as an identity provider, make sure the VM that installs MySQL Server resource provider has outbound internet connectivity.

Next steps

Add hosting servers