5 Identify and Translate Resources in Your Source Environment
You can use the output generated by this tool to analyze the networking objects that you'll need to set up in your Oracle Cloud Infrastructure tenancy and to identify the virtual machine instances and block storage volumes that you want to migrate. You can select an output format that works best for your requirements and you can also filter the output using various commands and options provided by this tool.
You can generate reports in the following formats:
- JSON: The default format. If you want to use Oracle Cloud Infrastructure Classic VM and Block Storage Migration Tool to migrate your resources, you can generate a list of instances that can be used as input for that tool.
- Graph: You can use the graphical output to get a visual representation of your resources. You can also filter the graphical output to exclude or include specified object types or to focus on specific objects.
- Spreadsheet: Use this format to view a list of different resource types in separate worksheets. The spreadsheet also includes a summary of your environment and a count of each resource type.
- Terraform: Use this format if you want to use Terraform to set up your resources on Oracle Cloud Infrastructure. Note that you must review the generated Terraform module carefully before using it to create resources on Oracle Cloud Infrastructure. You'll also need to provide input in a variables file to enable access to the Oracle Cloud Infrastructure tenancy.
Note:
The reports generated by the tool can contain sensitive data about your cloud environment, such as personally identifiable information, system identifiers, security configurations, system initialization scripts and default passwords. By default, the reports generated by this tool are stored in the local directory where the tool is run. Make sure that access to these files is restricted and that you delete the files as soon as possible after your migration is complete.
After you've generated reports for each of your resources, evaluate the options to create the network in the target environment before you migrate your virtual machine instances and block storage volumes.
After you've set up the network in your target environment, you can use the output provided by Oracle Cloud Infrastructure Classic Discovery and Translation Tool as input to Oracle Cloud Infrastructure Classic VM and Block Storage Migration Tool to specify the resources that you want to migrate. This simplifies the process of moving your compute and block storage resources to your Oracle Cloud Infrastructure tenancy.
You can also use the remote storage migration commands and the database migration commands to migrate those resources to Oracle Cloud Infrastructure.
Considerations for Using Oracle Cloud Infrastructure Classic Discovery and Translation Tool
Before you run Oracle Cloud Infrastructure Classic Discovery and Translation Tool, consider the following suggestions.
- The standalone distribution of this tool doesn't modify any resources in the source environment. It is recommended that you run this tool as a user with the minimum required read-only access. The recommended user privileges are:
- Compute Classic:
Compute.Compute_Monitor
- Load Balancer Classic:
LBAAS_READONLYGROUP
- Storage Classic:
Storage_ReadOnlyGroup
- Compute Classic:
- If you run this tool in an instance created with the Oracle Cloud Infrastructure Classic Migration Tools image, then you can use the
opcmigrate migrate
set of commands to migrate VMs, block storage, storage snapshots, and database instances. Some of those commands require read-write access to your Oracle Cloud Infrastructure Compute Classic account as well as your Oracle Cloud Infrastructure tenancy. Ensure that sufficient privileges are in place in both environments. - This tool generates Terraform configuration files that can be used to create resources in a single availability domain on Oracle Cloud Infrastructure.
Prepare to Use Oracle Cloud Infrastructure Classic Discovery and Translation Tool
If you want to use Oracle Cloud Infrastructure Classic VM and Block Storage Migration Tool along with Oracle Cloud Infrastructure Classic Discovery and Translation Tool, create a migration controller instance in your Oracle Cloud Infrastructure Compute Classic account using the Oracle Cloud Infrastructure Classic Migration Tools image.
For information about creating a migration controller instance, see Complete the Prerequisites and Launch the Migration Controller Instance (Control-S) in the Source Environment. If you've already created this instance, you can use the same instance for this procedure. You don't need to create it again.
Oracle Cloud Infrastructure Classic Discovery and Translation Tool is preinstalled on this instance, so you can start using this tool right away on all instances created with this image.
If you want to run Oracle Cloud Infrastructure Classic Discovery and Translation Tool on any other system, follow the procedure to install the tool on any system running Oracle Linux 7.x, Windows, or MacOS. Note, however, that not all features of this tool are available when you download and install the tool on other systems.
Before you run the tool, ensure that you've set up your profile and provided the credentials required to allow the tool to connect to your Oracle Cloud Infrastructure Compute Classic account. If you're using Oracle Cloud Infrastructure Classic VM and Block Storage Migration Tool on an instance created using the Oracle Cloud Infrastructure Classic Migration Tools image, skip the installation procedures and set up your profile now. See Set Up Your Profile.
Some features of the tool might require credentials to access yourOracle Cloud Infrastructure tenancy as well. Follow the steps in specific sections of this document to provide the required information for each feature.
Install Oracle Cloud Infrastructure Classic Discovery and Translation Tool
To install Oracle Cloud Infrastructure Classic Discovery and Translation Tool you'll need Python 3.6.6 or higher. To view graphs generated by the tool and to generate PDFs of graphs, you'll need Graphviz 2.30.1 or higher.
The steps to install the tool vary slightly depending on the OS of the system that you want to install it on. Currently, you can install this tool on the following operating systems:
- Oracle Linux 7.x
- MacOS
- Microsoft Windows
Install Oracle Cloud Infrastructure Classic Discovery and Translation Tool on Oracle Linux
On an Oracle Linux system, use pip
to install Oracle Cloud Infrastructure Classic Discovery and Translation Tool. You can use yum
to install pip
along with the required Python and Graphviz packages.
Set Up Your Profile
Oracle Cloud Infrastructure Classic Discovery and Translation Tool connects to your source environment using connection information that you provide in a profile file.
Upgrade Oracle Cloud Infrastructure Classic Discovery and Translation Tool
If you've already installed an earlier version of Oracle Cloud Infrastructure Classic Discovery and Translation Tool on your system, then you can use pip
to uninstall the old version and install the latest version.
Note:
You can upgrade only a standalone installation of Oracle Cloud Infrastructure Classic Discovery and Translation Tool. If you are using Oracle Cloud Infrastructure Classic Discovery and Translation Tool on an instance created with the Oracle Cloud Infrastructure Classic Migration Tools image, then to upgrade to the latest version of the installed tools, use the latest image to create an instance.On a local system with a standalone installation of Oracle Cloud Infrastructure Classic Discovery and Translation Tool, to upgrade, do the following:
Run Oracle Cloud Infrastructure Classic Discovery and Translation Tool to Generate Reports
You can use various commands and options to specify the output format of the report and to filter the output according to your requirements.
Learn About Commonly Used Commands and Options
Here are some of the commonly used commands and options that allow you to customize your reports as required. To view a complete list of commands and for detailed information about the options and permitted values for each command, run the tool with the --help
option.
To view help on all commands and options, use:
opcmigrate --full-help
- To generate JSON formatted resource files and reports, use:
opcmigrate discover:
Generates a report of all available network, instance, load balancer, PaaS, and object storage resources in the site, in JSON format. The data in this output processed by otheropcmigrate
commands.opcmigrate network:
Generates a report of the networking objects. The report contains the security lists in the shared network and a list of all the IP networks along with the associated access control lists, security rules, and instances in each IP network.opcmigrate instances-export:
Generates a file in JSON or YAML format that lists all the instances along with information about the operating system of each instance. This file can be passed as input to Oracle Cloud Infrastructure Classic VM and Block Storage Migration Tool.opcmigrate anonymize:
Removes sensitive data from a specified file.opcmigrate summary:
Displays on the terminal a summary of the resources in the site.
- To generate a spreadsheet, use
opcmigrate report
. This command generates a spreadsheet with separate worksheets for each resource type, listing all the resources in the site. - To generate a graph of relationships between resources, use
opcmigrate graph
. This command generates a Graphviz graph and a PDF of the relationships between the discovered resources. You can specify a number of options to customize the graphs generated by this command. - To focus on specified resources or resource types, include and exclude resources, or filter resources, use
opcmigrate plan create
. This command generates a plan for the specified resources. In addition to allowing you to filter resources in the output, this command allows you to set certain resource-level attributes for individual objects. For example, for any given object, you can specify if you want that object to be migrated or not. You can then provide the output of this command as input to theopcmigrate generate
command to generate a Terraform configuration for the specified resources. - To generate a Terraform configuration file, use
opcmigrate generate
. This command generates a Terraform configuration file that can be used to create resources on Oracle Cloud Infrastructure. - To migrate boot and block volumes, instances, remote snapshots, scheduled backups, and single instance deployments of Oracle Database Classic
Cloud Service using RMAN, use the
opcmigrate migrate
set of commands. These commands aren't explained in detail in this section. For information on using this tool to migrate these resources, see:
Generate a Summary and JSON Output
Use the following commands and options to generate a comprehensive JSON formatted resource cache of your resources or to view a brief summary of your resources.
- To generate a JSON formatted file that contains information about all the networking objects, instances, storage volumes, and other resources in the site:
opcmigrate discover
This command writes the output to a file with the name
resources-*.json
where * indicates the profile name. This file is stored in the same directory where the command is run. You can use this file as input to other commands, to filter and sort the data. - To specify a profile other than
default
:
The profile name is included in the file name of reports generated by theopcmigrate --profile <profile> discover
opcmigrate discover
command. - By default, a summary view of object storage containers is listed in the report. To fetch the full file names:
opcmigrate discover --with-storage-objects
- To view a list summarizing the resource types and the number of resources in your source environment:
This command takes as input a report generated by theopcmigrate summary
opcmigrate discover
command. You must run that command first, before runningopcmigrate summary
. With this command, output is displayed on the terminal and no output file is generated. Use standard commands to write the output to a file, if required. - To generate a file with the network details:
This command takes as input a report generated by theopcmigrate network
opcmigrate discover
command. You must run that command first, before runningopcmigrate network
.This report shows the security rules and instances in each security list in the shared network. It also lists the access control lists, security rules, and instances in each IP network.
You can filter the output by resource type, to view only the shared network or only IP networks. You can also sort the output to display data by secrule in the shared network, or by vNICset in IP networks, and so on. For more information about command options, run the command with the
--help
option. - The reports generated by the
opcmigrate discover
command contain sensitive data about your source environment. If you want to remove sensitive data from these files, including user ids, email addresses, instance initialization scripts, and unique service ids, use theanonymize
command.opcmigrate anonymize --file resources-default.json --output resources-anonymized.json
Generate a Spreadsheet
To generate an Excel spreadsheet with separate worksheets for each resource type, use the following command.
opcmigrate report
Generate Graphical Reports
To generate a graph of the relationships between resources, use the following command:
Create a Migration Plan
You can use the resources file generated by opcmigrate discover
to create a migration plan file. A migration plan file allows you to apply various filters to include or exclude objects. You can also set certain object-level migration attributes in this file.
A migration plan file is created by using a resources file as input. You must have already run opcmigrate discover
to generate a resources file, before you create a migration plan.
To create a migration plan, run opcmigrate plan create
. You can specify a number of options while creating a migration plan, to include or exclude specific resources or resource types. Use the --help
option for information about the available options.
You can specify a resources file by using the --file
option. If no resources file is specified, the command looks for the resources-default.json
file in the current directory.
By default, the plan file is named plan-default.json.
If you run the opcmigrate plan create
command multiple times, the output file is overwritten each time by default. Note, however, that in earlier versions of the tool, the output of this command wasn't written to a file but was displayed on the screen by default. To save the migration plan to a file with a different name, use the --output
option.
opcmigrate plan create --file resources-default.json --output migration-plan.json
If you want to print the output to standard output (stdout), use the option -o -
.
opcmigrate plan create --file resources-default.json -o -
For each object listed in the migration plan file, you can specify if you want to migrate that object by modifying the value of the opc_migrate_include
attribute. For customer-created resources, this attribute is set to true by default. For Oracle-defined resources, this attribute is generally set to false by default.
For some objects, such as databases and storage volumes, you can also specify other object-level migration attributes.
If you want to use this plan as input to generate a list of instances, you can scan through the list of instances and make the required modifications, if any, to include or exclude instances from being migrated.
You can use the --include, --exclude,
and --no-filter
options to alter the scope of the generated plan. For example, to generate a plan with specified resource types, use:
opcmigrate plan create --include instance ip_network vnic interface security_rule vnic_set acl security_protocol ip_address_prefix_set --output plan.json
Generate a List of Instances to Migrate
You can use Oracle Cloud Infrastructure Classic Discovery and Translation Tool to generate a list of instances and storage volumes that you want to migrate. You can then use this list as input to Oracle Cloud Infrastructure Classic VM and Block Storage Migration Tool.
Use the opcmigrate instances-export
command to generate a list of instances in your Oracle Cloud
Infrastructure Compute Classic account. This command requires as input a plan generated by the opcmigrate plan create
command. You can also specify a resources file generated by the opcmigrate discover
command. If no resources file is specified, the command looks for the resources-default.json
file in the current directory.
To generate a list of instances, do the following:
- Run
opcmigrate discover
to generate a resource file. By default the resource file is namedresources-default.json
and it is saved in the current directory.opcmigrate discover
- Run
opcmigrate plan create
to create a migration plan. You can specify a number of options while creating a migration plan, to include or exclude specific resources or resource types. Use the--help
option for information about the available options.opcmigrate plan create --file resources-default.json --output migration-plan.json
- Modify the migration plan file, if required. For each object listed in the migration plan file, you can specify whether you want to migrate that object or not. Scan through the list of instances and make the required modifications, if any, to include or exclude instances from being migrated.
- Run
opcmigrate instances-export
to generate the list of instances to be migrated. By default, this command generates the output in JSON format, which can be used to create job files for migration. Use the--format
option if you want to generate the output in YAML.By default, the output of this command is displayed on the terminal. Use standard commands to write the output to a file, if required.
opcmigrate instances-export --file resources-default.json --plan migration-plan.json > instances.yaml
Generate Terraform Configuration Files
If you want to use Terraform to set up resources in your Oracle Cloud
Infrastructure tenancy, you can use opcmigrate generate
to generate Terraform configuration files.
opcmigrate generate
command requires a migration plan file and a resources file as input.
You can specify a plan file by using the --plan
option. If no plan file is specified, the command uses the plan-default.json
file in the current directory. Note that in earlier versions of the tool, --plan
was a required option and the opcmigrate generate
command didn't use the plan-default.json
file by default.
You can optionally also specify a resources file by using the --file
option. If no resources file is specified, the command looks for the resources-default.json
file in the current directory.
By default, the Terraform configuration file is named generate-default.tf.
If you run the opcmigrate generate
command multiple times, the output file is overwritten each time by default. Note, however, that in earlier versions of the tool, the output of this command wasn't written to a file but was displayed on the screen by default. To save the configuration to a file with a different name, use the --output
option.
To generate a Terraform configuration file, do the following:
Troubleshooting
Here are a few tips for dealing with errors that might occur while installing and using Oracle Cloud Infrastructure Classic Discovery and Translation Tool.
- Error authenticating with your Oracle Cloud
Infrastructure Compute Classic, Oracle Cloud
Infrastructure Object Storage Classic, Oracle Cloud
Infrastructure Load Balancing Classic, or PaaS account.
When you run the
opcmigrate discover
command, the tool attempts to connect to your accounts using the user names supplied in the profile file. If authentication fails, ensure that the correct user name is supplied for each account. Also check that the correct REST API endpoints are provided. The endpoint should be just the domain name without thehttps://
prefix. The endpoint URLs can be found on the Service Details page for each service. - Warnings and errors while running the
opcmigrate graph
command.When you use the opcmigrate graph command, you might see the following errors:
- Warning: Overlap value "prism" unsupported - ignored- Error: remove_overlap: Graphviz not built with triangulation library
These errors indicate that the default Graphviz distribution is missing some required dependencies. You might need to reinstall Graphviz from an alternative distribution, or build from source with the
gts
andpango
options enabled. For example, on an Oracle Linux system, to build GTS dependency from source run the following commands:cd/usr/local/src wget http://gts.sourceforge.net/tarballs/gts-snapshot-121130.tar.gz tar zxvf gts-snapshot-121130.tar.gz cd gts-snapshot-121130 sudo yum install gcc glib-devel ./configure make sudo make install
To build Graphviz from source, run the following commands:
cd /usr/local/src wget https://graphviz.gitlab.io/pub/graphviz/stable/SOURCES/graphviz.tar.gz tar xzvf graphviz.tar.gz cd graphviz-2.40.1 sudo yum install gcc-c++ libstdc++-devel gd-devel pango-devel ./configure make sudo make install
- The
opcmigrate graph
command takes a long time to run or doesn't completeLarge graphs may take a long time to compete using the default graph layout engine. To reduce the time taken to create graphs, you can:- Use the
--engine
option to specify an alternative graph layout engine. Thesfdp
engine is recommended for large graphs. - Reduce the size of the graph by limiting the types of nodes displayed. Use the
--focus, --exclude,
or--include
options.
- Use the
- The
opcmigrate instances-export
command doesn't return theos
andosSku
values.When you run the
opcmigrate instances-export
command, you might see the following errors:PandaExportGenerator: WARNING: machine image details not found for instance://Compute-a000000/user@example.com
This error indicates that the machine image used to launch an instance is no longer present in the environment. The machine image and image list have been deleted after the instance was launched. You can ignore this warning. However, if you want to provide the output of the
opcmigrate instances-export
command as input to Oracle Cloud Infrastructure Classic VM and Block Storage Migration Tool, it's recommended that you specify theos
andosSku
value for all instances, if possible. - The Terraform output generated by the
opcmigrate generate
command doesn't include any security rules.By default, the
opcmigrate generate
command doesn't include output that maps the Oracle Cloud Infrastructure Compute Classic security rules to Oracle Cloud Infrastructure security rules. To generate security rules, use the--with-security-rule-union
option.Caution:
When you use the--with-security-rule-union
option, review the generated Terraform configuration carefully before applying it. Due to differences in the way security rules are implemented in Oracle Cloud Infrastructure Compute Classic and Oracle Cloud Infrastructure, the security rules implemented by the Terraform configuration in the target environment might expose instances to more traffic than intended.