Move from one environment to another for Azure DevOps on-premises

Article
05/29/2019

TFS 2017

The most common environment-based move scenario is changing the domain of the Azure DevOps Server deployment, whether it's a domain name change or going from a workgroup to a domain.

Important

In some situations you might want to change the domain of a Azure DevOps Server deployment as well as its hardware. Changing the hardware is a restoration-based move, and you should never combine the two move types. First complete the hardware move, and then change the environment.

Additionally, changing identities in Azure DevOps Server as part of an environmental move is the aspect that most often causes conflicts or problems. The Identities Command is a powerful tool, but it has certain limitations. Read up about it as part of planning your move. To help ensure a successful move, make sure that you understand the following requirements:

Once a user account is present in Azure DevOps Server, it cannot be removed or have another account mapped to it. For example, if you are moving DomainA/UserA to DomainB/UserB, the Identities command would only work to migrate the user if DomainB/UserB is not already present in Azure DevOps Server.
Because the members of the local Administrators group are automatically added to Azure DevOps Server, make sure to remove any accounts that you want migrated from that group before you change the domain or environment.

For further background information, go here for a detailed description of how identity changes in Azure DevOps Server work, including limitations of the tool.

We'll walk through the steps to change the environment of your Azure DevOps Server deployment in the following sections:

Check permissions and accounts
Stop Azure DevOps Server services
Back Up Data
Join Azure DevOps Server to its new domain
Configure SharePoint Products for the new environment
Move Azure DevOps Server user and service accounts
Configure Reporting and Analysis Services
Restart Azure DevOps Server services

Check permissions and accounts

In order to successfully change the environment for Azure DevOps Server, you'll need to be an administrator on the local computer as well as for Azure DevOps Server and all of the software on which your deployment depends: SQL Server, reporting, SharePoint Products (if your deployment uses reporting or SharePoint), and any other software with which your deployment interoperates, such as Project Server. However, all members of the local Administrators group are automatically included in Azure DevOps Server, which can cause problems when trying to migrate accounts. Therefore, you should use an account that you do not intend to migrate as part of the environmental move. You might consider adding a special administrative account just for the move, and using that account to perform the migration.

To verify administrator-level permissions

Make sure the account you're using is a member of the following groups:
- Servers: Administrators (local Administrators group or equivalent)
- Azure DevOps Server: Team Foundation Administrators and Admin Console Users
- SQL Server: sysadmin
- SharePoint Products: Farm Administrators (if your Azure DevOps Server deployment integrates with SharePoint Products)

If you aren't a member of one or more of these groups, get permissions now.

Now that you're sure you're using an account that has all the permissions needed, it's time to start checking accounts to see if there might be any conflicts with names or groups in the environment to which you'll be moving. We already know that accounts that are members of the local Administrators group can't be migrated, so let's remove those first.

Remove accounts to be migrated from local Administrators group

Open the local Administrators group and remove any accounts that you wish to migrate to the new environment. Repeat this step for any other groups that might be affected.

Now check the list of identities in the current Azure DevOps Server environment and look for any potential problems with groups or individual user accounts that might exist in the new environment.

Tip

Consider creating a table or migration map of identities to be moved as part of the environmental move, including details of which accounts might not be able to be migrated automatically.

Check identities

On the application-tier server for Azure DevOps, open a Command Prompt window with administrative permissions, navigate to %ProgramFiles%\Microsoft Visual Studio 12.0 Team Foundation Server\Tools, and run the following command to view the identities currently in the system:
```
TFSConfig Identities
```
A list of identities will display. Check these users and groups to ensure that there are no potential duplicates or problems with identities in the environment to which you'll move Azure DevOps Server, and take steps to mitigate any potential conflicts.

Stop services

Stopping the services helps ensure that users cannot make changes to work items or check in source code to the original deployment during or after the move process.

On the application-tier computer, open a Command Prompt window, and change directories to Drive:\%programfiles%\TFS 12.0\Tools.
Type the following TFSServiceControl command:

TFSServiceControl quiesce

Back up the databases and the SQL Server Reporting Services encryption key

Open the administration console for Azure DevOps Server and on the Scheduled Backups page, take a full backup. The backup will back up everything you configured for backup in your backup plan, but it will do so immediately, not according to the time scheduled in the plan. If your deployment uses reporting, you can back up the encryption key as part of this backup set.

(If you don't have backups configured, you'll have to create a plan before you can take a full backup.)
Once the backup completes, verify that the backup is available on the storage device or network share, and that you can access this backup from the new hardware.

Join the application tier server to its new domain

On each server, open the properties for the computer.
Change the settings for the computer to the domain or workgroup to which you want to join the server.

If you are prompted to provide the user name and password of an account that has permissions to join this computer to the domain, provide the appropriate credentials.
Restart the computer for the domain change to take effect.

Note

After you restart the computer, a warning might appear that services or drivers could not be started. Continue with the next procedure.

Configure SharePoint Products for the new environment

If you are changing the environment to one where there is no trust with your previous environment, you might need to configure SharePoint Products before it will operate correctly. Information about users imported from directory services is available on SharePoint sites from the People Picker Web control. Site administrators and other users use the People Picker to select people and groups when assigning permissions. When information about users is located on multiple forests or on a forest without a trust relationship for all users, additional steps might be necessary to ensure that all people and groups are available from this Web control.

Skip this procedure if you are not using SharePoint Products in your deployment, if you're new environment has a two-way trust to the old environment, or if no errors for your SharePoint Web application appear in the administration console for Azure DevOps.

On every server that is part of the SharePoint farm that supports your deployment of Azure DevOps Server, open a Command Prompt window with administrative permissions, and change directories to %programfiles%\Common Files\Microsoft Shared\Web Server Extensions\15\BIN.
Type the following command, where Key is the encryption key you want to use in your deployment of SharePoint Products:

stsadm.exe -o setapppassword -password Key

Note

This key is an encryption string that is used to encrypt the password for the account that is used to access the forest or domain. The encryption string must be the same for every server in the farm, but a unique string should be used for each farm.
Type the following command, where domain:DNSName is the target forest or domain and its DNS name, user,password is the username and password for an account that has access to the target forest or domain, and WebApp is the name of the Web application that supports your deployment of Azure DevOps Server:

stsadm.exe -o setproperty -pn peoplepicker-searchadforests -pv domain:DnsName,user,password -url http://WebApp
Type the following command, where URL is the URL for a site collection that supports a project collection, Port is the port number that is assigned to that site collection, and UserName is the user name of the account that will act as the owner for that site collection:

stsadm.exe -o siteowner -url http:// URL : Port -ownerlogin UserName
Repeat the previous step for each site collection that your deployment of Azure DevOps Server uses.

Move user accounts and service accounts

As mentioned at the beginning of this topic, moving accounts is when you're most likely to encounter difficulties, particularly if you haven't carefully planned for user migration. The TFSConfig Identities command cannot migrate any account to an account that already exists in Azure DevOps Server.

If account names are the same in both domains, and the only difference is the domain name, then you can use the batch mode of TFSConfig Identities to change all the identities at once. Otherwise you must change identities individually and specify a different target account name, as detailed below.

On the application-tier server for Azure DevOps, open a Command Prompt window with administrative permissions, navigate to %ProgramFiles%\Microsoft Visual Studio 12.0 Team Foundation Server\Tools, and run the following command to change the service IDs (SIDs) for the service account to the new domain:
```
TFSConfig identities /change /fromdomain:OldComputerorDomainName /todomain:NewDomainName /account:OldTFSServiceAccount /toaccount:NewTFSServiceAccount
```
Warning

If your service account was a system account such as Network Service, you cannot directly migrate the service account, because a system account with the same name exists in the new environment. You'll have to perform a two-stage process change. See the example in Identities Command.
To migrate all accounts that have the same name in the new environment, type the following command:
```
TFSConfig Identities /change /fromdomain:OldDomainName /todomain:NewDomainName
```
This will batch process the accounts.
if you're new domain contains one or more identities where the name changes between environments, you'll need to manually update the SIDs for each of those identities. For example, if Christie Church's user account was Fabrikam\CChurch in the previous environment, but is NewFabrikam\ChristieC in the new environment, you would have to manually update her SID. For every account that has this requirement, type the following command:
```
TFSConfig Identities /change /fromdomain:OldDomainName /todomain:NewDomainName /account:OldAccountName /toaccount:NewAccountName
```

Now run the following command to update the service account:

TFSConfig Accounts /change /AccountType:ApplicationTier /account:AccountName /password:Password

If your deployment uses reporting, run the following command to update the data source account used for reporting:
```
TFSConfig Accounts /change /AccountType:ReportingDataSource /account:AccountName /password:Password
```
If your deployment uses Azure DevOps Proxy Server, run the following command to update the service account used for the proxy:
```
TFSConfig Accounts /change /AccountType:Proxy /account:AccountName /password:Password
```
Note

If you are moving to a non-trusted domain, you might also need to manually add users and groups to teams, projects, collections, and Azure DevOps Server itself. For more information, see Add users to projects, Set administrator permissions for project collections, and Set administrator permissions for Azure DevOps Server.
If your deployment is integrated with Project Server, you might need to perform additional steps to configure the service accounts with the permissions required for operation. For more information, see Assign permissions to support TFS-Project Server integration and ConfigureTFS-Project Server integration.

Configure Reporting and Analysis Services

You can skip this procedure if you are not using reporting as part of your deployment.

If you renamed a report server as part of this type of move, you must redirect Azure DevOps Server to the report server at its new location. You must also restart the warehouse and manually rebuild the database for Analysis Services.

Open the administration console for Azure DevOps, go to the Reporting node, and edit the settings.
Change the values on all three tabs so that they include the new name of the server. Make sure that you provide the correct information for the data sources account in the new environment.
Choose Start Jobs to restart reporting.
Choose Start Rebuild to rebuild the warehouse.

Configure backups

If the network share name or storage device changed with the domain name change, you'll need to update the scheduled backup plan to point to those renamed resources.

In the administration console, go to the Scheduled Backups node and reconfigure the scheduled backups to back up the Azure DevOps Server databases on the new server. For more information, see Create a backup schedule and plan.

Restart services

Now that you've updated Azure DevOps Server with all the information for the new environment, restart the services.

On the Azure DevOps Server application-tier computer, open a Command Prompt window with administrative permissions and change directories to Drive:\%programfiles%\TFS 12.0\Tools.
Type the following TFSServiceControl command:

TFSServiceControl unquiesce

Q & A

Q: I want to change the physical server or servers for my deployment, not domains. Can I do that?

A: Yes. That's called a hardware-based move, and the steps are provided in Move or clone from one hardware to another. You should not try to combine an environment-based move with a hardware-based move. First complete the hardware move, and then change the environment.

Share via