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.

You can migrate application and deploy services to BIG-IP Next in two ways:

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. To maintain proper policy flows or rules, objects that are not yet supported on BIG-IP Next are marked as _unsupported. These unsupported objects are created in an empty state. During pre-deployment, 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 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:

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

  1. Log in to BIG-IP Next Central Manager as admin, click the Workspace icon next to the F5 icon, and click Applications.

  2. At the top of the screen, click Add Application.

  3. 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.

  4. For General Properties, type a Session Name (without whitespace) and an optional Description.

  5. Click Save & Continue.

  6. 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.

  1. 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) image and/or unsupported security objects relating to certificate (blue) image, or contains virtual servers that are not supported by BIG-IP Next (red) image.

  2. 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.

image

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.

image

  1. Click Preview AS3 </> to view a read-only declaration after it is migrated to BIG-IP Next.

  2. Click Close to close the service panels and return to the BIG-IP Application Services panel.

  3. 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: image

  4. 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.

  5. Select the check box of the services you would like to migrate. image

  6. Click Add. The services are added to the Application Migration list.

  7. 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, 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 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 or Access 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.

  1. 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.

      Note: You must import all shared objects before you can proceed to deployment or save as draft.

  2. (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: image

    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

  3. 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.

    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.

  4. 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.

  5. 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: image

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 using Postman collection

  1. Download the F5 Postman collection.

  2. 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)

  3. Select the folder Chained step-by-step migration of one app.

  4. Execute the requests Login to CM through Retrieve status of deployment operation.

Migrate application and deploy 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:

  1. Create a new session for application service migration

  2. Migrate Application Services (API)

  3. Generate and deploy migration

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

  1. 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 file.

    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.

  2. Upload UCS file

    Add the configuration (UCS file) from the source BIG-IP system to the new session by sending the POST request v1/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 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.

    Note: For large UCS files, 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 files using BIG IP Next Central Manger APIs, see OpenAPI documentation.

  3. 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)

  1. Retrieve applications list

    Retrieve the list of applications found on UCS file by sending the GET request to migrations/<migration_id>/applications endpoint.

    Modify the migration_id from previous steps response.

    GET https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>/applications
    Click for sample response ▶ 
    {
"_embedded": {
    "applications": [
        {
            "_links": {
                "self": {
                    "href": "/api/v1/migrations/2/applications/100"
                }
            },
            "id": 100,
            "name": "Common_virtual_irule_http_explicit",
            "status": "yellow",
            "description": null,
            "last_modified": "2024-06-13T12:44:26.770383Z",
            "as3_preview": "/api/v1/migrations/2/applications/100/preview",
            "virtual_servers": [
                {
                    "_links": {
                        "self": {
                            "href": "/api/v1/migrations/2/virtuals/100"
                        }
                    },
                    "id": 100,
                    "name": "Common_virtual_irule_http_explicit",
                    "description": "",
                    "ip_addresses": [
                        "10.2.3.5/32"
                    ],
                    "ports": [
                        "443"
                    ],
                    "pool": "pool_objects",
                    "status": "yellow",
                    "last_modified": "2024-06-13T12:44:26.779093Z",
                    "unsupported_properties": {
                        "ltm default-node-monitor": "This object is not supported by BIG-IP Next",
                        "ltm pool /tenantf7837dc217242/Common_virtual_irule_http_explicit/pool_objects": {
                            "min-active-members": "Deleted path from declaration: /tenantf7837dc217242/Common_virtual_irule_http_explicit/pool_objects/minimumMembersActive (reason - JSON Next Schema validator)"
                        }
                    }
                }
            ],
            "staged": false,
            "referenced_objects_installed": false,
            "waf_policies": [],
            "certificates": [
                {
                    "name": null,
                    "old_name": "/Common/test_cert_validate_ocsp",
                    "status": "not installed"
                }
            ],
            "irules": [
                {
                    "name": null,
                    "old_name": "/Common/irule_test",
                    "status": "not installed",
                    "version": null
                }
            ],
            "access_policies": [],
            "template_name": null,
            "template_parameters": {},
            "deploy_location": null,
            "readiness": true
        }
    ]
},
"_links": {
    "self": {
        "href": "/api/v1/migrations/2/applications"
    }
},
"count": 1,
"total": 1
}

    For more information about retrieving the applications list using BIG-IP Next Central Manager APIs, see OpenAPI documentation.

  2. Set staged applications list

    Set the applications list which are staged for a specific migration session by sending the PUT request to /migrations/{migration_id}/applications-stage endpoint.

    PUT https://{{cm_mgmt_ip}}//api/v1/migrations/{migration_id}/applications-stage

    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}}
]
}
    Click for sample response ▶ 
    {
"_embedded": {
    "applications": [
        {
            "_links": {
                "self": {
                    "href": "/api/v1/migrations/2/applications/100"
                }
            },
            "id": 100,
            "name": "Common_virtual_irule_http_explicit",
            "status": "yellow",
            "description": null,
            "last_modified": "2024-06-13T12:44:26.770383Z",
            "as3_preview": "/api/v1/migrations/2/applications/100/preview",
            "virtual_servers": [
                {
                    "_links": {
                        "self": {
                            "href": "/api/v1/migrations/2/virtuals/100"
                        }
                    },
                    "id": 100,
                    "name": "Common_virtual_irule_http_explicit",
                    "description": "",
                    "ip_addresses": [
                        "10.2.3.5/32"
                    ],
                    "ports": [
                        "443"
                    ],
                    "pool": "pool_objects",
                    "status": "yellow",
                    "last_modified": "2024-06-13T12:44:26.779093Z",
                    "unsupported_properties": {
                        "ltm default-node-monitor": "This object is not supported by BIG-IP Next",
                        "ltm pool /tenantf7837dc217242/Common_virtual_irule_http_explicit/pool_objects": {
                            "min-active-members": "Deleted path from declaration: /tenantf7837dc217242/Common_virtual_irule_http_explicit/pool_objects/minimumMembersActive (reason - JSON Next Schema validator)"
                        }
                    }
                }
            ],
            "staged": true,
            "referenced_objects_installed": false,
            "waf_policies": [],
            "certificates": [
                {
                    "name": null,
                    "old_name": "/Common/test_cert_validate_ocsp",
                    "status": "not installed"
                }
            ],
            "irules": [
                {
                    "name": null,
                    "old_name": "/Common/irule_test",
                    "status": "not installed",
                    "version": null
                }
            ],
            "access_policies": [],
            "template_name": null,
            "template_parameters": {},
            "deploy_location": null,
            "readiness": true
        }
    ]
},
"_links": {
    "self": {
        "href": "/api/v1/migrations/2/applications"
    }
},
"count": 1,
"total": 1
}
    .

    For more information about setting the staged application list using BIG-IP Next Central Manager APIs, see OpenAPI documentation.

  3. Install application level referenced objects onto CM

    Install the application level reference objects (iRules, WAF policies, access policies, and certificates) onto the CM by sending the POST request to /migrations/<migration_id>/applications-install-dependencies endpoint.

    POST https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>/applications-install-dependencies

    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}}
]
}
    Click for sample response (shortened) ▶ 
    "staged": true,
    "referenced_objects_installed": true,
    "waf_policies": [],
    "certificates": [
        {
            "name": "migrated_test_cert_validate_ocsp",
            "old_name": "/Common/test_cert_validate_ocsp",
            "status": "success"
        }
    ],
    "irules": [
        {
            "name": "migrated_irule_test",
            "old_name": "/Common/irule_test",
            "status": "success",
            "version": 1
        }

    For more information about this request, see OpenAPI documentation.

Generate and deploy migration

  1. Set the Deploy location

    Set the deployment location for a specified application on BIG-IP Next by sending the PATCH request to migrations/<migration_id>/applications/<application_id> endpoint.

    PATCH https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>/applications/<application_id>

    For the request payload, use the following example, modifying the values as required.
    bigip_next_mgmt_ip: Add the desired BIG IP Next IP address where you want to deploy the application.

    {
"deploy_location": "<bigip_next_mgmt_ip>"
}
    Click for sample response ▶ 
    "staged": true,
    "referenced_objects_installed": true,
    "waf_policies": [],
    "certificates": [
        {
            "name": "migrated_test_cert_validate_ocsp",
            "old_name": "/Common/test_cert_validate_ocsp",
            "status": "success"
        }
    ],
    "irules": [
        {
            "name": "migrated_irule_test",
            "old_name": "/Common/irule_test",
            "status": "success",
            "version": 1
        }
            "access_policies": [],
            "template_name": null,
            "template_parameters": {},
            "deploy_location": "192.168.10.10",
            "readiness": true

    For more information about setting the deploy location, see OpenAPI documentation.

  2. Deploy Configuration to given system

    Deploy the configuration of specific application to the BIG-IP Next by sending the POST request to /migrations/<migration_id>/deployments endpoint. This configuration is applicable to specific instance.

    POST https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>/deployments

    For the request payload, use the following example, modifying the values as required.

    {
 "applications": {"{{application_id}}":"API"}
}
    Click for sample response ▶ 
    {
"_links": {
    "self": {
        "href": "/api/v1/migrations/2/deployments/1"
    }
},
"id": 1,
"reason": null,
"deployment_type": "API",
"application": "Common_virtual_irule_http_explicit",
"destination": "192.168.10.10",
"status": "Waiting",
"completed": null,
"run_time": null
}

    For more information about deploying configuration to given system using BIG-IP Next Central Manager APIs, see OpenAPI documentation.

  3. Retrieve status of deployment operation

    Retrieve the status of a specific deployment operation for a given migration session by sending the GET request to /migrations/<migration_id>/deployments/<deployment_id> endpoint.

    GET https://{{cm_mgmt_ip}}/api/v1/migrations/<migration_id>/deployments/<deployment_id>
    Click for sample response (shortened) ▶ 
    {
"_links": {
    "self": {
        "href": "/api/v1/migrations/2/deployments/1"
    }
},
"id": 1,
"deployment_type": "API",
"destination": "192.168.10.10",
"status": "Process completed",
"results": [
    {
        "time": "2024-06-13T16:45:11.541801Z",
        "message": "Migration process started.",
        "level": "INFO"
    },
    {
        "time": "2024-06-13T16:45:16.624303Z",
        "message": "Application: Common_virtual_irule_http_explicit saved as draft to BIG-IP Next Central Manager.",
        "level": "INFO"
    },
    {
        "time": "2024-06-13T16:45:22.223348Z",
        "message": "Deployment to 192.168.10.10 completed.",
        "level": "INFO"
    },
    {
        "time": "2024-06-13T16:45:22.236369Z",
        "message": "Migration process completed.",
        "level": "INFO"
    }
],

    For more information about retrieving the status of the deployment operation 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 succesfull response:

HTTP 204 No Content

For more information about deleting the migration using BIG-IP Next Central Manager APIs, see OpenAPI documentation.