Intro to Cloud Scripts

Overview

Cloud Scripts enable the invocation of custom functionality within supported applications, such as Course Manager. This is achieved by writing a script to implement the desired functionality and deploying it. Once deployed, the script can be configured for invocation within the supported application.

Cloud Scripts are a self-service capability, meaning customers are responsible for developing, debugging, and deploying scripts. Familiarity with scripting in a supported language and using command-line interfaces is required.

Installation

Install the cloudscripts command-line tool, linked from the cloudscripts README. Ensure the utility is on your system path by running cloudscripts from the command line and verifying that the help screen is displayed.

Setting Up Docker

cloudscripts uses Docker to develop, build, and test scripts. This requires a Docker daemon to be available during the development process. You can either use a local Docker daemon or deploy a Docker VM within your Kyndryl Cloud Uplift account, known as a Build Host.

Local Docker Setup

Use Docker Desktop (https://www.docker.com/products/docker-desktop/) or open-source alternatives like Colima (https://github.com/abiosoft/colima).

Kyndryl Cloud Uplift-based Docker Setup

If you're not already a Docker user, cloudscripts can deploy a Docker VM within your Kyndryl Cloud Uplift account to perform all Docker-dependent operations. This VM is called a Cloud Scripts Build Host.

Note: Only one Build Host can be provisioned at a time per Kyndryl Cloud Uplift user. Additionally, you should only interact with Cloud Scripts Build Host templates through the cloudscripts CLI — do not modify or manage them directly in the Kyndryl Cloud Uplift UI.

Get a Kyndryl Cloud Uplift API Token: Follow the instructions at https://help.skytap.com/kb-generate-api-token.html.
Configure cloudscripts:
- Run cloudscripts cloud login -u <YourKyndrylCloudUpliftUsername> -i and paste your API token at the password prompt.
Log into your application: Follow the steps in Logging In to authenticate with your application (e.g., Course Manager) via the cloudscripts CLI. This is required before provisioning your Build Host.
Provision Your Build Host:
- Example for US-Central: cloudscripts build-host provision -r US-Central.

Logging In

To deploy scripts, provide cloudscripts with credentials for the application you're using.

For Course Manager: Generate an API key from the Admin > API Keys page. Use the "token" as your username and the "secret" as your password.
Configure cloudscripts:
- Run cloudscripts login -e <ApplicationEndpoint> -u <YourApplicationUsername> -i and paste the application password. The endpoint is the base URL of the application (e.g., customername.skytap-portal.com).

When logged into cloudscripts, you manage scripts for a specific customer account in a specific application. If you have multiple Course Manager tenants, you can only manage scripts for one tenant at a time. The credentials remain saved until changed or cleared.

Creating a Script From a Template

Scripts are generated from templates, which provide structure, configuration, and placeholder code.

List Available Templates: Run cloudscripts templates list or browse at https://github.com/skytap/course-manager-examples/tree/master/cs-templates.
Generate a Script: Run cloudscripts scripts new -t <ScriptTemplateName> <ScriptDestinationPath>. This command generates a new directory at the specified destination path and extracts the specified template to that location.
- Example: cloudscripts scripts new -t ruby ~/cloudscripts/my_cool_ruby_script

Templates are available for several scripting languages, including Ruby, Python, Node.js (JavaScript), and Bash. For scripts meant to be used with Course Manager, there are several Course Manager-specific templates that provide additional libraries to help you interact with Course Manager labs. Each script template maps to a specific image or runtime environment.

Developing Your Script

Each script template includes an "entry point" script file for your code. Most templates provide integration with a package management tool for the respective scripting language. More specific information is available in the README.md file found in your script directory.

All script projects include a config/ directory containing configuration files that govern how your script will be packaged, deployed and executed. For most use cases, modification of the configuration files should not be required. For more advanced use cases, users can customize the configuration.

Running Your Script

Run your script locally using cloudscripts scripts run <ScriptPath>. This command uses the local or Kyndryl Cloud Uplift-based Docker deployment set up earlier to execute your script in a similar environment to how it will be invoked in production.

Depending on the size of your script and its dependencies, running your script may take a few moments, especially when using the remote Kyndryl Cloud Uplift-based Docker option. Docker's layer and image caching are used to improve performance across repeated invocations.

Pushing Your Script

Deploy your script with cloudscripts scripts push <ScriptPath>. To update an existing script, add the --force (-f) argument to confirm that you are overwriting a previously pushed script.

Once pushed, your script is available for use from supported applications. For more information, please consult the help documentation for the respective product.

Advanced Topics

Additional CLI Capabilities

Only a subset of the capabilities provided by cloudscripts have been described above. Please consult the cloudscripts README for a complete reference.

Custom Package Configuration

Most scripts must provide a file called config/package.yml. This configuration file specifies the build process for your script, if needed, as well as the files that will be packaged and deployed as dependencies for execution of your script.

The reason "most" scripts must provide config/package.yml, not "all": Some scripts may be entirely configuration-based and not contain any code at all. This is permitted specifically for the special case where you may want to simply execute a command in a container without needing to deploy any code. In this scenario, config/package.yml is not required.

Each script template provides a default config/package.yml suitable for most use cases, but you are welcome to make modifications as needed. Below is a complete, annotated version of the file with comments explaining each option.

# This is the package configuration file for your script.
# This file is optional. If provided, it resides in config/package.yml.
# If not provided, this means that the script will have no build process and include no
# source files. This may be appropriate for simpler use cases in which you may want a
# script to simply run a container, optionally with a command specified.

# Configures the build process for your package (optional).
# A build prepares your code for execution. For compiled languages, this may involve
# compiling and linking your code. For interpreted languages, this may be as simple as
# installing packages, or even nothing at all.
build:
  # Configures the runtime image to be used to build the script. A value is required.
  image: debian:bookworm

  # Configures the command to execute the script. Only one command is supported. If your
  # build requires multiple steps, you can specify a shell script.
  command:
    - "/bin/bash"
    - "-c"
    - "echo"

  # Configures the files to be copied from your local machine to the build container for
  # use during the build process. Specified as file paths relative to the script root.
  # Wildcards are supported.
  context:
    - "Gemfile"
    - "lib/**/*"

  # Configures the files to be copied from the build container to your local machine once
  # the build is complete. Specified as a mapping of file paths relative to the script
  # root to the full source path in the build container.
  devArtifacts:
    "package-lock.json": "/build/package-lock.json"

  # Specifies the files to be bundled into the script package once the build is complete.
  artifacts:
    "package-lock.json": "/build/package-lock.json"
    "node_modules": "/build/node_modules"

# Configures the source files to be included in the script package. Wildcards are
# supported.
src:
  - lib/**/*
  - script.sh

Custom Run Specification Configuration

Every script must have at least one run specification, or run spec, to be executable. This required run spec resides in config/run/default.yml, and it defines various parameters concerning how your script will be run.

Each script template provides a default config/run/default.yml suitable for most use cases, but additional configuration options are available if needed. Below is a complete, annotated version of the file with comments explaining each option.

# This is the the default run spec for your script. It configures how your script is run.
# This file must reside in config/run/default.yml.
# Creating additional run specs allows the same script to be run with different configurations.
# To do this, copy this content to a new file in the config/run directory.

# Configures the runtime image to be used for the script. A value is required.
image: debian:bookworm

# Configures the command to execute the script. Defaults to the the image's default entry point or command.
command:
  - "/bin/bash"
  - "./script.sh"

# Configures whether script should have Internet access. Defaults to true.
egress: true

# Configures the mount point for the script files and the working directory for the script. Defaults to "/script".
workDir: "/script"

Additionally, it is possible to provide additional run specs, which allows you to deploy a script once while allowing it to be invoked with different sets of configuration options. To do this, simply copy the default file to config/run/<YourCustomSpecName>.yml and customize accordingly.

If your script has multiple run specs, you will have the opportunity to select which one to use in the application where you are configuring it.

When you run the script locally using cloudscripts scripts run, the default run spec is implicitly used; this can be overridden with the -r option, i.e., cloudscripts scripts run . -r <YourCustomSpecName>.

Images (Runtime Environments)

An "image" refers to a runtime environment for a script, and corresponds to a Docker image hosted by Kyndryl Cloud Uplift and available for use with Cloud Scripts. Kyndryl Cloud Uplift maintains several public images that are available for use, and each script template is preconfigured to use the most appropriate such image. The images offered are based on the Debian Bookworm distribution as of this writing and can be listed with cloudscripts images list.

In some cases, the stock images may not be sufficient -- e.g., if you wish to use a different programming or scripting language, or need OS-level dependencies that are not installed by default on our images. For these situations, custom images are supported. This capability provides you with a Docker image registry to which you can push your desired image, whether it be a public image you've pulled down or a totally custom image you've built. That image can then be specified as your build image (configured in config/package.yml) and/or your runtime image (configured in run/default.yml or your custom run spec definition).

Use of custom images requires the Docker CLI and familiarity with Docker tooling and image maintenance practices. Customers are responsible for creating and maintaining any custom images they push to the service.

To create a custom image, run cloudscripts images create <YourCustomImageName>. This command will return a Docker repository URL, username, and password. You can then use Docker tooling to build (if appropriate), tag, and push your image to our repository. Once done, the image is immediately available for use.

Important: Platform Architecture

The Cloud Scripts platform runs on the linux/amd64 platform. If your Docker installation uses a different platform (such as linux/arm64 on Apple Silicon Macs), you must ensure that your images are built for the linux/amd64 platform to work correctly in the Cloud Scripts environment.

When pulling or building images, use the --platform option to specify the target platform:

# When pulling an image:
docker pull --platform linux/amd64 <image-name>

# When building an image:
docker build --platform linux/amd64 -t <image-name> .

Before pushing your image, verify its architecture:

docker image inspect <image-name> --format '{{.Architecture}}'

The output should be amd64. If it shows a different architecture (like arm64), the image may not work correctly in the Cloud Scripts environment.

Using your Cloud Scripts Build Host to work with images

If you have deployed a Kyndryl Cloud Uplift-based Cloud Scripts Build Host, you can connect the Docker CLI to it for use as your Docker host. This requires you to execute a series of commands in your shell to extract the Build Host's private key, configure your SSH client to use that key, and then configure the Docker CLI to connect to the Build Host via SSH. For detailed instructions, run cloudscripts build-host docker-access.