How to: Migrate BIG-IP application configurations onto BIG-IP Next Central Manager¶

Migrate your BIG-IP applications (version 12.1 or later) and their application management services into BIG-IP Next. From BIG-IP Next Central Manager, you can use each managed BIG-IP device’s UCS file to migrate the device’s application services and deploy to a BIG-IP Next instance.

Bulk operations are not required, as you can select specific applications for migration. You can perform this process multiple times to ensure high priority applications are migrated first. An increased number of applications selected per migration will impact the time required to complete the migration process.

For a full overview of application migration, see Migrate BIG-IP application configurations onto BIG-IP Next Central Manager.

Prerequisites¶

BIG-IP Next tenants are instantiated on your Virtual Environment (VE), VELOS, or rSeries.
You must have Administrator or Application Manager user credentials to manage application migration. Users with Instance Manager or Auditor credentials have read-only access to the migration process. For more information about user roles, see How to: Assign standard roles to users.
BIG-IP Next instances are onboarded with VLAN and self IP configuration. See How to: Onboard BIG-IP Next and Central Manager with a setup script.
(Optional) BIG-IP Next instances are added to BIG-IP Next Central Manager.
A downloaded UCS file (max size 4GB) from each BIG-IP device (version 12.1 or later) that hosts the applications you would like to migrate. Learn how to generate a UCS file.

Summary of procedures using the migration wizard¶

The following procedures are required to complete migration:

Upload BIG-IP UCS to BIG-IP Next Central Manager - Upload a BIG-IP device’s UCS file to detect application services and their virtual servers.
Migrate application services - Migration application services by selecting application services and modifying/viewing their virtual servers
Application service pre-deployment - Prepare your applications for deployment and save application services and their objects to BIG-IP Next Central Manager.

Migrate a BIG-IP UCS to BIG-IP Next Central Manager¶

This procedure creates application services for the virtual servers found on the uploaded UCS. This stage is Source BIG-IP System in the migration wizard.

Note: Migration supports UCS files of up to 4GB.

This is the Source BIG-IP System stage of the migration wizard¶

Log in to BIG-IP Next Central Manager as admin, click the Workspace icon next to the F5 icon, and click Applications.
At the top of the screen, click Add Application.
From the Migrate Application(s) area, click New Migration.

Note: If you have already imported your applications, but have not completed the migration process, click Resume Migration to select an existing migration session.
For General Properties, type a Session Name (without whitespace) and an optional Description.
Click Save & Continue.
For Source BIG-IP System add the UCS file and customize encryption and merge preferences for the BIG-IP virtual servers:
1. In the UCS File area, upload your UCS file by dragging and dropping in the upload area, or click the upload icon to select the file from your local system.
  
  Note: This process may take a few minutes. The size and complexity of the file can impact the amount of time required.
2. From How would you like to group your application services? select one of the following options:
  1. Group by IP Addresses (Recommended) - Virtual servers with the same IP address are automatically grouped into one application service. Later in the migration process you can modify application services’ virtual servers and rename the applications services. This selection consolidates the number of application services and allows for better management.
  2. Group by Virtual Server - Each virtual server becomes an application service.
3. (Optional) Enable Master Key to apply a master key using BIG-IP Next Central Manager. The master key is used to decrypt and encrypt fields and files in the source configuration. If you do not apply a master key, you might not be able to migrate an application that uses SSL certificates and keys (e.g. HTTPS) to BIG-IP Next instances.
  1. Enter the Master Key password.
4. (Optional) Enable Encrypted UCS Archive to provide password encryption for the UCS if it was used on the BIG-IP device.
  1. Enter the Encrypted UCS Archive password.
5. Click Save & Continue to select applications for migration.
Note: You can click Save & Exit to save your progress and resume migration at a later time.

You have completed the import from the source BIG-IP system.

Migrate application services¶

Once you have imported the UCS file that contains your source BIG-IP system’s application services, you can select which application services and virtual servers are migrated to BIG-IP Next Central Manager.

Objects or entities that are not supported on BIG-IP Next are automatically modified, removed, or must be saved to BIG-IP Next Central Manager for manual changes to the AS3 declaration. You will receive a status notification regarding migration readiness of every application service (statuses yellow, blue, red, or green).

Note: If a virtual server’s status is red it is not eligible for migration. You must move the virtual server from the application service you intend to migrate.

This stage is Application Migration in the migration wizard.¶

Click Add Application. This action opens the BIG-IP Applications panel, which lists the BIG-IP application services and the virtual servers found on the UCS file. Each row specifies the virtual server and its IP address, security policies, status, and last date modified. The status indicates whether the application’s virtual servers contain unsupported objects (yellow) and/or unsupported security objects relating to certificate (blue) , or contains virtual servers that are not supported by BIG-IP Next (red) .
You can verify which objects in the services will be modified, removed, or present issues with deployment during the application conversion:
1. Click the service, or select multiple services and click Analyze to open the configuration analyzer.
2. Review the conflicts in the service. Conflicts are underlined, except for multiple SSL Profiles. See the example below of a virtual server with two SSL profiles of the same type:
```
"certificate": "<Paste your SSL cert content here>",
"class": "Certificate",
"privateKey": "<Paste your SSL key content here>"
}, 
```

To quickly locate a conflict in the service, look at the Summary section on the right - a line indicates the conflicting object’s location. Clicking there will bring you to the location of the object in the edit window.

Note: Some configurations are not eligible for deployment, and require manual changes. You can save the AS3 declaration to BIG-IP Next Central Manager and manually remove or customize the application service before you deploy. See How to: Troubleshoot AS3 application migration to BIG-IP Next Central Manager.

Click Preview AS3 </> to view a read-only declaration after it is migrated to BIG-IP Next.
Click Close to close the service panels and return to the BIG-IP Application Services panel.
To move virtual servers to a different application service:
1. Expand the application service to review the virtual servers.
2. Select the check box next to the virtual server you would like to move
3. Click Move from the top right of the panel and select the name of the application service target.
Note: You can move virtual servers to better group the objects and services, or to remove a virtual server that may cause issues with deployment. The image below is an example of an application service that contains a wildcard virtual server, which is not supported for deployment. The virtual server that is ready for deployment is moved to a different application service:
To rename an application service:
1. Select the check box next to the application service.
2. Click Rename.
3. Enter a new name for the application service
4. Click Ok.
Note: You are not able to save an application service with a name that already exists on BIG-IP Next Central Manager.
Select the check box of the services you would like to migrate.
Click Add. The services are added to the Application Migration list.
Click Save & Continue.

You have completed the migration process, and are now ready for pre-deployment which includes selection of application objects and deployment location.

If selected application services contain certificates, iRules, or WAF policies these objects can be imported to BIG-IP Next Central Manager. Migrated objects receive an automatic prefix and suffix to indicate that the object was migrated, and to prevent duplication in BIG-IP Next instances.

When multiple objects in a UCS have the same name, the folder and partition is added to the prefix to further avoid duplication. See the sample certificate migration: migrated_{originalPartition}*_{originalFolder}*_{originalCertificateName}_{sessionId}

Application service pre-deployment¶

Application services selected in Application Migration are prepared as an AS3 declaration. At this stage, you have the option to save the AS3 declaration as a draft (without deploying) and to import objects such as certificates and keys, iRules, and WAF policies to BIG-IP Next Central Manager.

When you import objects they are available on BIG-IP Next Central Manager for use in all BIG-IP Next application services. Any changes to objects on BIG-IP Next Central Manager are automatically updated in attached application services, once the application service is re-deployed.

This is the Pre Deployment stage of the migration wizard.¶

To import the shared objects found on the migrated applications:
1. Review each application service’s shared object, click the number in the Shared Objects column. The Import summary panel displays the object type, previous name, updated name to prevent migration errors, and the installation status on the migrated application.
2. Click Import to close the panel and import the objects to BIG-IP Next Central Manager. See the example below:
3. To immediately import all application service objects, click Import directly from the application services list.
(Optional) To view the virtual servers included in each application service, click the number in the Virtual Servers column. This allows you to review the virtual servers and their statuses. A virtual server that has multiple objects (such as WAF policies or SSL profiles of the same type) or unsupported virtual servers cannot be deployed to an instance. If you would like to change the application service’s virtual servers, you can click Back and change the application service for migration. See example below:
Note: Certain types of virtual servers are not supported on BIG-IP Next. The following types of virtual servers will have a red status (not able to deploy) and should be moved from an application service you would like to deploy to an instance:
- Wildcard virtual servers (0.0.0.0/0) - Deployment is not blocked, but F5 does not recommend deploying application services with wildcard virtual servers, as it can cause behavior issues if more than one wildcard virutal server is deployed to an instance.
- Internal virtual servers
- IP forwarding virtual server
Select the BIG-IP Next instance for Deploy Location, or select Save as Draft to save the AS3 declaration to BIG-IP Next Central Manager without deploying the application service. The default location is Save as Draft, which saves the application service to BIG-IP Next Central Manager, without deploying to an instance location.

Note: Some application services contain virtual servers that cannot be deployed, as they have duplicate objects (for example WAF policies or SSL profiles of the same type) or require changes to the declaration before they can be deployed. Failure to import any shared object will require you to save the application as a draft. For more information about how to deploy application services that can only be saved as a draft see How to: Troubleshoot AS3 application migration to BIG-IP Next Central Manager.

Note: If you migrated WAF application services with a WAF policy logging scope to log all requests, you will need to manually update the logging scope. See Logging all requests from a migrated WAF policy.
To download the converted AS3 declaration(s), click Bulk Actions and then Download AS3. The AS3 declaration(s) are downloaded to your system based on your browser settings.
To deploy the migrated AS3 application services, click Deploy. This deploys the applications to the BIG-IP Next instance. You can see the application deployment status in the Deployments section of the wizard. You can click the status to view the deployment summary and log:

The migrated application services are deployed to the BIG-IP Next instance. You can view the migrated applications in the My Application Services list. If you click the application name, you can edit the AS3 declaration.

Migrate application and deploy services to BIG-IP Next - API¶

Use the following procedures to deploy migrated application services:

Create a new session for application service migration
Generate and deploy an AS3 declaration for application services

Create a new session for application service migration¶

Initiate the migration process by establishing new session and generating a session ID:

POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations

Sample request:

{
  "name": "session",
  "description": "optional description"
}

Sample successful response:

{
  "last_update_time": "2021-01-28T15:24:05.029102Z",
  "id": 0,
  "url": "sessions/{session_id}",
  "name": "session",
  "description": "optional description"
}

Provide source configuration (UCS)¶

Add the configuration (UCS file) from the source BIG-IP system to the new session. Use the session ID generated from Create a new session. Add the ucs_file to the body of the request. Include the ucs_passphrase and/or master_key if the UCS file is password protected. Define the grouping_type: * disabled - Each virtual server becomes an application service. * ip - Virtual servers with the same IP address are automatically grouped into one application service.

POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations/{migration_id}/upload

Preview virtual server list¶

Request a list of virtual servers found on the UCS.

GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations/{migration_id}/virtuals

Preview a specific virtual server:

GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations/{migration_id}/virtuals/{virtual_id}}

Stage virtual servers (application services)¶

Stages all virtual servers for the migration session:

PUT https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations/{migration_id}/virtuals-stage

To stage specific virtual server:

POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations/{migration_id}/virtuals/{virtual_id}/stage

Generate and deploy an AS3 declaration for application services¶

Create an AS3 declaration that can be deployed to a BIG-IP Next instance:

POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations/{migration_id}/output

Deploy the AS3 declaration to a BIG-IP Next instance. Ensure the instance_address (IP address) is included in the body of the post.

POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations/{migration_id}/deployments

The deployment request returns a deployment_id. You can check the progress of your deployment with the following request:

POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/migrations/{migration_id}/deployments/{deployment_id}–>

Previous Next