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.

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 Teams Connector's certificate.
  • 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).

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, or if you need to modify the number of Teams Connector instances.

Upgrading the Teams Connector to the latest software

When upgrading the Teams Connector to version 29, you must redeploy it using your original variables initialization script (although you may apply any configuration changes, if required), and with the latest application software files and v29 redeployment script, as described below.

When upgrading your Teams Connector to version 29:

New upgrade steps for version 29

  • You must install the Microsoft Graph PowerShell module by running the following PowerShell command (as Administrator):

    Install-Module -Name Microsoft.Graph -MinimumVersion 1.9.2

    Note that the installation of Graph can take 5-10 minutes. Wait until you the get PS prompt back (several minutes after the install reports as completed) before continuing.

  • There is a new mandatory $PxUseAzureHybridBenefit variable you must specify in the variables script that defines whether to enable license optimization if your organization uses Azure Hybrid Benefit. You must set this variable to either $true or $false.

Standard upgrade steps

  • When upgrading from a previous major release (e.g. from v27.n to v29.1), you must use the latest version of the redeploy script as contained here. You can use your existing redeploy script if you are upgrading to a new minor/ "dot" release for the same major version (e.g. from 29.0 to 29.1).

    When using a new redeploy script, update the two lines in the redeploy script that say:

    $AppId = ""
    $AppPassword = ""

    to contain the Pexip CVI app ID and password from the version of the redeploy script you saved from your existing deployment.

  • You must be using Az module version 5.1.0 or later.

    • To check your installed version you can run:
      Get-InstalledModule -Name Az -AllVersions

    • To install the latest appropriate Az version you can run:
      Install-Module -Name Az -MinimumVersion 5.1.0 -AllowClobber -Scope AllUsers
  • If you have deployed multiple Teams Connectors, you must follow the same redeploy process (with the appropriate variable initialization script) for each Teams Connector.
  • As with all upgrades, you can continue to use the Pexip CVI app from your existing deployment.

If you are currently running version 26, as with Pexip Infinity, you should also upgrade your Teams Connector to version 27 before upgrading your entire platform to v29. See our previous documentation for information about the upgrade steps and the changes introduced in v27.

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 its certificate, or 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.

There are three main steps to redeploying the Teams Connector:

  1. Check that you have the latest relevant version of the Teams Connector software, and your variable initialization and redeploy scripts.
  2. Delete the previous dynamic resource group and then recreate it for the new deployment, and ensure that the person performing the redeployment has the appropriate role for the resource groups in each region.
  3. Reinstall the Teams Connector software.

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

  1. Download the latest relevant version of the Teams Connector ZIP file (Pexip_Infinity_Connector_For_Microsoft_Teams_v29.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 certificate for the Teams Connector to this folder.
  4. Retrieve your saved copies of the initialization and redeploy scripts. You should have created and stored your version of these scripts after you completed your initial installation of your first Teams Connector.

  5. Check your saved copy of the initialization script that sets the environmental variables:

    • 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, ensure that you have the correct versions of the initialization scripts that set the regional variables to the appropriate values.
  6. Check your saved copy of the redeploy script:

    • If you are upgrading to v29, ensure that you use the latest version of the redeploy script instead of your previously saved copy, but that you have updated it with your Pexip CVI App ID and credentials from your previously saved copy, as described immediately below.
    • Confirm that the redeploy script contains your Pexip CVI App ID and credentials:

      • When the installation script ran, it generated some output that listed the CVI App ID and credentials, similar to this:

      • These output lines should have been used to replace the two existing lines in the redeploy script that say:

        $AppId = ""
        $AppPassword = ""

        This means that when you run the redeploy script, you will reuse the CVI app and password 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 for your 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:

    Connect-AzAccount

    Then follow the prompts to sign in to Azure.

  2. Run the variable initialization script that you used when your first installed the Teams Connector (to set the required subscription, resource group name and 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 existing dynamic resource group and then recreates it for the new/redeployed Teams Connector.

    Copy to clipboard
    # Remove the existing dynamic resource groups
    $PxTeamsConnResourceGroup = Get-AzResourceGroup -Name $PxTeamsConnResourceGroupName -Location $PxAzureLocation
    if ($PxTeamsConnResourceGroup)
    {
        $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!"
    }

    # Create Resource group for Teams Connector VMSS (per region)
    # This 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 performing the redeploy/upgrade has the Azure Owner role for the static and dynamic resource groups, and Contributor role for the Azure Bot resource group. If you have deployed in multiple regions you must do this for all of the resource groups in each region.

    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 also 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. In PowerShell, run your initialization script that sets the environmental variables.

    If you have Teams Connectors in many regions, ensure that you run the version of the initialization script that sets the regional variables to the appropriate values.

  2. In PowerShell run your redeploy script.

    You only need one version of this script — you can use the same script in every region if you have multiple Teams Connectors.

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 29. If you are using an earlier version you should refer to our previous documentation.

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 "29"){Write-Warning "The Connector version (extracted ZIP files) and this deployment script version do not match. Connector version = $PxConnMajorVersion. Deployment script version = 29"}

# 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

# Connect to Azure with an authenticated account for use with Azure Resource Manager (in same window to reuse variables)
# If the Import-Module step fails, ensure you have a suitable version of Az installed (5.1.0+)
Remove-Module "Az*" -ErrorAction SilentlyContinue
Import-Module Az -MinimumVersion 5.1.0
Connect-AzAccount

# Before running the following commands, update the following 2 lines/variables with the CVI App ID and password
# that were output when the installation script was run
$AppId = ""
$AppPassword = ""

# Change context to the Pexip Subscription and set the app credentials
Set-AzContext -SubscriptionId $PxSubscriptionId

$AppSecurePassword = ConvertTo-SecureString -AsPlainText $AppPassword -Force
$AppCred = New-Object System.Management.Automation.PSCredential -ArgumentList $AppId,$AppSecurePassword

# 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 variables above) 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 -ResourceGroupName $PxTeamsConnResourceGroupName -VmssName "$($PxBaseConnName)$($PxVmssRegion)" -VMAdminCredential $PxWinAdminCred -PfxPath $PxPfxCertFileName -TeamsConnectorFqdn $PxTeamsConnFqdn -PexipFqdns $PxNodeFqdns -instanceCount $PxTeamsConnInstanceCount -AppCredential $AppCred -StaticResourcesResourceGroupName $PxTeamsConnStaticResourceGroupName -IncidentReporting $PxTeamsConnIncidentReporting -RdpSourceAddressPrefixes $PxMgmtSrcAddrPrefixes -PexipSourceAddressPrefixes $PxNodesSourceAddressPrefixes -WupdScheduledInstallDay $PxWupdScheduledInstallDay -WupdScheduledInstallTime $PxWupdScheduledInstallTime -WupdActiveHoursStart $PxWupdActiveHoursStart -WupdActiveHoursEnd $PxWupdActiveHoursEnd -CustomerUsageAttribution $PxCustomerUsageAttribution -UseAzureHybridBenefit $PxUseAzureHybridBenefit -Tag $tags -TeamsConnectorApiApplicationId $TeamsConnectorApiApplicationId

# supply the PFX certificate file password when prompted

# Please enter the password for the 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

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 following script 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.

Copy to clipboard
# Get the API application registration reference
$apiApp = Get-AzureADApplication -Filter "AppId eq '${TeamsConnectorApiApplicationId}'"

# Get the assignee
# Note that in case of external users (guests in a tenant) the -ObjectId parameter is in form "<email_name>#EXT#@<tenant_url>"
$user = Get-AzureADUser -ObjectId <email_name>

# Assign owner role for the API application registration to the assignee
Add-AzureADApplicationOwner -ObjectId $apiApp.ObjectId -RefObjectId $user.ObjectId

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

# Assign owner role for the API application service principal to the assignee
Add-AzureADServicePrincipalOwner -ObjectId $apiAppSp.ObjectId -RefObjectId $user.ObjectId

Maintaining 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 120) 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.

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 initialization script to keep it 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 "Alternate 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" -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"

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"

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.

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. (If your Teams Connector was installed prior to version 27 then the name uses the format <prefix>-TeamsBotChan-RG instead.)
      • <prefix>-TeamsConn-<region>-RG: this contains the Teams Connector instances (Virtual Machine scale set).
      • <prefix>-TeamsConn-<region>-static-RG: this includes the Azure Key Vault and the public IP address of the Teams Connector.

      If you have 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 as from v26, 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 two app registrations (the CVI app and the API app) 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:

      Import-Module MicrosoftTeams

      Connect-MicrosoftTeams

    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.