Scripts management

The Cloud Migration Factory on AWS solution allows users to fully manage the library of automation scripts or packages within the user interface. You can upload new custom scripts as well as new versions of the script using the scripts management interface. When multiple versions are available, an administrator can switch between these versions allowing the ability to test updates before making them default. The script management interface also allows administrators to download script packages to update or review the content.

A supported script package is a compressed zip archive containing the following mandatory files in the root:

• Package-Structure.yml – Used to define the script’s arguments and other metadata, such as description and default name. Refer to Composing a new script package for more details.

• [custom python script].py – This is the initial script that will be run when a job is submitted. This script can call other scripts and modules and if so these should be included in the archive. The name of this script must match the value specified in the MasterFileName key in the Package-Structure.yml.

Upload new script package

Note

A script package must conform to the supported format. Refer to Composing a new script package for more details.

1. Choose Add on the Automation Scripts table.

2. Select the package archive file you want to upload.

3. Enter a unique name for the script. Users will reference the script by this name for initiating jobs.

Download script packages

You can download script packages from the console to activate updates and content verification.

1. Select Automation, then Scripts.

2. Select the script you want to download from the table, then select Actions and choose Download default version or Download latest version.

You can download specific versions of a script. To do so, select the script, then Actions and choose Change default version. From the Script Default Version list, choose Download selected version.

Add new version of a script package

Updates to AWS Cloud Migration Factory script packages can be uploaded in the Automation > Scripts section by following these steps:

1. Select Automation, then Scripts.

2. Select the existing script to add a new version, then select Actions and choose Add new version.

3. Select the updated package archive file you want to upload, and choose Next. The new script version will keep the existing name by default. Enter a unique script name. Any name change will only be applied to this version of the script.

4. You can make the new version of the script the default version by selecting Make default version.

5. Choose Upload.

Deleting script packages and versions

You cannot delete scripts or versions of a script for auditing purposes. This allows reviewing the exact script that was run against a system at a point in time. Every script version has a unique signature and ID when uploaded which is recorded against the job history that the script and version was used in.

Composing a new script package

Cloud Migration Factory on AWS script packages support Python as the primary scripting language. You can initiate other shell scripting languages as required from within a Python main program or wrapper. To create a new script package quickly, we recommend downloading a copy of one of the prepackaged scripts and updating it to perform the required task. You must first create a master Python script that will perform the core functionality of the script. Then, create a Package-Structure.yml file to define the arguments and other metadata the script requires. Refer to Package-Structure.yml options for more details.

Main Python script

This is the initial main script that runs when a job is initiated. Once the script completes running, the task is finished and the final return code determines the status of the job. All output from this script is captured when run remotely and passed into the output audit log of the job for reference. This log is also stored in Amazon CloudWatch.

Accessing Cloud Migration Factory on AWS data and APIs from a script

To provide access to the Cloud Migration Factory on AWS APIs and data, you can use the included python helper module. The module provides the following common functions:

Factorylogin

Returns an access token that can be used to call Cloud Migration Factory on AWS APIs. This function will attempt login to CMF using a number of attempts for credentials:

1. By attempting to access the default secret containing the service account userid and password if it exists and access is allowed. This secret name MFServiceAccount-[userpool id] will be checked.

2. If Step 1 is unsuccessful, and the user is running the script from the command line, then the user will be prompted to supply an AWS Cloud Migration factory userid and password. If run from a remote automation job, the job will fail.

getServerCredentials

Returns the login credentials for a server stored in AWS Cloud Migration Factory in either Credentials Manager, or through user input. This function will check a number of different sources to determine the credentials for a specific server, the order of the sources is:

1. If local_username and local_password is set and valid then these will be returned.

2. If secret_overide is set then this will be used to retrieve the secret specified from AWS Secret Manager, otherwise, checks if the server record contains the key secret_name and this is not empty then this secret name will be used.

3. If there is a failure locating or accessing the secrets specified then the function will fall back to prompting the user for the credentials, but only if the no_user_prompts is set to False, otherwise it will return a failure.

Parameters

local_username – If passed, then will be returned.

local_password – If passed, then will be returned.

server – Server name, as stored in the server_name attribute in AWS Cloud Migration Factory.

Secret_overide – Is passed this will set the secret name to retrieve from Secrets Manager for this server.

No_user_prompts – Tells the function not to prompt a user for a userid and password if not stored, this should be True for any remote automation script.

getCredentials

Gets the credentials stored using AWS Cloud Migration Factory Credentials Manager from Secrets Manager.

Parameters

secret_name – name of the secret to retrieve.

get_factory_servers

Returns an array of servers from the AWS Cloud Migration Factory datastore based on the waveid provided.

Parameters

Waveid – Wave record ID of the servers that will be returned.

Token – Authentication token obtained from the FactoryLogin Lambda function.

UserHOST – AWS Cloud Migration Factory User API Endpoint URL.

osSplit – If set to true, then two lists will be returned one for Linux and one windows servers, if False, then a single combined list will be returned.

Final message summary

It is recommended to provide a summary message of the script’s outcome as the final output to the screen or sysout. This will be shown on the console in the Last Message property, which provides a quick status of the script outcome without the user having to read the full output log.

Return code

The main python script should return a non-zero return code on exit if the function of the script was not completely successful. On receiving a non-zero return code the job status will be shown as Failed in the jobs log indicating to the user that they should review the output log for details of the failure.

YAML Package-Structure.yml options

Example YAML file

Name: "0-Check MGN Prerequisites"
Description: "This script will verify the source servers meet the basic requirements for AWS MGN agent installation."
MasterFileName: "0-Prerequisites-checks.py"
UpdateUrl: ""
Arguments:
-
name: "ReplicationServerIP"
description: "Replication Server IP."
long_desc: "IP Address of an AWS MGN Replication EC2 Instance."
type: "standard"
required: true
-
name: "SecretWindows"
long_desc: "Windows Secret to use for credentials."
description: "Windows Secret"
type: "relationship"
rel_display_attribute: "Name"
rel_entity: "secret"
rel_key: "Name"
-
name: "SecretLinux"
long_desc: "Linux Secret to use for credentials."
description: "Linux Secret"
type: "relationship"
rel_display_attribute: "Name"
rel_entity: "secret"
rel_key: "Name"
-
name: "Waveid"
description: "Wave Name"
type: "relationship"
rel_display_attribute: "wave_name"
rel_entity: "wave"
rel_key: "wave_id"
validation_regex: "^(?!\\s*$).+"
validation_regex_msg: "Wave must be provided."
required: true
SchemaExtensions:
-
schema: "server"
name: "server_pre_reqs_output"
description: "Pre-Req Output"
type: "string"

YAML key descriptions

Required

Name – Default name that the script will use on import.

Description – Description of the usage of the script.

MasterFileName – This is the starting point for the script to run, it has to be a python file name that is included within the script package archive.

Arguments – A list of arguments that the MasterFileName Python script accepts. Each argument needs specified is in the AWS Cloud Migration Factory Attribute definition format. Required properties for each argument are Name and Type, all other properties are optional.

Optional

UpdateUrl – Provide a URL where the script package’s source is available for providing updates. Currently this is for reference only.

SchemaExtensions – A list of attributes that the Python script requires to be in the schema to store output or retrieve additional data. Each attribute must be specified in the AWS CMF Attribute definition format. Required properties for each attribute are Schema, Name, Description and Type. All other properties are optional. Any new attributes will be automatically added to the schema when the script is initially loaded, and changes to SchemaExtensions will not be processed for new versions of the script. If this is required for a new script to be added, manual updates to the schema must be made.