Maintaining your Teams Connector deployment

After you have installed and configured your Teams Connector there are several maintenance tasks you may need to perform, such as adding extra Conferencing Nodes, changing your call capacity or upgrading the platform to the latest software version.

This topic covers the following maintenance tasks:

Modifying the Teams Connector's configuration

If you need to change the configuration on the Teams Connector after it has been deployed, you must make the necessary changes to the variables in your initialization script and then redeploy it using the new configuration, as described below. Configuration changes that require redeployment include:

  • Changing the pool name or node FQDNs of the associated Conferencing Nodes (the name referenced by the $PxNodeFqdns variable in the initialization script).
  • Enabling RDP access to the Teams Connector instances (from any addresses specified in the $PxMgmtSrcAddrPrefixes installation variable).
  • Enabling support for dedicated hosting plans for Azure functions and VNet integration.

Note that you do not need to redeploy the Teams Connector if you need to change the Azure Network Security Group configuration, for example to add the IP address of a new Conferencing Node, update its certificate, or if you need to modify the number of Teams Connector instances.

Upgrading the Teams Connector to the latest software

If you are not yet currently using a blue-green deployment strategy, but want to start using one as part of the upgrade process, see Moving from an existing single Teams Connector to a blue-green deployment strategy.

When upgrading the Teams Connector to version 35, you should redeploy the deployment which is currently not in use / decommissioned — for example, after initially using the blue system you will redeploy the green system. You should use your original variables initialization script (blue or green as appropriate, although you may apply any configuration changes, if required), and with the latest application software files and v35 redeployment script, as described here.

After completing and testing the upgraded system e.g. green, you can then switch over to that system as your live environment, and then decommission the system that was previously in use e.g. blue.

Pexip has produced the following tutorial video that demonstrates the upgrade process:

If you are using, and want to continue to use, a single Teams Connector, you can still follow the upgrade process described here. In this case you do not have to decide between using blue or green scripts or systems as you have only one system to update. Your system will be upgraded after you have completed running the redeploy script — you can ignore the subsequent sections on testing the new software and switching over to the new software.

Using CBA with version 35

Certificate-based authentication (CBA) is now the default method to authenticate the Teams Connector CVI application towards MS Graph. You can still use the previous password-based authentication method, but we plan to deprecate it in a future release, thus we recommend using CBA for new installations, or migrating to CBA as soon as practicable when upgrading existing deployments.

New/modified upgrade steps for version 35

There are no changes to the installation variables or the installation script for version 35 (except for the beginning of the install script which, as usual, performs the script to software version number comparison).

However, the primary documented installation and upgrade process has been modified to reflect a blue-green deployment strategy, which is our recommended approach. This means that the installation process now has a "blue" and a "green" installation script (the "green" script omits the tasks that do not require duplication). The redeploy script is unchanged.

The required versions of the PowerShell modules that need to be installed have been updated, as listed below in the standard upgrade steps.

Standard upgrade steps

  • The upgrade steps described here assume that your existing deployment is using certificate-based authentication (CBA), and has been updated accordingly to use the PFX certificate for the Teams Connector CVI app.
  • If you (the person performing the upgrade) did not perform the initial installation, you should ensure that you have all the PowerShell modules with the supported versions installed.

    1. Open a new PowerShell ISE or PowerShell session before you install the modules.
    2. Run the following PowerShell commands (as Administrator):
    Copy to clipboard
    # Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
    Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

    Install-Module -Name Az.Accounts -RequiredVersion 2.19.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Automation -RequiredVersion 1.10.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Compute -RequiredVersion 7.3.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.EventHub -RequiredVersion 4.2.2 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.KeyVault -RequiredVersion 5.3.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Network -RequiredVersion 7.5.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Resources -RequiredVersion 6.16.2 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Storage -RequiredVersion 6.2.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Az.Websites -RequiredVersion 3.2.1 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Microsoft.Graph.Authentication -RequiredVersion 2.17.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Microsoft.Graph.Applications -RequiredVersion 2.17.0 -Scope AllUsers -AllowClobber -Force
    Install-Module -Name Microsoft.Graph.Identity.DirectoryManagement -RequiredVersion 2.17.0 -Scope AllUsers -AllowClobber -Force

    Note that:

    • The Az PowerShell module collects telemetry data (usage data) by default, however you can opt out from this data collection using Disable-AzDataCollection (see this article for more information).
    • The Az PowerShell module remembers login information by default (i.e. you're not automatically logged out when closing your PowerShell window), but you can disable this with Disable-AzContextAutosave if required (see this article for more information).
  • You must use the latest version of the redeploy script as contained here.

  • You can use the same redeploy script for either your blue or green system (you should only upgrade the system that is not currently in use), and for any regional deployments. Always use the appropriate variable initialization script for that system.
  • As with all upgrades, you can continue to use the Pexip CVI app from your existing deployment.
  • Your Pexip Infinity and Teams Connector installations must both be running the same software version (including minor/"dot" releases).
  • Ensure that the Teams Connector resource groups are exempt from any configured Azure policies.

Redeploying the Teams Connector

The Teams Connector redeployment process described below is required when you want to:

  • Upgrade the Teams Connector software.
  • Change the Teams Connector's configuration (such as the names of the associated Conferencing Nodes).
  • Deploy a new Teams Connector in a different Azure region.

Note that there is no need to backup the Teams Connector as there are no specific settings, status or history information to preserve — if the deployment is lost you can just reinstall it with this redeploy process.

The redeployment process is summarized below:

  1. Check that you have the latest relevant version of the Teams Connector software, your variable initialization and redeploy scripts, your Teams Connector TLS certificate, and your CVI App ID, CVI App PFX certificate and CVI App certificate password.
  2. Redeploy the deployment which is currently not in use. For example, after initially using the blue system you will redeploy the green system. You will then have two functioning deployments again — the old version and the new version.
  3. Test the newly redeployed system.
  4. Switch over to the new system.
  5. When the transition is complete you can decommission the old deployment version (by either stopping all the VMs in the VMSS, or by completely removing the dynamic resource group associated with that system), so that you don't have to pay for the redundant Azure resources while that environment is not in use.

Before running your scripts we recommend that you check the Azure status (https://status.azure.com) for your region. Any ongoing issues in your region with the Azure services used by the Teams Connector could cause the script to fail.

The redeployment steps are shown in the following diagram and are then described in detail below.

Deployment script flowchart

Check Teams Connector software, retrieve your original scripts, and check your Azure environment

These instructions describe how to upgrade a Teams Connector that is already using CBA.

  1. Download the latest relevant version of the Teams Connector ZIP file (Pexip_Infinity_Connector_For_Microsoft_Teams_v35.1_<build>.zip) from the Pexip download page.

    Ensure that the Teams Connector version you download is the same version as your Pexip Infinity deployment (including minor/ "dot" releases).

  2. Extract the files to a folder on a local drive on your administrator PC.
  3. Add your PFX Teams Connector TLS certificate to this folder.
  4. Add your PFX certificate for the Teams Connector CVI app to this folder.
  5. Retrieve your saved copy of either your blue or green variables initialization script, as appropriate — choose the deployment which is currently not in use. You should have created and stored your version of this script after you completed your initial installation of your first pair of Teams Connectors.
  6. Check your saved copy of the initialization script that sets the environmental variables:

    • If you are upgrading your Teams Connector, you should compare the saved copy of your initialization script against the current version of this script (as listed here), and adjust your script if necessary, for example if new variables have been added.
    • If you are redeploying and need to change any of the previous configuration you should also adjust your initialization script as required.
    • If you have Teams Connectors in many regions, also ensure that you have the correct versions of the initialization scripts that set the regional variables to the appropriate values.
  7. Prepare your redeploy script:

    • If you are upgrading to v35, ensure that you use the latest version of the redeploy script and that you have updated it with your Pexip CVI App ID and CVI App certificate path:

      • The CVI App ID and CVI App certificate password should have been stored in a password manager.

        Use the stored CVI App ID value to update the two existing lines in the redeploy script that say:

        $AppId = ""

        $AppCertificatePath = ".\your_cvi_app_certificate.pfx"

        and set $AppCertificatePath to refer to the file name of the certificate that you retrieved in step 4.

        You'll be prompted for the CVI App certificate password later.

        This means that when you run the redeploy script, you will reuse the CVI app and CVI app certificate that you created the first time.

    • You should use the redeploy script in all scenarios except for when deploying a Teams Connector for the very first time (per Azure subscription) i.e. you should use the redeploy script when upgrading, redeploying, or deploying a new Teams Connector in another region.
    • You only need one version of this script — you can use the same redeploy script in every region if you have multiple Teams Connectors.

Remove and then recreate the dynamic resource group and ensure appropriate roles are assigned to the resource groups

These steps must be performed by the Owner of the Azure subscription used for the Teams Connector.

  1. Run the following PowerShell command to connect to Azure:

    • In all standard deployments run:

      Connect-AzAccount

    • If this is a GCC High / Azure US Government Cloud deployment then use this command instead:

      Connect-AzAccount -EnvironmentName AzureUSGovernment

    Then follow the prompts to sign in to Azure.

  2. Run either the blue or green variable initialization script as appropriate for the deployment you want to upgrade/redeploy (to set the required subscription, resource group name and blue/green/region variables).
  3. Ensure that you are using the Azure subscription for the Teams Connector:

    Set-AzContext -SubscriptionId $PxSubscriptionId

  4. Run the following script. It first deletes the dynamic resource group (if it exists) and then recreates it for the Teams Connector.

    Copy to clipboard
    # Remove the existing dynamic resource groups
    $PxTeamsConnResourceGroup = Get-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation -ErrorAction SilentlyContinue
    if ($PxTeamsConnResourceGroup) {
    # Disassociate NSG from the VMSS subnet
    $nsg = Get-AzNetworkSecurityGroup -ResourceGroupName $PxTeamsConnResourceGroupName -ErrorAction SilentlyContinue
    if ($null -ne $nsg) {
    $vmssSubnet = $nsg.Subnets | Where-Object { $_.Id.EndsWith("vmss-subnet") }
    if ($null -eq $vmssSubnet) {
    Write-Warning "NSG is not attached to the VMSS subnet"
    } else {
    $subnetConfig = Get-AzVirtualNetworkSubnetConfig -ResourceId $vmssSubnet.Id
    $existingVnet = Get-AzVirtualNetwork -Name $vmssSubnet.Id.Split('/')[8] -ResourceGroupName $vmssSubnet.Id.Split('/')[4]
    Set-AzVirtualNetworkSubnetConfig -Name $vmssSubnet.Id.Split("/")[-1] -AddressPrefix $subnetConfig.AddressPrefix -VirtualNetwork $existingVnet -NetworkSecurityGroupId $null -ServiceEndpoint @("Microsoft.Storage", "Microsoft.KeyVault", "Microsoft.EventHub") | Out-Null
    Write-Warning "The next command will disassociate subnet $($vmssSubnet.Id.Split("/")[-1]) from NSG $($nsg.Name)"
    $confirmation = "Y"
    $confirmation = Read-Host -Prompt 'Do you wish to proceed? [Y] Yes [N] No (default is "Y")'
    if ($confirmation -eq "Y") {
    $existingVnet | Set-AzVirtualNetwork | Out-Null
    }
    }
    }
    $resources = Get-AzResource -ResourceGroupName $PxTeamsConnResourceGroupName
    $resNames = $resources | ForEach-Object { return "`n" + $_.Name + " " + $_.ResourceType }
    Write-Host "In order to redeploy Pexip Teams Connector, resource group $PxTeamsConnResourceGroupName has to be deleted. Resources: $resNames"
    Remove-AzResourceGroup -Name $PxTeamsConnResourceGroupName | Out-Null
    }
    $PxTeamsConnResourceGroup = Get-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation -ErrorAction SilentlyContinue
    if ($null -ne $PxTeamsConnResourceGroup) {
    Write-Warning "$PxTeamsConnResourceGroupName still exists, however it has to be removed before redeploying!"
    } else {
    # Create resource group for Teams Connector VMSS (per region)
    # This is region specific; ensure that the initial variables are set with the
    # correct values for $PxAzureLocation, $PxTeamsConnFqdn and $PxVmssRegion
    New-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation -Tag $tags
    }
  5. Ensure that the person who will perform all of the remaining steps has the Azure Owner role for the static and dynamic resource groups, and Contributor role for the Azure Bot resource group.

    If the Owner of the Azure subscription will be performing the redeploy/upgrade then this step can be skipped, otherwise the subscription Owner must assign the required roles to the person performing the upgrade. You do this by running the following commands:

    New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Owner" -ResourceGroupName $PxTeamsConnStaticResourceGroupName

    New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Owner" -ResourceGroupName $PxTeamsConnResourceGroupName

    New-AzRoleAssignment -SignInName <email_name> -RoleDefinitionName "Contributor" -ResourceGroupName $PxBotResourceGroupName

    where <email_name> is the email address / user principal name of the person who will perform the remaining upgrade/redeploy steps; for example where alice@example.com will perform the upgrade/redeploy, the SignInName would be -SignInName alice@example.com for the commands listed above.

Note:

  • In the future, if another person were to upgrade or redeploy the Teams Connector, that person would also have to be granted the appropriate roles for these resource groups.
  • You can use the Azure portal to check/assign permissions by selecting the resource group and using the Access control (IAM) option.

Redeploy the Teams Connector

To redeploy the Teams Connector:

  1. Open a new PowerShell ISE or PowerShell session.
  2. Change directory to the folder into which you extracted the files from the Teams Connector ZIP.
  3. Ensure that you have Owner permissions for the API app (check App registrations in the Azure portal); see Assigning Owner permissions for the API app if you do not have permission.
  4. In PowerShell, run either your blue or green variables initialization script, as appropriate for the deployment that you want to upgrade/redeploy, that sets the environmental variables.
  5. In PowerShell run your redeploy script.

    You only need one version of this script — you can use the same script for every Teams Connector (blue, green or regional).

This is the redeploy script. It is a variation on the installation script that only performs the necessary commands to redeploy the Teams Connector. As with the initial installation, we recommend running each group of commands step-by-step within PowerShell.

This script applies to software version 35. If you are using an earlier version you should refer to our previous documentation.

  • Standard deployment
  • GCC High / Azure US Government Cloud deployment
Copy to clipboard
# Ensure the correct script and software combination is being used
try {$PxConnMajorVersion = (Get-Content .\version.json -ErrorAction Stop | Out-String | ConvertFrom-Json).major} catch {Write-Warning "Can't find version.json file. Make sure you run the installation script from the folder into which you extracted the files from the Teams Connector ZIP"}

if ($PxConnMajorVersion -ne "35"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 35"}

# Connect to PowerShell Azure Resource Manager account
# Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

# The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet. 
# By default, these files are blocked to protect the computer from untrusted files.
Get-ChildItem -Recurse | Unblock-File

# Import the PexTeamsCviApplication PowerShell module
Import-Module .\PexTeamsCviApplication.psm1

# Import Az Powershell modules
Import-PexAzurePowershellModules -ErrorAction Stop

# Import Microsoft.Graph Powershell modules
Import-PexMicrosoftGraphPowershellModules -ErrorAction Stop

# Connect to Azure with an authenticated account for use with Azure Resource Manager (in same window to reuse variables)
Connect-AzAccount

# Connect to Graph
Connect-PexTeamsMsGraph

# Before running the following commands, update the following 2 lines/variables with the CVI App ID and
# the path to the CVI App certificate file that were output when the original installation script was run
# You'll be prompted for the CVI App certificate password later.
$AppId = ""
$AppCertificatePath = ".\your_cvi_app_certificate.pfx"

# Change context to the Pexip Subscription
Set-AzContext -SubscriptionId $PxSubscriptionId

# Virtual Machine Scale Set (VMSS) creation
# Provide credentials to be used as local user/password for Pexip Teams Connector VMs
# Create a password (using the initialization script variables) for the Windows VM
$PxWinAdminSecurePassword = ConvertTo-SecureString -AsPlainText $PxWinAdminPassword -Force
$PxWinAdminCred = New-Object System.Management.Automation.PSCredential -ArgumentList $PxWinAdminUser,$PxWinAdminSecurePassword

# Optionally if you did not want to specify the password as a variable, use Get-Credential
# $PxWinAdminCred = Get-Credential

# Deploy the Teams Connector VMs
# this step can take up to 30 minutes to complete
.\create_vmss_deployment.ps1 -SubscriptionId $PxSubscriptionId -AzureVmSize $PxAzureVmSize -ResourceGroupName $PxTeamsConnResourceGroupName -VmssName "$($PxBaseConnName)$($PxVmssRegion)" -VMAdminCredential $PxWinAdminCred -PfxPath $PxPfxCertFileName -TeamsConnectorFqdn $PxTeamsConnFqdn -PexipFqdns $PxNodeFqdns -instanceCount $PxTeamsConnInstanceCount -AppId $AppId -AppCertificatePath $AppCertificatePath -StaticResourcesResourceGroupName $PxTeamsConnStaticResourceGroupName -IncidentReporting $PxTeamsConnIncidentReporting -RdpSourceAddressPrefixes $PxMgmtSrcAddrPrefixes -PexipSourceAddressPrefixes $PxNodesSourceAddressPrefixes -WupdScheduledInstallDay $PxWupdScheduledInstallDay -WupdScheduledInstallTime $PxWupdScheduledInstallTime -WupdActiveHoursStart $PxWupdActiveHoursStart -WupdActiveHoursEnd $PxWupdActiveHoursEnd -CustomerUsageAttribution $PxCustomerUsageAttribution -UseAzureHybridBenefit $PxUseAzureHybridBenefit -Tag $tags -TeamsConnectorApiApplicationId $TeamsConnectorApiApplicationId -FunctionsDedicatedHostingPlan $FunctionsDedicatedHostingPlan -EventHubSourceAddressPrefixes $EventHubSourceAddressPrefixes -VnetIntegration $VnetIntegration -PexipConfiguredConnectorFqdn $PexipConfiguredConnectorFqdn -PexipOutboundFqdn $PexipOutboundFqdn -ExistingVNETResourceId $PxExistingVNETResourceId -UsePrivateRouting $PxUsePrivateRouting

# supply the PFX certificate file password when prompted

# Please enter the password for the PFX certificate '.\xxxxxxxx.pfx': ***************

# supply the PFX CVI app certificate file password when prompted

# Please enter the password for the CVI app PFX certificate '.\xxxxxxxx.pfx': ***************

# Printing finished message
Write-Host
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host " All steps completed."
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host
Copy to clipboard
# This script only applies to GCC High / Azure US Government Cloud deployments

# Ensure the correct script and software combination is being used
try {$PxConnMajorVersion = (Get-Content .\version.json -ErrorAction Stop | Out-String | ConvertFrom-Json).major} catch {Write-Warning "Can't find version.json file. Make sure you run the installation script from the folder into which you extracted the files from the Teams Connector ZIP"}

if ($PxConnMajorVersion -ne "35"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 35"}

# Set VmImage variable to hold the CIS STIG image properties - STIG image is optional but typical
# In a later step in this script you can choose not to use the STIG image 
$VmImage = @{
"sku"  = "cis-windows-server2019-stig-gen1"
"offer"  = "cis-windows-server"
"publisher" = "center-for-internet-security-inc"
"version"  = "latest"}

# Connect to PowerShell Azure Resource Manager account
# Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

# The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet. 
# By default, these files are blocked to protect the computer from untrusted files.
Get-ChildItem -Recurse | Unblock-File

# Import the PexTeamsCviApplication PowerShell module
Import-Module .\PexTeamsCviApplication.psm1

# Import Az Powershell modules
Import-PexAzurePowershellModules -ErrorAction Stop

# Import Microsoft.Graph Powershell modules
Import-PexMicrosoftGraphPowershellModules -ErrorAction Stop

# Connect to Azure USGovernment with an authenticated account for use with Azure Resource Manager (in same window to reuse variables)
Connect-AzAccount -EnvironmentName AzureUSGovernment

# Connect to Graph
Connect-PexTeamsMsGraph

# Before running the following commands, update the following 2 lines/variables with the CVI App ID and
# the path to the CVI App certificate file that were output when the original installation script was run
# You'll be prompted for the CVI App certificate password later.
$AppId = ""
$AppCertificatePath = ".\your_cvi_app_certificate.pfx"

# Change context to the Pexip Subscription
Set-AzContext -SubscriptionId $PxSubscriptionId

# Virtual Machine Scale Set (VMSS) creation
# Provide credentials to be used as local user/password for Pexip Teams Connector VMs
# Create a password (using the initialization script variables) for the Windows VM
$PxWinAdminSecurePassword = ConvertTo-SecureString -AsPlainText $PxWinAdminPassword -Force
$PxWinAdminCred = New-Object System.Management.Automation.PSCredential -ArgumentList $PxWinAdminUser,$PxWinAdminSecurePassword

# Optionally if you did not want to specify the password as a variable, use Get-Credential
# $PxWinAdminCred = Get-Credential

# Deploy the Teams Connector VMs
# this step can take up to 30 minutes to complete
# if you are not using a STIG image then remove the following parameter from this command: -VmImage $VmImage
.\create_vmss_deployment.ps1 -SubscriptionId $PxSubscriptionId -AzureVmSize $PxAzureVmSize -ResourceGroupName $PxTeamsConnResourceGroupName -VmssName "$($PxBaseConnName)$($PxVmssRegion)" -VMAdminCredential $PxWinAdminCred -PfxPath $PxPfxCertFileName -TeamsConnectorFqdn $PxTeamsConnFqdn -PexipFqdns $PxNodeFqdns -instanceCount $PxTeamsConnInstanceCount -AppId $AppId -AppCertificatePath $AppCertificatePath -StaticResourcesResourceGroupName $PxTeamsConnStaticResourceGroupName -IncidentReporting $PxTeamsConnIncidentReporting -RdpSourceAddressPrefixes $PxMgmtSrcAddrPrefixes -PexipSourceAddressPrefixes $PxNodesSourceAddressPrefixes -WupdScheduledInstallDay $PxWupdScheduledInstallDay -WupdScheduledInstallTime $PxWupdScheduledInstallTime -WupdActiveHoursStart $PxWupdActiveHoursStart -WupdActiveHoursEnd $PxWupdActiveHoursEnd -CustomerUsageAttribution $PxCustomerUsageAttribution -UseAzureHybridBenefit $PxUseAzureHybridBenefit -Tag $tags -TeamsConnectorApiApplicationId $TeamsConnectorApiApplicationId -FunctionsDedicatedHostingPlan $FunctionsDedicatedHostingPlan -EventHubSourceAddressPrefixes $EventHubSourceAddressPrefixes -VnetIntegration $VnetIntegration -VmImage $VmImage -TeamsEnvironmentName TeamsGCCHigh -PexipConfiguredConnectorFqdn $PexipConfiguredConnectorFqdn -PexipOutboundFqdn $PexipOutboundFqdn -ExistingVNETResourceId $PxExistingVNETResourceId -UsePrivateRouting $PxUsePrivateRouting

# supply the PFX certificate file password when prompted

# Please enter the password for the PFX certificate '.\xxxxxxxx.pfx': ***************

# supply the PFX CVI app certificate file password when prompted

# Please enter the password for the CVI app PFX certificate '.\xxxxxxxx.pfx': ***************

# Printing finished message
Write-Host
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host " All steps completed."
Write-Host
Write-Host "`n--------------------------`n"
Write-Host
Write-Host

Test the new Teams Connector software

After you have upgraded your test system to the latest Teams Connector software, you can test the new software without having to make any significant configuration changes within Pexip Infinity — the only configuration change required is to select the Enable Azure Event Hub checkbox on the "Test system" Teams Connector for the duration of the testing period.

  • Assuming blue is the current production system, after upgrading the green system to the latest software you can test it simply by using the existing "test" rule (that you set up during the initial installation and is configured to use the "Test system" Teams Connector).
  • Your existing production system will continue to work normally (using the other Call Routing Rules and the "Production" Teams Connector).

Pexip Infinity version compatibility

Normally you should ensure that you are running the same software version (including minor releases) of Pexip Infinity and Teams Connector to ensure compatibility between the two platforms.

When testing the new Teams Connector software while also running the existing production version it is likely that, for a period of time, you will have a version mismatch between the two platforms. Typically when upgrading to a new minor release there should not be any incompatibility issues. However when upgrading to a new major version of the Teams Connector there could be compatibility issues, and any new features introduced in that new version may not work as expected, and possibly the interop service may not work at all. You must always read the release notes for any known compatibility issues and upgrade guidelines. In some cases you may need to deploy and use a test Pexip Infinity platform that is also running the same software version as the new Teams Connector.

Note that no DNS changes are required when testing or switching over (after initially creating the two A-records during the installation process). However, you may need to enable the relevant firewall ports for the upgraded Teams Connector deployment if you have previously locked down the test system.

Switching over to the upgraded Teams Connector software

After you have upgraded and tested the new Teams Connector software, you can switch the configuration of the two deployments within Pexip Infinity.

Assuming blue is the current production system:

  1. Go to Call control > Microsoft Teams Connectors and update the "Production system" Teams Connector to use the address and Event Hub connection details of the green deployment.

    If you have any Microsoft Teams Room devices that call VTCs or VMRs then you also you need to redo the steps described at Enabling the Teams Connector to receive calls from a Teams Room (this updates the Azure Bot to use the correct Teams Connector FQDN).

    You are now live with the new software and any new calls will be routed through the new green system (any existing calls will remain connected via the blue deployment).

  2. Update the "Test system" Teams Connector with the address and Event Hub connection details of the blue deployment. You should then also deselect the Enable Azure Event Hub checkbox again.

    This gets it ready for the next upgrade cycle.

At the next upgrade, just repeat the process of switching the configuration of the two Teams Connectors — this time the blue system will go back to being the production environment, and green will go back to being the test environment. And then just repeat this toggling process in the future.

The benefit of this approach is that you only have to update the configuration of the two Teams Connectors whenever you want to complete the switchover, rather than potentially having to update lots of Call Routing Rules to switch between the two Teams Connector deployments. However, any process that follows the same principles of toggling between the two deployed Teams Connectors is fine.

If you do need to fallback to the previous system you can just reverse the configuration steps to reinstate the previous blue/green deployment as the production system.

After successful upgrade to the new Teams Connector, you can remove the dynamic resource group ($PxTeamsConnResourceGroupName) of the previous production system so you don't have to pay for the redundant Azure resources while that environment is not in use:

  1. In the Azure portal, for your subscription, go to Resource groups and search for the group named with the value of the $PxTeamsConnResourceGroupName variable from the variables script associated with the previous production system (i.e. from the green or blue variables script, as appropriate).
  2. Select the resource group and then select Delete resource group and confirm with the name of the resource group.

    Do not delete any of the other resource groups.

Alternatively, to still save money, instead of deleting the entire dynamic resource group, you can stop all of the Teams Connector instances in the VMSS.

When you upgrade to the next version you will redeploy this system and you will then have two functioning deployments again for the duration of the switchover.

Note that calls to your test system will not work while it is in a decommissioned state (when its dynamic resource group does not exist, or the VMs are stopped).

Moving from an existing single Teams Connector to a blue-green deployment strategy

This section describes how to move/upgrade from an existing single Teams Connector to a blue-green deployment strategy.

Differences between a single and a blue-green installation

Most of the deployment steps for a blue-green installation are similar to a single Teams Connector deployment. However, you should note that:

  • You deploy two Teams Connectors. Each Teams Connector needs a unique DNS name and a TLS certificate that matches that identity. You can use a single certificate for both Teams Connectors; this can either be a wildcard certificate or a certificate that contains the Subject Alternative Name (altNames attribute) entries for both Teams Connectors.
  • You do not need to create a new CVI app or perform any additional app authorizations when deploying the second Teams Connector — only one CVI app registration is required per tenant. However you do need to create a new API app for each new Teams Connector deployment.
  • Both Teams Connectors can use the same set of Conferencing Nodes (the $PxNodeFqdns variable in the initialization script).
  • You create 2 DNS A-records (one for each deployment), and you need to enable the relevant firewall ports for both Teams Connector deployments while you are testing / switching over.
  • You still do not need to create a new CVI app or API app when upgrading (redeploying) to a new version.

See How a blue-green strategy works for more information.

Migrating to a blue-green strategy

If you have an existing Teams Connector and want to switch to using a blue-green upgrade strategy you can create a new, second "green" deployment to use alongside your existing deployment which in effect becomes your "blue" deployment (using whatever name is currently assigned to $PxVmssRegion in your existing variables script).

If you are also planning on upgrading to a new release of Teams Connector software you can either install and test the green system first with your current version of the Teams Connector and then follow our upgrade procedure to switch the new green system to your production environment, or you can download and use the latest Teams Connector software to create your green system.

To create your green deployment:

  1. Decide on the DNS name for your green deployment and obtain a TLS certificate that matches that identity (if you are using a single certificate for all Teams Connectors ensure that it contains Subject Alternative Names for the existing blue and the new green systems).
  2. Create a variables initialization script for the green system. This can be based on your existing blue variables script, but requires some of the variables to be different. See Specify installation variables used in the PowerShell installation commands for details.
  3. Run the following PowerShell command to connect to Azure:

    • In all standard deployments run:

      Connect-AzAccount

    • If this is a GCC High / Azure US Government Cloud deployment then use this command instead:

      Connect-AzAccount -EnvironmentName AzureUSGovernment

    Then follow the prompts to sign in to Azure.

  4. Create the Azure resource groups for your green environment:

    1. Run the green variable initialization script (to set the required subscription, resource group name and green/region variables).
    2. Run the following script to create the resource groups for static and dynamic resources for the green environment:

      Copy to clipboard
      # Resource group for static resources for the Teams Connector / region
      New-AzResourceGroup -Name $PxTeamsConnStaticResourceGroupName -Location $PxAzureLocation -Force -Tag $tags

      # Resource group for the Teams Connector VMSS (per region)
      New-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation -Tag $tags
  5. Create the Teams Connector API app for your green environment.

    Follow the instructions at Create the Teams Connector API apps for your blue and green environments, omitting the steps to create and store the details of the API app for your blue environment as that has already been completed.

  6. Deploy the green Teams Connector.

    Follow the instructions at Deploying the "green" Teams Connector, remembering to ensure you have set the directory of your PowerShell session to the folder containing the extracted files from the Teams Connector ZIP for the software version you want to install.

  7. Update DNS with the IP address of your new Teams Connector.

    See Update DNS with Teams Connector names and IP addresses for details.

  8. Configure your new Teams Connector in Pexip Infinity and set up a Call Routing Rule for testing:

    1. Go to Call control > Microsoft Teams Connectors and select Add Microsoft Teams Connector and add the details of your green Pexip Infinity as your "test" environment.

      See Configuring your Teams Connectors (addresses, Event Hub, minimum capacity) for details.

    2. Create a routing rule that can be used to test the newly installed green system and for testing any upgraded system before you switch over to using it as your production system.

      See Configuring a test rule for details.

      If you are setting up your green system and upgrading to the latest Teams Connector software at the same time, then do not remove the dynamic resource group of the new green system as it is required when you switch over to using the green system.

You now have a new green Teams Connector alongside your existing production system which is now, in effect, your blue system.

Next steps

You now have the following options depending on where you are in your deployment/upgrade cycle:

  • If your blue and green systems are both running the same older version of Teams Connector software, you can follow the upgrade guidelines to make your new green system your new production system using the latest Teams Connector software.
  • If you have already used the latest Teams Connector software for your green system then you can follow the instructions at Switching over to the upgraded Teams Connector software to switch to using the green system as your new production system.

Migrating (upgrading) an existing Teams Connector using password-authentication to CBA

If you already have a Teams Connector deployed with password-based authentication, you can switch to a certificate-based authentication model.

Note that the instructions below generate and use a self-signed certificate; see Using your own certificate for the CVI App if you want to use your own certificate instead.

To switch to certificate-based authentication:

  1. Ensure that you are an owner of the Pexip CVI Application.
  2. Download the latest relevant version of the Teams Connector ZIP file (Pexip_Infinity_Connector_For_Microsoft_Teams_v35.1_<build>.zip) from the Pexip download page.
  3. Extract the files to a folder on a local drive on your administrator PC.
  4. Start a PowerShell session as Administrator.
  5. After launching PowerShell you must change directory to the folder into which you extracted the files from the Teams Connector ZIP.
  6. Assign the $AppId variable with your CVI App ID (as contained within your existing redeploy script).
  7. Run the following commands:

    Copy to clipboard
    # Ensure the correct script and software combination is being used
    try {$PxConnMajorVersion = (Get-Content .\version.json -ErrorAction Stop | Out-String | ConvertFrom-Json).major} catch {Write-Warning "Can't find version.json file. Make sure you run the installation script from the folder into which you extracted the files from the Teams Connector ZIP"}

    if ($PxConnMajorVersion -ne "35"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 35"}

    # Import the PexTeamsCviApplication PowerShell module
    Import-Module .\PexTeamsCviApplication.psm1

    # Import Az Powershell modules
    Import-PexAzurePowershellModules -ErrorAction Stop

    # Import Microsoft.Graph Powershell modules
    Import-PexMicrosoftGraphPowershellModules -ErrorAction Stop

    # Connect to Azure
    Connect-AzAccount

    # Connect to Graph
    Connect-PexTeamsMsGraph

    $AppCertificatePath = New-PexTeamsCviApplicationCertificateCredential -AppId $AppId -ValidityInMonths 24
    $AppCertificatePath = $AppCertificatePath.Trim()
    # Please enter the password for the CVI app PFX certificate: ********************
    # Verifying - Enter the password for the CVI app PFX certificate: ********************
    # Your PFX certificate including the private key has been stored at '{absolute path}'
    # The certificate is valid from '{notBefore}' to '{notAfter}' (UTC)
    # CVI application certificate credential 'pexip-cvi-app-certificate-[{date}]' has been successfully uploaded to Microsoft Entra ID

    Enter the password for the CVI app PFX certificate when prompted. We recommend that you create and save the CVI App PFX certificate password using a password manager.

    Regarding the CVI App certificate, you should note that:

    • The script passes a -ValidityInMonths parameter to the PexTeamsCviApplicationCertificateCredential cmdlet to specify the validity period of the CVI App certificate. In this case it specifies "-ValidityInMonths 24" i.e. 2 years but you can specify your own period as required.
    • The Teams Connector application will stop working if the CVI App certificate expires. We recommend that you set certificate contact notifications (see this Microsoft article) as they can warn you of certificates that are due to expire.
  8. Store the CVI App certificate PFX file in a safe location.
  9. Now you can follow the redeploy instructions above.

Using your own certificate for the CVI App

The procedure above generates and uses a self-signed certificate. If you want to use your own certificate instead:

  • The certificate must be a .pfx certificate.
  • The CVI App certificate must be different from the Teams Connector certificate.
  • You have to manually upload its public key (.cer/.pem/.crt) to the CVI application via the Microsoft Entra admin center — see this article for instructions.
  • You have to specify its location in the $AppCertificatePath variable when preparing your installation/redeploy script.

    Replace this line

    $AppCertificatePath = New-PexTeamsCviApplicationCertificateCredential -AppId $AppId -ValidityInMonths 24

    with

    $AppCertificatePath = "C:\your_cvi_app_certificate.pfx"

Updating the Teams Connector TLS certificate or the CVI app certificate

The Teams Connector TLS certificate and the CVI app certificate (when using CBA to authenticate the Teams Connector CVI application towards MS Graph) are stored in the Azure key vault and can be updated without having to redeploy the Teams Connector. The old (existing) certificates can be updated when they are expiring or when they have already expired. We recommend updating the certificates before they expire to avoid service disruptions.

If you need to roll back to an older (but still valid) version of a certificate, you must follow these steps to import it as an additional certificate. Simply disabling the current certificate will not automatically revert to the previous version.

See Teams Connector certificate requirements for more information about the certificate requirements.

You can also refer to this video tutorial:

Note:

  • An alarm is raised on Pexip Infinity when the Teams Connector certificates are due to expire within the next 30 days, and if they have expired.
  • You can use the test_pfx_certificate.ps1 script (which is in the Teams Connector ZIP file) to verify the currently installed Teams Connector TLS certificate (you cannot use it on the CVI app certificate). The command takes the format (run your variables initialization script first):

    test_pfx_certificate.ps1 -TeamsConnectorFqdn $PxTeamsConnFqdn -PfxPath $PxPfxCertFileName -PfxPassword <certificate password>

  • If you need to create a new CVI app certificate, follow steps 1-7 of the instructions at Migrating (upgrading) an existing Teams Connector using password-authentication to CBA.

To update either the Teams Connector TLS certificate or the CVI app certificate:

  1. In the Azure portal, for your subscription, select the Teams Connector static resource group (which typically has a name in the style <prefix>-TeamsConn-<blue/green/region>-static-RG).
  2. Ensure that you are an owner of the resource group.
  3. Select the Key vault in that resource group.
  4. Add a Key Vault Certificates Officer role (a4417e6f-fecd-4de8-b567-7b0420556985) for your user principal (see this article for instructions).
  5. Open the Certificates pane (under Settings).

    (Note that the screenshot examples below are for the Teams Connector TLS certificate.)

    If you have VNet integration enabled and you see a warning "Firewall is turned on and your client IP address is not authorized to access this key vault" then you need to temporarily add your client IP address in the key vault’s Networking settings (Firewall > + Add your client IP address).

  6. Select the relevant certificate:

    • To update the Teams Connector TLS certificate: select the certificate named pexip-teams-connector-certificate.
    • To update the CVI app certificate: select the certificate named pexip-cvi-app-certificate.

    (Don't create/import a new certificate under a different name.)

  7. Select New Version.

  8. Select Import as the creation method.

  9. Select your new pfx certificate and provide a password if the certificate is password protected.
  10. Import the certificate.

    After importing a certificate any alarm in Pexip Infinity related to an expiring or expired Teams Connector TLS certificate will be lowered, but the new certificate is not applied across the VMSS yet.

    There is no need to delete the expired certificate.

  11. You have to reboot the scale set to apply the new certificate version.

    To do this, in the Azure portal, for your subscription, select the Teams Connector dynamic resource group (which typically has a name in the style <prefix>-TeamsConn-<blue/green/region>-RG), then the Virtual Machine Scale Set and select the Restart option from the top menu.

    Perform the reboot during out-of-hours — rebooting the scale set drops any existing calls.

  12. After a few minutes, when the instances have restarted, verify that you can make calls and that the desired state configuration (from within your dynamic resource group, select the Automation Account, and then State configuration DSC) is green for all the running VMSS instances. (Some instances might be deallocated if using scheduled scaling — these instances will be provisioned with the new certificate on startup.)

We recommend that you set certificate contact notifications (see this Microsoft article) as they can warn you of certificates that are due to expire.

Assigning Owner permissions for the API app

The person who will be performing the deployment must have Owner permissions for the API app.

When necessary, the script below can be used by the current Owner to assign the Owner permission to another user.

Note that you must have run the variables script to assign the $TeamsConnectorApiApplicationId variable and you must replace <email_name> in the script with the email address / user principal name of the person who will perform the remaining installation steps.

  1. Run the following PowerShell command to connect to Azure:

    • In all standard deployments run:

      Connect-AzAccount

    • If this is a GCC High / Azure US Government Cloud deployment then use this command instead:

      Connect-AzAccount -EnvironmentName AzureUSGovernment

    Then follow the prompts to sign in to Azure.

  2. Run the relevant variables script to assign the $TeamsConnectorApiApplicationId variable.
  3. Copy the script below:

    1. You must replace <email_name> in the script with the email address / user principal name of the person who will perform the remaining installation steps.

      For external users (guests in a tenant) the -UserId parameter should be in the form "<emailname_domain>#EXT#@<tenant_url>". For example, for external users, if the external user has an email name of guestname@guestdomain.com and is a guest in maintenant.com, then you would specify (note the _ replacing the @ between guestname and guestdomain.com):

      -UserId "guestname_guestdomain.com#EXT#@maintenant.onmicrosoft.com"

    2. Run the script.
    Copy to clipboard
    # Import the PexTeamsCviApplication PowerShell module
    Import-Module .\PexTeamsCviApplication.psm1

    # Import Microsoft.Graph Powershell modules
    Import-PexMicrosoftGraphPowershellModules -ErrorAction Stop

    # Connect to Graph
    Connect-PexTeamsMsGraph

    # Import the HelperFunctions PowerShell module
    Import-Module .\HelperFunctions.psm1

    # Get Graph url for this environment
    $graphUrl = GetMsGraphUrlForAzureEnvironment

    # Get the API application registration reference
    $apiApp = Get-MgApplication -Filter "AppId eq '${TeamsConnectorApiApplicationId}'"

    # Make sure you have Microsoft.Graph.Users Powershell module installed
    Install-Module -Name Microsoft.Graph.Users -RequiredVersion 2.11.1 -Scope AllUsers -AllowClobber -Force
    Import-Module Microsoft.Graph.Users -RequiredVersion 2.11.1

    # Get the assignee
    # Replace <email_name> with the email address / user principal name of the person to perform the remaining installation steps
    $user = Get-MgUser -UserId <email_name>

    # Assign owner role for the API application registration to the assignee
    $newOwner = @{
    "@odata.id"= "$($graphUrl)v1.0/directoryObjects/$($user.Id)"
    }
     
    New-MgApplicationOwnerByRef -ApplicationId $apiApp.Id -BodyParameter $newOwner

    # Get the service principal associated with the API application
    $apiAppSp = Get-MgServicePrincipal -Filter "AppId eq '${TeamsConnectorApiApplicationId}'"

    # Assign owner role for the API application service principal to the assignee
    New-MgServicePrincipalOwnerByRef -ServicePrincipalId $apiAppSp.Id -BodyParameter $newOwner

Maintaining access to the Admin Consent web page

This section provides information on managing access to the Admin Consent web page.

Reinstating the Admin Consent web page

If you are upgrading and you need to maintain access to the Admin Consent web page (typically only necessary if you are a service provider), then after completing the commands in the redeploy script you should also run the following additional PowerShell commands to reinstate the Admin Consent web page:

Import-Module .\PexTeamsCviApplication.psm1

$AdminConsentUrl = Publish-PexTeamsAdminConsentWebSite -SubscriptionId $PxSubscriptionId -ResourceGroupName $PxBotResourceGroupName -PxBaseConnName $PxBaseConnName -AppId $AppId -SourceAddressPrefixes $PxConsentSourceAddressPrefixes -Confirm:$false -Tag $tags

and then

Write-Host "To give consent to the CVI app, go to: $AdminConsentUrl"

Note that if you run the above commands in a new window/session you will first need to run the PowerShell variables initialization script.

Changing the workstation / management network addresses that can access the consent page

To change the workstation / management network addresses that can provide consent for the Teams Connector CVI app (the addresses that were initially specified in $PxConsentSourceAddressPrefixes):

  1. In the Azure portal, go to the Azure bot resource group — this is called <prefix>-TeamsBot-RG.
  2. Select the App Service object.
  3. Under Settings, select Networking.
  4. Select Configure Access Restrictions.
  5. Modify the addresses as required and save your changes.

Adding or removing Conferencing Nodes

You can change the pool of Conferencing Nodes that communicates with the Teams Connector without having to redeploy the Teams Connector itself, providing that the certificate installed on any new Conferencing Nodes contains an identity that was in the $PxNodeFqdns initialization script variable when the Teams Connector was originally deployed.

For example, if you have a Teams Connector deployed as shown in Certificate and DNS examples for a Microsoft Teams integration i.e.

  • two existing Conferencing Nodes called px01.vc.example.com and px02.vc.example.com
  • both nodes have the same certificate installed with subject name px.vc.example.com, and altNames px.vc.example.com, px01.vc.example.com and px02.vc.example.com
  • the Teams Connector was deployed with the $PxNodeFqdns variable set to px.vc.example.com

and you want to add a new Conferencing Node px03.vc.example.com, you would have to:

  1. Install a certificate on the new Conferencing Node that contains the common px.vc.example.com identity.

    To remain consistent with our example certificate naming policy this would mean creating a new certificate with a subject name of px.vc.example.com and altNames of px.vc.example.com, px01.vc.example.com, px02.vc.example.com and px03.vc.example.com. You would then install this certificate on the new node and the two existing nodes.

    Note that purely from a Teams Connector perspective, the node certificate only needs to contain the identity specified in the $PxNodeFqdns variable, but if the same Conferencing Nodes handle SIP and Skype for Business signaling then the example certificate naming policy used here is more appropriate.

  2. You may need to update the Network Security Group associated with your Teams Connector in Azure.

    The "MCU-signalling-endpoint" rule (priority 110) specifies the IP addresses of the Conferencing Nodes that can communicate with the Teams Connector. These addresses were based on the value of the $PxNodesSourceAddressPrefixes initialization script variable. If individual IP addresses were specified then you need to add the IP address of the new Conferencing Node to this NSG rule. If the variable specified an IP subnet and the new node's address is within that subnet, then no changes are required.

  3. If you had to update the NSG rule, you should add the same new address to the $PxNodesSourceAddressPrefixes variable in your stored initialization script to keep it in sync with your actual deployment in case it is needed for a future redeployment or upgrade.
  4. Ensure you apply steps 2 and 3 to all of your Teams Connectors (blue, green or regional).

Removing Conferencing Nodes

If you need to remove a Conferencing Node from the pool for any reason, you do not need to make any immediate changes to your Teams Connector / Azure configuration. However, you should make any necessary changes to the $PxNodesSourceAddressPrefixes variable in your stored variable initialization scripts to keep them in sync with your actual deployment.

Changing the alternative dialing instructions or IVR address

You can use the Set-CsVideoInteropServiceProvider command to change the alternative dialing instructions or the IVR address (TenantKey).

Changing the alternative dialing instructions

You can update the webpage of "More info" alternative VTC dialing instructions that the recipient of the meeting invite can look at, by adding or removing some of the address types that are displayed.

You do this by using the Set-CsVideoInteropServiceProvider command and supplying a new InstructionUri parameter, following the same rules as described when you first created the service provider.

In our original example, the service provider was created with the command:

New-CsVideoInteropServiceProvider -Name Pexip -TenantKey "teams@example.com" -InstructionUri "https://px.vc.example.com/teams/?conf={ConfId}&ivr=teams&d=example.com&ip=198.51.100.40&test=test_call&w&qrcode" -AllowAppGuestJoinsAsAuthenticated $true -AadApplicationIds "c054d1cb-7961-48e1-b004-389e81356232"

To change the instructions to remove the "Test call" option, for example, the revised InstructionUri parameter would be "https://px.vc.example.com/teams/?conf={ConfId}&ivr=teams&d=example.com&ip=198.51.100.40&w&qrcode"

and the command to apply the revised InstructionUri parameter would be:

Set-CsVideoInteropServiceProvider -Identity Pexip -InstructionUri "https://px.vc.example.com/teams/?conf={ConfId}&ivr=teams&d=example.com&ip=198.51.100.40&w&qrcode"

Changing the IVR address (TenantKey)

The IVR address (TenantKey) is the alias that you assign to the Pexip Virtual Reception that is to act as the IVR gateway into the Teams meetings. In our original example this was set to teams@example.com.

To change the address you can use the Set-CsVideoInteropServiceProvider command and supply a new TenantKey parameter, for example:

set-CsVideoInteropServiceProvider -Identity Pexip -TenantKey "newaddress@example.com"

Note that when using Set-CsVideoInteropServiceProvider, the first parameter is called -Identity, not -Name.

These changes may take up to 6 hours to come into effect.

Changing the call capacity of a Teams Connector

When you install a Teams Connector CVI application in Azure, you initially specify the number of Teams Connector instances (VMs) to deploy.

You can subsequently modify the number of instances via the Azure portal, to reflect changing capacity requirements, or if you have enabled the Azure Event Hub you can also automate/schedule changes in call capacity to suit your requirements.

See Scheduling scaling and managing Teams Connector capacity for full details.

Changing management workstation access

When you deploy a Teams Connector, a Network Security Group (NSG) is created within Azure. The NSG includes an "RDP" rule (priority 1000) that controls RDP access to the Teams Connector instances from any addresses specified in the $PxMgmtSrcAddrPrefixes installation variable.

If no addresses were specified then a Deny rule is created instead. If you want to subsequently allow RDP access you must do a full redeploy. You cannot just convert the Deny rule into an Allow rule (as other associated Teams Connector settings also have to be modified).

You can change this rule if you want to specify a different set of management workstation addresses. To do this:

  1. In the Azure portal, for your subscription, go to the Network security group in your Teams Connector resource group.
  2. Select rule 1000 RDP.
  3. Change the Source IP addresses/CIDR ranges as appropriate for the management workstation / network subnet addresses you want to allow RDP access.
  4. Select Save.
  5. Update the $PxMgmtSrcAddrPrefixes installation variable in your stored initialization script to match your changes applied to the NSG to keep the script in sync with your actual deployment.

Mandating the use of Availability Zones

By default the Teams Connector uses Azure Availability Zones if they are available in the selected region. However if you want to mandate the use of Availability Zones you can add an extra parameter to the call to create_vmss_deployment.ps1 in your installation/redeployment script.

The parameter is -UseAvailabilityZones and can be set to either "BestEffort" (the default) or "Mandatory".

If you use "Mandatory" and Availability Zones are not available in the selected region then the deployment will fail with an error: "Availability zones not available for the selected region or the VM type is not available in the availability zones". See Azure regions with Availability Zones for the list of supported regions.

Monitoring the Teams Connector

This section contains optional configuration in Azure for administrators who want to collect metrics and Windows event logs into Azure log analytics workspace and Azure Monitor Metrics (in preview at the time of writing).

  1. From within the Azure portal, go to the Teams Connector's dynamic resource group and select + Create.
  2. Use the search bar to find and select Log Analytics Workspace.
  3. Select Create to add the Log Analytics Workspace in your dynamic resource group.

    1. Your subscription and resource group should be preselected.
    2. Enter a Name, for example "pexip-teams-connector-log-analytics".
    3. Select a Region.
    4. Select Review + Create.

    5. Select Create (after the validation stage completes).
  4. Wait for the workspace deployment to complete and select Go to resource.
  5. Go to Agents management and select Data Collection Rules.
  6. Select + Create to create a Data Collection Rule.

    1. On the Basics tab:

      1. Enter a Name, for example "pexip-teams-connector-dcr", and select a Region.
      2. Leave the Platform Type as Windows.
    2. On the Resources tab:

      1. Select + Add resources.
      2. Use the search bar to find, select and Apply the Virtual machine scale set for your Teams Connector.
    3. On the Collect and deliver tab.

      1. Select + Add data source.
      2. Choose a Data source type of Performance counters.
      3. Select the required performance counters.
      4. As a Destination, select Azure Monitor Logs and choose your log analytics workspace. You can also send these metrics to Azure Monitor Metrics (in preview at the time of writing).
      5. Select Add data source.
      6. Add a second data source: repeat the above steps for a data source of Windows event logs.
      7. Select Review + Create, and then select Create.

  7. This installs extension AzureMonitorWindowsAgent onto your VMSS instances. The agent will start sending metrics and logs to your log analytics workspace, although this can take some time.

Reviewing your log analytics workspace status and metrics

From within your log analytics workspace resource, you can go to Monitoring > Insights (or Settings > Agents management) to check whether the agents are connected to your workspace.

In the Log analytics workspace you can query the event logs or performance metrics in the General > Logs pane.

In Azure Monitor > Metrics you can view the metrics/logs of the VMSS by selecting the correct scope pointing to the resource itself. In Metrics you can either choose "guest" or "host" metrics.

The above is only an example of monitoring configuration. If you want to persist the log analytics workspace, you could deploy it in the static resource group and only recreate the data collection rules after each Teams Connector redeployment. Monitoring can also be set up against an already existing log analytics workspace. You can also collect custom performance counters and custom event logs.

Enabling diagnostic logs

Most of the Azure resources support sending of diagnostic logs to a specified destination. To enable some of these to output logs to log analytics workspace, see the following settings.

Key Vault

Event Hub

VMSS

  1. Go to VMSS resource > properties and copy resource ID.
  2. Go to Log analytics workspace resource > properties and copy resource ID.
  3. Decide on your data retention (specified in days).
  4. Enable diagnostic settings using PowerShell. Make sure you connect to the correct tenant and subscription beforehand.
Copy to clipboard
$resourceId = {previously retrieved resource id}
$workspaceId = {previously retrieved workspace id}
# Modify retention in days based on your requirements
$retentionDays = 30
Set-AzDiagnosticSetting -ResourceId $resourceId -Enabled $True -WorkspaceId $workspaceId -RetentionEnabled $True -RetentionInDays $retentionDays -EnableLog $true -EnableMetrics $true

Data retention for the whole log analytics workspace

See this article for information about configuring the default workspace retention policy.

Removing old Bit-locker encryption keys (BEKs)

The Bit-locker encryption keys (BEKs) for encrypting drives of the Teams Connector VMs are stored in a key vault. During an upgrade of the Teams Connector to a new version, these VMs are recreated, but the encryption keys of the deleted VMs are not purged.

Keeping old BEKs in the key vault does not impose any risk. However, if still you want to delete the old BEKs, we have provided a suitable PowerShell script. When running the script:

  • Run the relevant variables initialization script first, for the the Teams Connector whose keys you want to purge.
  • Execute the script below from the folder into which you extracted the files from the Teams Connector ZIP.
  • If your key vault has network restrictions you will need to whitelist your host IP before running the script (see this Microsoft article for more information).
  • Your user account also needs the “Key Vault Secrets Officer” (or similar) role over the scope of the key vault.
Copy to clipboard
# Set execution policy for the current PowerShell process, when prompted type A (Yes to All)
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process

# The Unblock-File cmdlet lets you run PowerShell script files that were downloaded from the internet.
# By default, these files are blocked to protect the computer from untrusted files.
Get-ChildItem -Recurse | Unblock-File

$ErrorActionPreference = "Stop"

# Import the PexTeamsCviApplication PowerShell module
Import-Module .\PexTeamsCviApplication.psm1

# Import Az Powershell modules
Import-PexAzurePowershellModules -ErrorAction Stop

# Set VMSS name
$PxVmssName = "$($PxBaseConnName)$($PxVmssRegion)"

# Login and set subscription
Connect-AzAccount -Subscription $PxSubscriptionId

# Get the key vault name from the static resource group
$PxKeyVaultName = (Get-AzKeyVault -ResourceGroupName $PxTeamsConnStaticResourceGroupName) | Select-Object -First 1 -ExpandProperty VaultName

$BEKInUse = New-Object System.Collections.Generic.List[string]

# Get active VM disks and related keys, save them to $BEKInUse array
$vmssVms = Get-AzVmssVM -ResourceGroupName $PxTeamsConnResourceGroupName -VMScaleSetName $PxVmssName -InstanceView -ErrorAction SilentlyContinue

foreach ($vm in $vmssVms) {
$BEKInUse.Add($vm.InstanceView.Disks[0].EncryptionSettings.DiskEncryptionKey.SecretUrl.Split("/")[-2]) # OS disk
$BEKInUse.Add($vm.InstanceView.Disks[1].EncryptionSettings.DiskEncryptionKey.SecretUrl.Split("/")[-2]) # Data disk
}

$BEKToDelete = New-Object System.Collections.Generic.List[string]
$BEKToSave = New-Object System.Collections.Generic.List[string]

# Get all secrets from the key vault
$allSecrets = Get-AzKeyVaultSecret -VaultName $PxKeyVaultName | Where-Object { $_.ContentType -eq "BEK" }

foreach ($secret in $allSecrets) {
if ($secret.Name -in $BEKInUse) {
$BEKToSave.Add($secret.Name)
} else {
$BEKToDelete.Add($secret.Name)
}
}

$BEKToDeleteCount = $BEKToDelete.Count
$BEKToSaveCount = $BEKToSave.Count

Write-Host "$BEKToDeleteCount secrets will be deleted."
foreach ($BEK in $BEKToDelete) {
Write-Host $BEK
}

Write-Host "$BEKToSaveCount secrets are in use."
foreach ($BEK in $BEKToSave) {
Write-Host $BEK
}

if ($BEKToDeleteCount -eq 0) {
Write-Host "No secrets to delete"
} else {
Write-Host "Continuing will delete '$BEKToDeleteCount' total secrets"
Read-Host -Prompt "Press ENTER to continue or CTRL+C to quit" | Out-Null

# Delete BEKs in $BEKToDelete array
foreach ($BEK in $BEKToDelete) {
try {
Remove-AzKeyVaultSecret -VaultName $PxKeyVaultName -Name $BEK -Force -ErrorAction Stop
Write-Host "Secret $BEK deleted"
} catch {
Write-Warning $_.Exception.Message
}
}

Write-Host "Continuing will purge '$BEKToDeleteCount' total secrets"
Read-Host -Prompt "Press ENTER to continue or CTRL+C to quit" | Out-Null

# Purge BEKs in $BEKToDelete array
foreach ($BEK in $BEKToDelete) {
try {
Remove-AzKeyVaultSecret -VaultName $PxKeyVaultName -Name $BEK -InRemovedState -Force -ErrorAction Stop
Write-Host "Secret $BEK purged"
} catch {
Write-Warning $_.Exception.Message
}
}
}

Uninstalling the Teams Connector

This section describes how to completely remove a Teams Connector installation, for example if you have a test system that you no longer need.

  1. Delete all of the resource groups from Azure:

    1. Identify all of your existing Teams Connector resources in Azure: in the Azure portal, for your subscription, go to Resource groups and search for the prefix that you used when naming your resources — this is the value of the $PxBaseConnName variable in the initialization script.

      You will see resource groups with names in the following formats:

      • <prefix>-TeamsBot-RG: this contains the Azure Bot.
      • <prefix>-TeamsConn-<blue/green/region>-RG: this contains the Teams Connector instances (Virtual Machine scale set).
      • <prefix>-TeamsConn-<blue/green/region>-static-RG: this includes the Azure Key Vault and the public IP address of the Teams Connector.

      If you have followed a blue-green deployment strategy or deployed a Teams Connector in multiple regions you will see several <prefix>-TeamsConn-... resource groups.

    2. Select each resource group in turn (with the prefix of the Teams Connector you want to delete), and then select Delete resource group and confirm with the name of the resource group.

      Note that the Azure Key Vault is only soft-deleted when the static resource group is deleted. This means that if you subsequently redeploy your Teams Connector using the same variables initialization script, you will encounter deployment errors due to conflicts with key vault object names. To avoid this you must first purge the soft-deleted key vault:

      1. Go to the Key Vaults services within Azure.
      2. Select Manage deleted vaults.
      3. Select the subscription and purge the key vault.

  2. Remove the App registrations from Azure:

    1. Within the Azure portal, select Azure Active Directory.
    2. Under Manage, select App registrations.
    3. Select the app registrations (the CVI app and the API apps) with the prefix of the Teams Connector you want to delete, and then Delete them.
  3. Remove the Cloud Video Interop service provider from your tenant:

    1. Start a PowerShell session and run the following commands to sign in to your Teams tenant:

      • In all standard deployments run:

        Import-Module MicrosoftTeams

        Connect-MicrosoftTeams

      • If this is a GCC High / Azure US Government Cloud deployment then use these commands instead:

        Import-Module MicrosoftTeams

        Connect-MicrosoftTeams -TeamsEnvironmentName TeamsGCCH

    2. Run the command:

      Remove-CsVideoInteropServiceProvider -Identity Pexip

      To run the command, you need the Global administrator role.

  4. Remove references to the Teams Connector from the Pexip Management Node:

    1. Change or delete any locations, Virtual Receptions or Call Routing Rules that are using the Teams Connector.
    2. Go to Call control > Microsoft Teams Connectors and delete the Teams Connector address.
  5. Remove from DNS the record that refers to the FQDN of the Teams Connector load balancer.