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. The MySQL resource provider runs as a service on a Windows Server 2016 Server Core virtual machine (for adapter version <= 1.1.47.0>) or a special Add-on RP Windows Server (for adapter version >= 1.1.93.0).

Important

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 may result in a mismatched state.

Prerequisites

There are several prerequisites that need to be in place before you can deploy the Azure Stack Hub MySQL resource provider:

  • You'll need a computer and account that can access:

    • the Azure Stack Hub administrator portal.
    • the privileged endpoint.
    • the Azure Resource Manager admin endpoint, https://management.region.<fqdn>, where <fqdn> is your fully qualified domain name (or https://management.local.azurestack.external if using the ASDK)
    • the Internet, if your Azure Stack Hub was deployed to use Azure Active Directory (AD) as your identity provider.
  • If you haven't already, register Azure Stack Hub with Azure so you can download Azure Marketplace items.

  • Add the required Windows Server VM to Azure Stack Hub Marketplace.

    • For MySQL RP version <= 1.1.47.0, download the Windows Server 2016 Datacenter - Server Core image.
    • For MySQL RP version >= 1.1.93.0, download the Microsoft AzureStack Add-On RP Windows Server image. This Windows Server version is specialize for Azure Stack Add-On RP Infrastructure and it is not visible to the tenant marketplace.
  • Download the supported version of MySQL resource provider binary according to the version mapping table below. Run the self-extractor to extract the downloaded contents to a temporary directory.

    Supported Azure Stack Hub version MySQL RP version Windows Server that RP service is running on
    2008, 2005 MySQL RP version 1.1.93.1 Microsoft AzureStack Add-on RP Windows Server
    2005, 2002, 1910 MySQL RP version 1.1.47.0 Windows Server 2016 Datacenter - Server Core
    1908 MySQL RP version 1.1.33.0 Windows Server 2016 Datacenter - Server Core

Note

To deploy the MySQL provider on a system that doesn't have internet access, copy the mysql-connector-net-6.10.5.msi file to a local path. Provide the path name using the DependencyFilesLocalPath parameter.

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"
  1. 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
  1. Then you copy the downloaded packages to a USB device.

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

  3. 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" 

Certificates

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. Place the .pfx file in the location specified by the DependencyFilesLocalPath parameter. Don't provide a certificate for ASDK systems.

Deploy the resource provider

After you've completed all of the prerequisites, you can 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.

Important

Before deploying the resource provider, review the release notes to learn about new functionality, fixes, and any known issues that could affect your deployment.

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.

Important

We strongly recommend using Clear-AzureRmContext -Scope CurrentUser and Clear-AzureRmContext -Scope Process to clear the cache before running the deployment or update script.

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 using the gallery.
  • Publishes a gallery package for deploying hosting servers.
  • Deploys a VM 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.

Note

When the MySQL resource provider deployment starts, the system.local.mysqladapter resource group is created. It may take up to 75 minutes to finish the deployments required to this resource group. You should not place any other resources in the system.local.mysqladapter resource group.

DeployMySqlProvider.ps1 parameters

You can specify these parameters from the command line. If you don't, or if any parameter validation fails, you're prompted to provide the required parameters.

Parameter name Description Comment or default value
CloudAdminCredential The credential for the cloud administrator, necessary for accessing the privileged endpoint. Required
AzCredential The credentials for the Azure Stack Hub service admin account. Use the same credentials that you used for deploying Azure Stack Hub. The script will fail if the account you use with AzCredential requires multi-factor authentication (MFA). Required
VMLocalCredential The credentials for the local administrator account of the MySQL resource provider VM. Required
PrivilegedEndpoint The IP address or DNS name of the privileged endpoint. Required
AzureEnvironment The Azure environment of the service admin account used for deploying Azure Stack Hub. Required only for Azure AD deployments. Supported environment names are AzureCloud, AzureUSGovernment, or if using a China Azure AD, AzureChinaCloud. AzureCloud
DependencyFilesLocalPath For integrated systems only, your certificate .pfx file must be placed in this directory. For disconnected environments, download mysql-connector-net-6.10.5.msi to this directory. You can optionally copy one Windows Update MSU package here. Optional (mandatory for integrated systems or disconnected environments)
DefaultSSLCertificatePassword The password for the .pfx certificate. Required
MaxRetryCount The number of times you want to retry each operation if there's a failure. 2
RetryDuration The timeout interval between retries, in seconds. 120
Uninstall Removes the resource provider and all associated resources (see the following notes). No
DebugMode Prevents automatic cleanup on failure. No
AcceptLicense Skips the prompt to accept the GPL license. https://www.gnu.org/licenses/old-licenses/gpl-2.0.html

Deploy the MySQL resource provider using a custom script

If you are deploying the MySQL resource provider version 1.1.33.0 or previous versions, you need to install specific versions of AzureRm.BootStrapper and Azure Stack Hub modules in PowerShell. If you are deploying the MySQL resource provider version 1.1.47.0 or later, the deployment script will automatically download and install 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

Note

In disconnected scenario, you need to download the required PowerShell modules and register the repository manually as a prerequisite.

To eliminate any manual configuration when deploying the resource provider, you can 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 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.

Next steps

Add hosting servers