K8S ACTIONSCRIPTS

TBUtil Action Scripts Pod

Label	Value
Date	23 janv. 2024
Author	Chris Lowth - [email protected]
TBUtil version	3.4

The TBUtil actionscript flavoured pod provides a useful base for writing Turbonomic actions scripts, and a tool to assist in deploying them.

It also provides a couple of dummy template scripts that do nothing, but that can be used as a starting point for creating your own.

Action scripts - product documentation

Turbonomic action scripts are documented in the product's on-line user guide, which you can read at https://www.ibm.com/docs/en/tarm .

Relevant sections is this one: https://www.ibm.com/docs/en/tarm/8.9.0?topic=policies-deploying-action-scripts (Search for "action scripts" in field "Filter on titles" from documentation)

Note that the information about the context in which a script is being called is passed to it via environment variables and a JSON document on it's standard input.

Configuring the scripts

Setting up a script involves the steps described in the documentation. The TBUtil actionscript pod helps to simplify some of them for you.

The high-level steps are ..

• Write the script and install it on a system where it can be reached using SSH.
  • the TBUtil actionscript flavour pod provides such a platform.
• Create a manifest file that describes your script as per the documentation.
  • the TBUtil pod has a script that does this for you based on "magic comments" you supply in your script.
• Create a Turbonomic Orchestrator target and configure it with the address of the SSH service, the name of the manfiest file, the user name and private key.
  • the script also does this for you.
• Configure policies using the Turbonomic UI to call the scripts at the desired steps of their workflows.

Installing the pod

Install the container as a K8S pod by following these instructions using the word "actionscripts" as the pod flavour.

Once installed, you can set up the scripts and then register the script server with Turbonomic.

The scripts need to be placed in one of two locations (described below) and include some special comments (also described below). Once these have been placed into the pod, the add-actionscript-target script can be used to complete the process.

Script location

The action scripts in the pod live in one of two directories.

Directory	Customisable?	Persisted?	Description
/home/tbutil/actionScripts	Yes	Yes	Custom scripts, or editted versions of the supplied scripts.
/usr/local/actionScripts	No	No	Contains scripts that are supplied with the container image (or images that are based on it). Any edits made to these files will be reversed if the pod is ever deleted (for example: during an update). To edit one of these, first copy it to /home/tbutil/actionScripts (using the same base name) and edit the copy.

If a script in /home/tbutil/actionScripts has the same name as one in /usr/local/actionScripts then the add-actionscript-target utility (described below) causes the former one to be used in place of the latter. The former folder is persisted in a K8S PVC and so will survive container restarts. The latter will not.

If you wish to build your own container pod using ours as the base, then you could place your scripts in the /usr/local/actionScripts folder in your new container image.

Script format

All action scripts to be implemented on the pod (and be configured using add-actionscript-target) must have an extension of ".sh" and include the following "magic" comments in the header...

Key	Meaning
@enabled	Either "true" or "false" to indicate whether or not the script is enabled.
@name	The script name that will be shown in the Turbonomic UI.
@description	A one-line description of the script. This is effectively just a comment.
@entityType	The type of entity. The script can only be applied to actions on entities of this type.
@actionType	The type of action to which the script can be applied.
@actionPhase	The action phase to which the script can be applied.

Valid entityTypes are:

• APPLICATION_COMPONENT
• BUSINESS_APPLICATION
• BUSINESS_TRANSACTION
• BUSINESS_USER
• CONTAINER_POD
• CONTAINER_SPEC
• DATABASE
• DATABASE_SERVER
• DESKTOP_POOL
• DISK_ARRAY
• PHYSICAL_MACHINE
• IO_MODULE
• LOGICAL_POOL
• SERVICE
• STORAGE_CONTROLLER
• STORAGE
• SWITCH
• VIEW_POD
• VIRTUAL_MACHINE
• VIRTUAL_VOLUME
• WORKLOAD_CONTROLLER

Valid actionTypes are:

• ADD_PROVIDER
• CHANGE
• CROSS_TARGET_MOVE
• DELETE
• MOVE
• MOVE_TOGETHER
• PROVISION
• RECONFIGURE
• RESIZE
• RESIZE_CAPACITY
• RIGHT_SIZE
• SCALE
• START
• SUSPEND
• TERMINATE

Valid actionPhases are:

• AFTER_EXECUTION
• APPROVAL
• ON_GENERATION
• POST
• PRE
• REPLACE

Here's a valid example...

#! /bin/bash

# @enabled: false
# @name: VmMovePre
# @description: Execute this script in preperation for a VM Move
# @entityType: VIRTUAL_MACHINE
# @actionType: MOVE
# @actionPhase: PRE

... script code follows here ...

Coding a new script.

When using the TBUtil action script pod, we recommend writing your scripts using the BASH shell language and following the conventions that allow the add-actionscript-target tool to recognise them. You should...

• Place your script in the directory /home/tbutil/actionScripts (create it if it doesnt exist).
• Make it executable:
  • Give it execution rights using chmod +x FILENAME
  • Give it a first line, reading #! /bin/bash
  • Give it the extension ".sh".
• Populate the magic comments noted above.
• Place any configuration and other files it uses and that need to be persistent in /home/tbutil or a child directory.

Your code can:

• Inspect the JSON document passed on its standard input using jq or tbscript.
• Inspect the environment variables (see the product documentation for the values to expect).
• Query the Turbonomic REST API using tbutil or tbscript.
• Take any other actions that it needs, using the available linux commands.

Your code should:

• Avoid CPU or Memory-intensive actions.
• Check errors and log them to a file of your choice.

If your script needs Alpine linux packages that are not installed in the supplied pod, then you can create your own container using ours as the "FROM" base in the Dockerfile, and add the packages you need to that.

If you use our pod as the FROM base of your own, then you may also choose to place your action scripts in /usr/local/actionsScripts so that they are part of the pod static content.

Registering the script server

Turbonomic needs to discover the pod and the scripts it contains, but first you should configure the Turbonomic credentials for the pod.

1. Log in to the pod using the command kubectl exec -ti deploy/tbutil-actionscripts -- /bin/bash
2. Configure credentials using the command tbutil save local credentials.
   • IP address or hostname: For an OVA deployment, the answer is almost certainly "nginx" (this is the default).
   • API/UI User name: Give the name of a user with admin rights. The default of administrator is usually good.
   • password: Give the administrator user's password
3. Ensure that the action scripts you want to register are correctly formatted, as described above.
4. Register the script server by running the command: add-actionscript-target

Note that it can take 10 or more minutes for the scripts you have defined to be visible to the Turbonomic policy editor UI.

Once registered, you can change the policy configuration via the UI to use the scripts.