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:

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:

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.

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

  6. For Source BIG-IP System add the **UCS archive ** and customize encryption and merge preferences for the BIG-IP virtual servers:

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

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

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

  2. You can verify which objects in the application services will be modified, removed, or present issues with deployment during the application conversion:

    1. Click on the application service name to open the configuration analyzer.

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

    image

    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.

    image

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

    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. Select More Actions and click Rename.

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

  5. To download the converted AS3 declaration(s):

    1. Select the check box(es) next to the application service.

    2. Select More Actions and click Download AS3.
      The AS3 declaration(s) are downloaded to your system based on your browser settings.

  6. To create an application service:

    1. Select More Actions and click Create.

    2. Enter a new name for the new application service and click Ok.

  7. To remove an application service:

    1. Select the check box next to the application service.

    2. Select More Actions and click Remove.

    3. Click Confirm to remove the application service.

    Note: You can only remove an empty application service.

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

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

  10. You can import shared objects in two ways:

    1. Select the check box next to the application service, click Import Shared Objects from the top right of the panel and click Yes, import.

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

  11. Click + Add Filter to filter the application services based on IP address, security policies, number of shared objects, migration status and so on.

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

  1. To deploy the migrated AS3 application services, select the application service and review the AS3 declaration.

  2. If you make any changes to AS3 declaration, click Save.

  3. Click Review & Deploy.

  4. Click Start Adding to select the BIG-IP Next instance for deploying the application services.

  5. Click Validate to check whether the application service is valid or not.

  6. Click Configure to review Access deployment configuration.

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

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

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

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

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

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

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

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

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