Cloud Admin Tool CLI Quick Start

The Cloud Admin Tool (CAT) replaces and automates the existing deploy scripts used to deploy the server image on the application stack. With CAT CLI, you can:

• Configure a newly built Roku client to connect to a given application test stack
• Deploy a new server package to an application test stack
• Query successful deployment

Install the CAT CLI Package

Before You Start

You need to have Python version 3.6 or later and pip3 installed on your machine. The CLI is supported on any development platform that supports Python 3.6 or later. You can use Python virtual environments or virtual environment managers, such as Conda, at your discretion. To install Python on Mac, You.i TV recommends using a package manager, such as Homebrew.

To verify if pip3 is installed on your machine, do: pip3 --version. If successful, you’ll see the pip3 version with the path it’s installed to. If you don’t have pip3 installed, follow these instructions to install it.

Install the CLI Using a Local Python Package

Note To get the Python package (.whl file) for installing the CAT CLI, contact your You.i TV account representative.

After installing python and pip3, copy the latest Python package file (.whl) to your machine. Ensure the file name for the .whl file hasn’t changed during copying. If it has, rename it back to the original name.

Run the following command on the terminal for Linux and macOS, or Windows PowerShell for Windows, to install CAT CLI on your machine and follow the installation prompts as required:

pip3 install <path-to-whl-file>

where <path-to-whl-file> is the path to the .whl file.

Once done, you can invoke the CLI root command, youicloud, without any options or arguments on the terminal or PowerShell window from anywhere in your machine.

Uninstall the CLI

To uninstall the CLI, run the following command: pip3 uninstall youi_cloud_cli

Upgrade the CLI

If a newer version of the CLI is available, copy the latest Python package file to your local system. Run the following command by replacing <path-to-whl-file> with the path to the .whl file and follow the installation prompts as required:

pip3 install --upgrade <path-to-whl-file>

Configure User Credentials

Note You need to contact your You.i TV account representative to get user credentials. You can contact them at the same time, or after acquiring the CAT CLI python installer. An email will be sent with instructions on how to finalize the new-user setup.

To successfully issue commands with the CAT CLI, you will need to have valid user credentials configured in your computer. Currently the CAT CLI only supports sourcing credentials from environment variables.

You need to set the following environment variables. The example below is non-persistent and assumes a BASH shell. Issue the following two commands in your console where you will be issuing the CAT CLI commands.

export YOUI_CAT_CLI_USERNAME='<user_name>'
export YOUI_CAT_CLI_PASSWORD='<password>'

where the angle brackets (< >) indicate placeholders to be replaced by the actual values.

As including single quotes around the values is recommended, we don’t recommend that you add any single quotes in your actual password when you first set it up. Otherwise, use a backslash to escape any single quote in your password.

Tip You can also add the export commands above to your shell environment for a persistent configuration, such as .bash_profile and .zsh. You may need to re-source your existing console session for the changes to take effect.

Using the CAT CLI

The full structure of a CLI command is as follows:

youicloud [options] <command-group> [options] <command> [options] [arguments] [options]

The following table provides a quick summary of the command arguments that are used in the CLI commands:

Notes

• CLIENT_TAG and SERVER_TAG can have any number of digits, lower- and upper case letters, dashes (-), and dots (.), up to a maximum of 20 characters.
• Use the built-in help feature of the CLI commands to get more details on any of the commands.

Upload Client and Server Package

This section describes how to upload and download the client package and upload the server package. The assumed definitions for this quick start are:

APP_NAME = test-app STACK_DEF_ID = v1-0-0 STAGE_DEF_ID = v190507 DEPLOYMENT_REGION = us-east-1

Once the stack-admin has created all the definitions, you’ll get a stack URL in the following form: <STAGE_DEF_ID><REGION_SHORT_CODE>.<APP_NAME>-<STACK_DEF_ID>.<ROOT_DOMAIN>.com

You can use this URL, such as v190507e1.testapp-v1-0-1.youi-cloud-test.com, to upload the client package and server package.

Upload the Client Package

You need to upload the client archive file (.zip) and download the archive file that is currently mapped to a given stack id and client tag.

Step 1: Upload the Roku Client Package for Processing

Upload a single side-loadable client archive file (.zip) for Roku devices.

The uploaded zip files are mapped to a specific stack definition using the STACK_DEF_ID specified in the command. The Roku client’s manifest file is configured for production use, and configured to point to the application stack root URL for all future stack deployments mapping to the given STACK_DEF_ID. This command associates a client to the stack and configures the client manifest accordingly. The CLIENT_TAG is a fully user-definable value intended to be used to identify the specific client build or version number for the currently mapped client.

Command format: youicloud [OPTIONS] deployment [OPTIONS] upload-client-zip [OPTIONS] <APP_NAME> <STACK_DEF_ID> <CLIENT_TAG> <PATH_TO_FILE>

Example command: youicloud deployment upload-client-zip test-app v1-0-0 ~/Documents/roku_client_test-app_1.0.0.zip

Step 2: Download the Processed Client Zip

Acquire the configured Roku client zip currently mapped to a given STACK_DEF_ID and CLIENT_TAG.

Note For production apps only: Additional files uploaded to the same STACK_DEF_ID and CLIENT_TAG are not overwritten in storage; instead they are versioned. So it’s possible to acquire previous versions by specifying a value for VERSION_ID. The value for VERSION_ID with respect to a specific file is returned by the upload-client-zip command after it completes successfully.

Command format: youicloud [OPTIONS] deployment [OPTIONS] download-client-zip [OPTIONS] <APP_NAME> <STACK_DEF_ID> <CLIENT_TAG> <DOWNLOAD_PATH> [VERSION_ID]

Command: youicloud deployment download-client-zip test-app v1-0-0 ~/Documents/processedClients/

Upload the Server Image

The following table illustrates the best way to choose what steps you need to perform when you want to upload the server image:

Use Case 1: Server Image upload and Application Stack update are done by same person

Step 1: Package the Server Image

The CLI doesn’t currently create the server image package, and you’ll need to do it manually using the tar command, as in tar --exclude="*deploy.sh" --exclude="*deploy_readme.txt" --exclude=appname.tar -cf appname.tar ./

The example command above should be run from the build output folder. This means the tar command above should be run from inside the bin folder, if the build output folder path is build/linux/Release/bin. To save the package in a different location, change the second to last argument. To target the build folder from a different location, change the last argument.

Note Ensure the size of the .tar file is 1 GB or less to avoid any storage-related errors during the uploading of the application stack server image.

Step 2: Upload and Update the Application Stack Server Image (in One Step)

To update a deployment, a server image must have first been uploaded using the upload-server-image command. The upload-server-image command can also be used to automatically update server instances immediately after the upload succeeds. To update a stack with a new server image in a single step, specify the --update-deployment option with the proper arguments as shown in the example command. You can use either the same value for SERVER_TAG or use a new value as required.

The SERVER_TAG argument is used to identify a particular server release version. It’s entirely up to you to decide what information the SERVER_TAG should contain, but ultimately the SERVER_TAG is used to map your uploaded server package to your stack, and inform you of particular build or release information relevant to the package being uploaded. The recommendation is to use a value known as the stack name, which is equivalent to <app_name>-<stack_def_id>, that is, the second URL component from the right in your provided stack URL, and prepend or append additional information as required.

Command format: youicloud [OPTIONS] deployment [OPTIONS] upload-server-image --update-deployment <STACK_DEF_ID> <STAGE_DEF_ID> [OPTIONS] <APP_NAME> <SERVER_TAG> <EXECUTABLE_FILENAME> <PATH_TO_FILE>

Example command: youicloud deployment upload-server-image --update-deployment v1-0-0 v190507 test-app test-app-v1-0-0 testapp ~/Documents/testapp.tar

Note Once the update command returns, you’ll need to wait about 5 minutes for the servers to finish rebooting before you can use the stack again successfully.

Step 3: Confirm the Successful Update

Confirm server image update has completed successfully by running the query-definitions command, and verify the StatusMessage field has changed to completed. The update process takes around 5 minutes.

Command Format: youicloud [OPTIONS] deployment [OPTIONS] query-definitions [OPTIONS] <APP_NAME> <STACK_DEF_ID> <STAGE_DEF_ID> <DEPLOYMENT_REGION>

Command: youicloud deployment query-definitions test-app v1-0-0 v190507 us-east-1

Use Case 2: Server Image Upload and Application Stack Update Are Done by Different Persons

Step 1: Packaging the Server Image

The CLI doesn’t currently create the server image package, and you’ll need to do it manually using the tar command, such as tar --exclude="*deploy.sh" --exclude="*deploy_readme.txt" --exclude=appname.tar -cf appname.tar ./

The example command above should be run from the build output folder. This means the tar command above should be run from inside the bin folder, if the build output folder path is build/linux/Release/bin. To save the package in a different location, change the second to last argument. To target the build folder from a different location, change the last argument.

Note Ensure the size of the .tar file is 1 GB or less to avoid any storage-related errors during the uploading of the application stack server image.

Step 2: Upload a Server Package

Upload a server image file to be used for application stack deployments.

Command Format: youicloud [OPTIONS] deployment [OPTIONS] upload-server-image [OPTIONS] <APP_NAME> <SERVER_TAG> <EXECUTABLE_FILENAME> <PATH_TO_FILE>

Command: youicloud deployment upload-server-image test-app test-app-v1-0-0 testapp ~/Documents/testapp.tar

Step 3: Update the Application Stack Server

Deployment updates are requested using the update-servers command. By default, the command initiates a stack update using the latest server image file that was uploaded with a matching SERVER_TAG argument. If you want to specify a previously uploaded file version instead of creating a new file version, add SERVER_TAG_VERSION_ID to the command. The SERVER_TAG_VERSION_ID value is returned by the upload-server-image command.

Command format: youicloud [OPTIONS] deployment [OPTIONS] update-servers [OPTIONS] <APP_NAME> <STACK_DEF_ID> <STAGE_DEF_ID> <SERVER_TAG> [SERVER_TAG_VERSION_ID]

Example command: youicloud deployment update-servers test-app v1-0-0 v190507 test-app-v1-0-0

Note Once the update command returns, you’ll need to wait approximately 5 minutes for the servers to finish rebooting before you can use the stack again successfully.

Step 4: Confirm the Successful Update

Confirm that the server image update has completed successfully by running the query-definitions command, and verify the StatusMessage field has changed to completed. The update process takes around 5 minutes.

Command Format: youicloud [OPTIONS] deployment [OPTIONS] query-definitions [OPTIONS] <APP_NAME> <STACK_DEF_ID> <STAGE_DEF_ID> <DEPLOYMENT_REGION>

Command: youicloud deployment query-definitions test-app v1-0-0 v190507 us-east-1

Common Reasons for Server Image Upload Failure

One of the following are the general causes of failure that you may see when you upload a new application stack server image:

• The root-level folder structure of the server image (.tar file) uploaded is different from the previously uploaded server image (.tar file) folder structure.
• The executable file name, stated in the CLI commands, is not same as the actual file name in the packaged server image (.tar).

AWS Regional Code Shorthand Mappings

This table provides the short name for each AWS region that’s supported with CAT: