K8S ADOPTION

Turbonomic Adoption Review POD

• Version: 3.4 / mar. 23 janv. 2024 16:45:54 CET
• By: Chris Lowth
• Status: For use by IBM Turbonomic field staff only.

Pre-Requisites.

This tool should be used with the assistance of a member of the IBM Turbonomic post-sales team.

Before running the tool, confirm that you have..

1: The software

• Either the pod image zip file (for off-line installations) or a recent copy of the yamlmaker tool (for on-line installations).
  • This is quite large, so it could be worth asking the customer to do the download in advance.

The links for downloading the zip file or yamlmaker tool are included in these instructions.

2: A PIN code for the day

• The PIN code for the day you will run the tool on.
  • You can obtain this by posting a request on the dedicated slack channel #turbonomic-tar-pin-request in advance. your message should include at least the following details..
    • WHO: Your name and role in IBM and the market in which you operate.
    • WHEN: the date when you will be running the tool (give us plenty of notice).
    • for WHOM: The name of the customer and a high-level description of the Turbonomic installation. For example: is this Turbo or CWOM? Is this a SAAS, OVA or custom K8S deployment? Approximately how many VMs and Containers are managed by the instance? Which target types are in use?
    • WHERE: Where are they on their adoption journey?
    • WHY: what's the business reason for running the tool?

NB: this version of tbutil no longer requires an "unlock code".

Installing the tool POD.

Follow these instructions using the text "adoption" as the flavour name.

A note about the namespace used.

In the following instructions, "NAMESPACE" should be replaced with "turbonomic" or "tbutil", depending on the answer you gave when you ran the yamlmaker tool during the installation.

Using a customer logo image.

If you provide a suitable image file containing the customer's logo, this can be embedded in the cover page of the document. You can do this in one of two ways..

• Copy the image into the tool's directory structure - in which case it can be embedded automatically.
• Apply the image to the created MS Word document by hand after it has been created.

You should follow the steps below before running the tool for the first of these two options (I'll assume you know enough about using "Word" to use the second option without needing additional instructions).

If you do not have a logo image available, or you choose to follow the second option (copying it into the doc by hand) then leave the "logo image file" field of the form blank when you run the tool.

To use the first option ...

1. Locate a suitable image.
   • It SHOULD not be a particularly large file (1Mb is about right).
   • It MUST be named "logo.png", "logo.jpg", "logo.jpeg" or "logo.gif".
   • The extension used MUST be consistent with the format.
   • It will be resized to 502px wide and 300px high - so aim to use am image with similar dimensions.
   • It will be mounted on a pure white background, so an image which also has a pure white background will look best.
2. If you will be running the tool on an OVA Turbonomic/CWOM installation then copy the file to the /tmp directory of the OVA.
3. If you are NOT going to run on an OVA installation, then copy the file to the /tmp directory of pod using kubectl cp like this..
   • kubectl -n NAMESPACE get pods (note the full pod name)
   • kubectl -n NAMESPACE cp LOGO-FILE-NAME POD-NAME:/tmp/LOGO-FILE-NAME
   • For example: kubectl -n tbutil cp logo.png tbutil-adoption-64ff4895d9-jzj89:/tmp/logo.png
4. When you run the tool, it should find the logo file and fill the path name in the form for you. But if not - type it in yourself. For example
   • /local-tmp/logo.png (on an OVA installation)
   • /tmp/logo.png (on a non-OVA installation)

Running the tool

Once installed...

1. If you're not already running a shell in the tbutil-adoption pod then start one..
   • kubectl -n NAMESPACE exec -ti deploy/tbutil-adoption -- /bin/bash
   • If you get the error message invalid resource name "deploy/tbutil-adoption" then you are running an old version of the kubectl command. The bye-pass is to use a two-command process, as follows..
     • First: Get the name of the pod using the command:
       • kubectl -n NAMESPACE get pods
     • Then: Use the full pod name in the "exec" command like this..
       • kubectl -n NAMESPACE exec -ti POD_NAME_HERE -- /bin/bash
2. Set up the tbutil credentials (answer the questions the command asks)
   • tbutil save local credentials
3. Move to the "xl-adoption" folder by running the command.
   • cd xl-adoption
4. Run the script by running the following command and answering the questions it asks.
   • sh run.sh

The script can take quite a long time to run, so wait until the message appears to say that it is finished.

Downloading the report

If all went well, a minimal web server will start in the POD. This allows you to view an HTML version of the document or download the Word version using your browser (provided the network configuration allow you to access port 31313 on the Turbonomic instance). The URL to browse to will be shown in the message at the end of the tool's execution.

You will be asked to re-enter the password you used for the Turbonomic administrator user when you configured the credentials at the start.

Note: the web server will stop when you type "finished" at the prompt.

If downloading that way doesn't work (usually for firewall reasons), type "finished" and then "exit" to leave the POD's shell. After that you have a couple of options..

OVA Installations

The report document will have been copied to the /tmp folder of the OVA itself and can be downloaded from there using WinSCP or your favourite equivalent. The name of the file is adoption-report.docx.

There should also be a file called adoption-diags.tgz there. This is the file to send to me if you feel that something has gone wrong.

Other Installation Types

If Turbonomic is not installed as an OVA, then you can copy the file from the POD directly using the kubectl command.

First: get the POD's full name using the following command (change "NAMESPACE" to the right value)..

kubectl -n NAMESPACE get pods

Then: copy the report file from the POD to your local file system using the following command (change "NAMESPACE" and "POD-NAME" to the right values)..

kubectl -n NAMESPACE cp POD-NAME:/home/tbutil/xl-adoption/report.docx report.docx

You can then copy the file from there to a running Microsoft Word to view and edit it.

Editing section headers and summary widgets

The created document uses embedded PNG images for the section titles and the widgets on the summary page. These cannot easily be modified without exporting them and editing using an external image editor.

However, the tool also creates an experimental version of the document that has these elements converted to equivalent editable "Shape" elements. This version of the document is called report_e.docx and you can download it by adding the "_e" suffix to the instructions above.

On the whole, I would recommend using the non-experimental version unless you have a specific need to edit the relevant document elements.

Uninstalling and Deleting

Refer to the subsection "Deleting the K8S resources" of these instructions.

But note:

• The capital "-U" option for the deploy-tbutil-adoption-3.4.sh command is not supported for the pod because it does not create a PVC. You will need to use lower case "-u" instead.
• Uninstalling the POD does not delete the created files from the /tmp directory of the OVA (if you are running on an OVA system).