_target secrets file

Target secrets file.

When exporting targets using tbutil's export targets or export from hot commands, you have the option of specifying the name of a JSON file from which target secrets (such as passwords) can be read. This page describes that file.

Target concepts

In order to understand its format, we first need to understand some concepts..

Each target in Turbonomic is identified by a combination of three strings:

• A "category". Possible values include "Applications and Databases", "Cloud Native", "Hypervisor" etc. The exact set recognised by your installation depends on the probes enabled in it's configuration, but you can see them in the "Category" column when you run "tbutil list target types".
• A "type". Different categories support different types. Here again, the "tbutil list target types" command gives you all the supported values.
• A "display name". This is the name of the target seen in the UI and in the output of "tbutil list targets -l"

Targets have zero or more "secrets" which have a name and a value. The names of the secrets for each possible target type are also shown by the "tbutil list target types" command.

File format

The target secrets file combines all these bits of information as a JSON object that is formatted as follows..

{
    "category_name": {
        "type_name": {
            "display_name": {
                "secret_name": "value"
            }
        }
    }
}

Here's small example that supplies the passwords and keys for seven targets..

{
    "Applications and Databases": {
        "AppDynamics": {
            "appd.example.com": {
                "password": "xxxxxxxxxxxxxxxxxxxx"
            }
        },
        "Datadog": {
            "ddog.example.com": {
                "apiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "applicationKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
            }
        },
        "Dynatrace": {
            "dtrace.example.com": {
                "apiToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
            }
        }
    },
    "Hypervisor": {
        "Hyper-V": {
            "hp-cluster.example.com": {
                "password": "xxxxxxxxxxxxxxxxxxxxxx"
            },
            "hpv0001.example.com": {
                "password": "xxxxxxxxxxxxxxxxxxxxxx"
            }
        },
        "vCenter": {
            "vsphere1.example.com": {
                "password": "xxxxxxxxxxxxxxxxxxxxxx"
            },
            "vsphere2.example.com": {
                "password": "xxxxxxxxxxxxxxxxxxxxxx"
            }
        }
    }
}

You can use the following command to create a blank template copy of this file (with all the secrets as empty strings) for the exportable targets in your Turbonomic instance, ready for you to add the actual secret strings to..

If you have the pod installed on the HOT as well as the WARM (ie: when dashboards are being copied) then run the following command in the HOT system's pod and copy the resulting file to the WARM#s pod..

tbutil create target secrets file > secretsFile.json

If you are NOT copying dashboards (and so the pod is running on the WARM instance only), then run the following command in the WARM instance's pod..

tbutil @hot create target secrets file > secretsFile.json

Keeping the secrets secret.

The long-hand way

If you wish to store the passwords in the file in an encrypted form, then prepend the secret's name with a dollar sign and use the encypted value returned by the command "tbutil crypt -encode PASSWORD-GOES-HERE" as the value.

For example: for a vCenter target called "example.com" which has a password "betYouCantGuess" ..

You can obtain the encrypted form of the password by running the command...

tbutil crypt -encode "betYouCantGuess"

This will return a long hexadecimal string which should be placed in the JSON file, and the secret name ("password" in the example below) should have a dollar signed prepended to it, like this..

{
    "Hypervisor": {
        "vCenter": {
            "example.com": {
                "$password": "5dcbee0a7f501854858fb161a0a61004d8c7ebd91476b302b68fc750cc86d34b72aa2b3960e5a33b34e309a533f44980"
            }
        }
    }
}

The dollar at the sart of the name tells "tbutil" that what follows is an encrypted string.

A potentially easier way

An easier alternative may be to populate the file with the secrets in clear text and then run crypt target secrets subcommand on the file, like this...

tbutil crypt target secrets secretsFile.json

This will encrypt any un-encrypted secrets that the file contains and write the updated version back.

If you want to change a secret in the encrypted file, you can edit it to remove the leading dollar from the field concerned, write the clear-text password as the field value and then re-run the above command to encrypt it.

Note: if you use the template syntax (see below) in the file, the crypt target secrets will parse the template and write the updated parsed output to the file. This means that the original template "{{ ... }}" constructs will no longer form part of the updated file although their expanded equivalents will be.

Template expansion

The JSON file is read using the GO-Lang template parser which allows you to use variables for repeated strings, if that would help. Here's an example of what that could look like..

{{ $vcPass := "very secret indeed" }}
{{ $hvPass := "rather hard to guess" }}
{{ $domain := "example.com" }}
{
    "Hypervisor": {
        "Hyper-V": {
            "hp-cluster.{{ $domain }}": {
                "password": "{{ $hvPass }}"
            },
            "hpv0001.{{ $domain }}": {
                "password": "{{ $hvPass }}"
            }
        },
        "vCenter": {
            "vsphere1.{{ $domain }}": {
                "password": "{{ $vcPass }}"
            },
            "vsphere2.{{ $domain }}": {
                "password": "{{ $vcPass }}"
            }
        }
    }
}