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 (CM), you can use each managed BIG-IP device’s UCS archive 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.
You can migrate application services to BIG-IP Next in three ways:
Migrate application services using BIG-IP Next Central Manager GUI
Migrate application services using BIG-IP Next Central Manager API
WAF policy migration¶
Migration supports WAF policies in declarative JSON format. WAF policies in XML or Binary formats are not currently supported on BIG-IP Next.
BIG-IP Next provides a single policy for all WAF services, which includes Bot Defense and L7 DoS protection. In BIG-IP, Bot Defense and L7 DoS were configured using separate profiles that were not attached to a WAF policy.
The migration process supports the single policy configuration by identifying bot and L7 DoS profiles found on the same virtual server as a WAF policy. During migration, bot and L7 DoS profiles will be automatically added to the WAF policy for an application service.
Bot and L7 DoS protection profiles that do not have a WAF policy within the same virtual server cannot be migrated.
Access policy migration¶
Access policy migration supports most Access features, however some features are not supported on this version of BIG-IP Next.
The migration process automatically imports and updates shared Access objects in their required order. For a partially supported confiugration, this allows for proper deployment of an application service that contains an Access policy. During migration stage, you proceed to deploy or save as draft only once all shared object are installed on 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 archive (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 archive.
Migrate application services to BIG-IP Next using BIG-IP Next Central Manager GUI¶
Summary of procedures using the migration view, including the following required steps to complete migration:
Upload BIG-IP UCS to BIG-IP Next Central Manager - Upload a BIG-IP device’s UCS archive 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.
Note: Migration supports UCS archives of up to 4GB.
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 Next.
For Source BIG-IP System add the **UCS archive ** and customize encryption and merge preferences for the BIG-IP virtual servers:
In the UCS File area, upload your UCS archive 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.
From How would you like to group your application services? select one of the following options:
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.
Group by Virtual Server - Each virtual server becomes an application service.
(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.
Enter the Master Key password.
(Optional) Enable Encrypted UCS Archive to provide password encryption for the UCS if it was used on the BIG-IP device.
Enter the Encrypted UCS Archive password.
Click Next 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 archive 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. You will import objects such as certificates and keys, iRules, and WAF or Access policies to BIG-IP Next Central Manager.
Objects or entities not supported on BIG-IP Next are automatically modified or highlighted. When migrating to BIG-IP Next Central Manager, they will be removed or replaced by a placeholder text, requiring you to manually update the AS3 declaration. You will receive a status notification regarding migration readiness of every application service (statuses green, yellow, or red).
Note: If a virtual server’s status is red, you can save it as a draft and will be removed during migration.
Once you upload the UCS archive, you see the list of BIG-IP application services and the virtual servers found on the UCS archive. Each row specifies the virtual server and its IP addresses, security policies, ports, status, number of shared objects, and migration readiness status. For more information about statuses, see Application migration status.
You can verify which objects in the application services will be modified, removed, or present issues with deployment during the application conversion:
Click on the application service name to open the configuration analyzer.
Review the underlined conflicts in the service. See the following example 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 will require manual changes. Hovering over conflicting objects or properties provides insights about unsupported objects, including unsupported nested properties. 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 draft, read-only declaration.
Note: To view the declaration saved as a draft in the migration process to BIG-IP Next Central Manager, click the Download AS3 button and review the downloaded file.
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:
Expand the application service to review the virtual servers.
Select the check box next to the virtual server you would like to move.
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:
Select the check box next to the application service.
Select More Actions and click Rename.
Enter a new name for the application service and click Ok.
Note: You are not able to save an application service with a name that already exists on BIG-IP Next Central Manager.
To download the converted AS3 declaration(s):
Select the check box(es) next to the application service.
Select More Actions and click Download AS3.
The AS3 declaration(s) are downloaded to your system based on your browser settings.
To create an application service:
Select More Actions and click Create.
Enter a new name for the new application service and click Ok.
To remove an application service:
Select the check box next to the application service.
Select More Actions and click Remove.
Click Confirm to remove the application service.
Note: You can only remove an empty application service.
Select the check box(es) of the application services you would like to migrate and select Migrate as Draft. By default the Include Shared Objects checkbox is selected to import the shared objects. If you unselect the Include Shared Objects checkbox, the application services migrate as a draft without any shared objects. The shared objects will be replaced by placeholder text in the AS3 declaration.
Click Yes, Migrate. After you migrate the application service, the status changes to Migrated in the Readiness column.
Note: You cannot migrate the same application service again. To re-migrate previously migrated application services, first delete them from CM.
You can import shared objects in two ways:
Select the check box next to the application service, click Import Shared Objects from the top right of the panel and click Yes, import.
Click the number in the Shared Objects column and click Import.
The Import summary panel displays the object type, previous name, updated name to prevent migration errors, and the import status of the migrated application.
Note: The migration module cannot detect if you remove the imported shared objects from the CM. To reuse it, reupload the UCS archive and import from another session.
Click + Add Filter to filter the application services based on IP address, security policies, number of shared objects, migration status and so on.
Click Save & Exit.
If selected application services contain certificates, iRules, or, Access 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 archive 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}
Note: Certain types of virtual servers are not supported on BIG-IP Next. The following types of virtual servers will have a red status and can be saved as a draft and edit in CM:
Wildcard virtual servers (0.0.0.0/0) - Saving as draft 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
Application services selected in Application Migration are prepared as an AS3 declaration. At this stage, you have the option to save the AS3 declaration.
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 (except for iRules) on BIG-IP Next Central Manager are automatically updated in attached application services, once the application service is re-deployed.
Note: If you make any changes to iRules, you must redeploy it through the application service.
To deploy the migrated AS3 application services, select the application service and review the AS3 declaration.
If you make any changes to AS3 declaration, click Save.
Click Review & Deploy.
Click Start Adding to select the BIG-IP Next instance for deploying the application services.
Click Validate to check whether the application service is valid or not.
Click Configure to review Access deployment configuration.
Click Deploy.
This deploys the applications to the selected BIG-IP Next instance.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. 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.
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 services using Postman collection¶
Download the F5 Postman collection.
Modify the Postman variables.
Create an environment or modify the collection variables.bigip_next_1_mgmt_ip: (IPv4 address of BIG-IP Next instance) bigip_next_cm_mgmt_ip: (IPv4 address of BIG-IP Next Central Manager) cm_admin_user: (admin username) cm_admin_password: (admin password)
Select the folder Chained step-by-step migration of one app.
Execute the requests Login to CM through Retrieve status of deployment operation.
Migrate application services to BIG-IP Next using BIG-IP Next Central Manager APIs¶
For a full list of API endpoints for application migration, see Migrations.
Use the following procedures to deploy migrated application services:
Prerequisite¶
Authenticate with the BIG-IP Next Central Manager API. For details refer to How to: Authenticate with the BIG-IP Next Central Manager API.
Use the following BIG-IP Next Central Manager APIs to deploy migrated application services:
Create a new session for application service migration¶
Create a new migration session for application service migration
Initiate the migration process by establishing new session and generate a session ID by sending a POST request to
/v1/migrations
endpoint.POST https://{{cm_mgmt_ip}}/api/v1/migrations
For the request payload, use the following example, modifying the values as required
{ "name": "Example_migration_name", "description": "optional description" }
Identify the session ID (
id
) from the response to upload UCS archive.Click for sample response ▶
{ "_links": { "self": { "href": "/api/v1/migrations/2" } }, "id": 2, "name": "Example_migration_name", "description": "Example migration description", "grouping_type": null, "last_update_time": "2024-06-13T09:06:15.124237Z", "task_id": null }
For more information about creating new migration session using BIG-IP Next Central Manager APIs, see OpenAPI documentation.
Upload UCS archive
Add the configuration (UCS archive) from the source BIG-IP system to the new session by sending the POST request
/migrations/<migration_id>/upload?async=true
endpoint.Replace the
migration_id
value with session ID (id
) from the response of the previous request.POST https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>/upload?async=true
For the request payload, use the following example, modifying the values as required
Add the ucs_file to the body of the request.
Include the ucs_passphrase and/or master_key if the UCS archive 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.
Note: For large UCS archives, it is recommended to use the
refresh_token
in the header instead of the regular access token.{ "ucs_file": "<path_to_ucs_file>", "grouping_type": "ip", "ucs_passphrase": "<ucs_passphrase>", "master_key": "<master_key>" }
Identify the
task_id
value is generated in the response to know the status of upload task.Sample successful response:
{ "task_id": "2ac55d6f-62ca-4562-9f96-d7c325455b4d" }
For more information about uploading UCS archives using BIG IP Next Central Manger APIs, see OpenAPI documentation.
Retrieve upload task status
Retrieve the upload task status by sending the GET request
system/tasks/<task_id>
endpoint.Replace the
task_id
from the response of the previous API request to check the progress and status of the upload operation.GET https://{{cm_mgmt_ip}}/api/v1/system/tasks/<task_id>
Click for sample response ▶
{ "_links": { "self": { "href": "/v1/tasks/2ac55d6f-62ca-4562-9f96-d7c325455b4d" } }, "created": "2024-06-13T12:44:13.422827Z", "id": "2ac55d6f-62ca-4562-9f96-d7c325455b4d", "inactive_time_in_min": 5, "percent_completed": 100, "resumable": false, "source": "MIGRATION", "status": "COMPLETED", "updated": "2024-06-13T12:44:29.42115Z" }
For more information about the upload task status using BIG-IP Next Central Manger APIs, see OpenAPI Documentation.
Migrate Application Services (API)¶
Retrieve applications list
Retrieve the list of applications found on UCS archive by sending the GET request to
migrations/<migration_id>/application-services?sort=id&page=1&limit=100
endpoint.Modify the
migration_id
from the previous steps response.GET https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>/application-services?sort=id&page=1&limit=100
Click for sample response ▶
{ "_embedded": { "application-services": [ { "_links": { "self": { "href": "/api/v1/migrations/4/application-services/41" } }, "id": 41, "name": "Common_vs_http2", "deployed_app_id": null }, { "_links": { "self": { "href": "/api/v1/migrations/4/application-services/42" } }, "id": 42, "name": "Common_vs_http1", "deployed_app_id": null } ] }, "_links": { "self": { "href": "/api/v1/migrations/4/application-services?limit=1000000&select=name,id,_links,deployed_app_id" } }, "count": 2, "total": 2 }
For more information about retrieving applications list using BIG-IP Next Central Manger APIs, see OpenAPI Documentation.
Import shared objects
Import shared objects (Access policies, Certificates, iRules, WAF policies) of selected applications to BIG-IP Next Central Manager by sending the POST request to
migrations/<migration_id>/application-services/import-shared-objects?async=true
endpoint.Modify the
migration_id
from the previous steps response.POST https://{{cm_mgmt_ip}}//api/migrations/<migration_id>/application-services/import-shared-objects?async=true
For the request payload, use the following example, modifying the values as required.
application_id
: Provide the selected application IDs for deployment as a list of integers.{ "applications": [ {{application_id}} ] }
Sample successful response:
{ "task_id": "5a2587a4-18ca-44a3-be13-9838ecb4107b", "path": "/api/task-manager/v1/tasks/5a2587a4-18ca-44a3-be13-9838ecb4107b" }
For more information about importing shared objects using BIG-IP Next Central Manger APIs, see OpenAPI Documentation.
Retrieve the shared objects import status
Retrieve the shared objects import status by sending the GET request to
system/tasks/<task_id>
endpoint.Replace the
task_id
from the response of the previous API request to check the status.GET https://{{cm_mgmt_ip}}/api/v1/system/tasks/{{task_id}}
Click for sample sucessful response: ▶
{ "_links": { "self": { "href": "/api/v1/system/tasks/5a2587a4-18ca-44a3-be13-9838ecb4107b" } }, "created": "2024-09-02T16:19:18.808438Z", "id": "5a2587a4-18ca-44a3-be13-9838ecb4107b", "inactive_time_in_min": 5, "percent_completed": 100, "resumable": false, "source": "IMPORT_SHARED_OBJECTS", "status": "COMPLETED", "updated": "2024-09-02T16:19:25.448657Z" }
For more information about retrieving the shared object import status using BIG-IP Next Central Manager APIs, see OpenAPI documentation.
Generate and deploy migration¶
Preview an application
Retrieve an AS3 declartion for importing on CM by sending the GET request to
migrations<migration_id>/application-services/<application_id>/preview
endpoint.GET https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>/application-services/<application_id>/preview
Click for sample successful response: ▶
{ "class": "ADC", "schemaVersion": "3.0.0", "id": "urn:uuid:45b3551b-f4ef-46d8-a5df-fd8216fc9bbd", "label": "Converted Declaration", "tenant5d32a0471d9cc": { "class": "Tenant", "Common_vs_http_irule": { "class": "Application", "template": "generic", "http_default_v15": { "class": "HTTP_Profile" }, "a_irule": { "iRule": { "base64": "d2hlbiBIVFRQX1JFUVVFU1QgewogICAgbG9nIGxvY2FsMC5pbmZvICJwb3J0OiBbVENQOjpjbGllbnRfcG9ydF0gLSAzcmQgaVJ1bGUiCn0=" }, "class": "iRule" }, "tcp_default_v15": { "class": "TCP_Profile" }, "Common_vs_http_irule": { "pool": "pool_http", "iRules": [ { "use": "/tenant5d32a0471d9cc/Common_vs_http_irule/a_irule" } ], "translateServerAddress": true, "class": "Service_HTTP", "profileHTTP": { "use": "/tenant5d32a0471d9cc/Common_vs_http_irule/http_default_v15" }, "profileTCP": { "use": "/tenant5d32a0471d9cc/Common_vs_http_irule/tcp_default_v15" }, "virtualAddresses": [ "xxx.xxx.xxx.xxx" ], "virtualPort": 80, "persistenceMethods": [], "snat": "auto" }, "pool_http": { "members": [ { "addressDiscovery": "static", "servicePort": 80, "serverAddresses": [ "xxx.xxx.xxx.xxx", "xxx.xxx.xxx.xxx", "xxx.xxx.xxx.xxx" ], "shareNodes": true } ], "class": "Pool" } } }, "remark": "Generated by JOURNEYS", "controls": { "class": "Controls", "userAgent": "JourneysCM/development-build" } }
For more information about previewing an application using BIG-IP Next Central Manager APIs, see OpenAPI documentation.
Import selected applications to CM
Import migrated applications to BIG-IP Next Central Manager by sending the POST request to
/migrations/<migration_id>/application-services/import?async=true
endpoint.POST https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>//application-services/import?async=true
For the request payload, use the following example, modifying the values as required.
{ "applications": [ <application_id> ] }
Click for sample successful response: ▶
{ "task_id": "509df8ac-5dd2-4994-8dbf-c9fdee55d49d", "path": "/api/task-manager/v1/tasks/509df8ac-5dd2-4994-8dbf-c9fdee55d49d" }
For more information about importing selected applications to CM using BIG-IP Next Central Manager APIs, see OpenAPI documentation.
Retrieve the application import status
Retrieve the application import status by sending the GET request to
/api/v1/system/tasks/{{task_id}}
endpoint.Replace the
task_id
from the response of the previous API request to check the status.GET https://{{cm_mgmt_ip}}/api/v1/system/tasks/{{task_id}}
Click for sample successful response ▶
{ "_links": { "self": { "href": "/api/v1/system/tasks/509df8ac-5dd2-4994-8dbf-c9fdee55d49d" } }, "created": "2024-09-02T16:45:53.805251Z", "id": "509df8ac-5dd2-4994-8dbf-c9fdee55d49d", "inactive_time_in_min": 5, "percent_completed": 100, "resumable": false, "source": "IMPORT_APPLICATIONS", "status": "COMPLETED", "updated": "2024-09-02T16:46:03.077051Z" }
For more information about retrieving the application import status using BIG-IP Next Central Manager APIs, see OpenAPI documentation.
Delete Migration¶
Delete a specific migration session by sending the DELETE request to /migrations/<migration_id>
endpoint.
DELETE https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>
Sample succesful response:
HTTP 204 No Content
For more information about deleting the migration using BIG-IP Next Central Manager APIs, see OpenAPI documentation.