DCT Toolkit
Introduction
DCT Toolkit (dct-toolkit) is the command line application specifically designed to interact with a particular DCT instance. It aims to simplify and ease out interacting with DCT instances while making the process intuitive, with minimal configuration and setup. dct-toolkit abstracts all of the API level implementation complexities and provides a user friendly LINUX-like interface, which can be run from any terminal.
Compatibility
dct-toolkit is designed to be compatible with any DCT product version, but is fully supported from DCT version 8.0.0 onwards. While dct-toolkit can be used in testing or development environments against any DCT versions, Delphix highly recommends at least DCT version 8.0.0 for using it in the production environment. Some of the value added features are only supported from DCT 8.0.0 version onwards.
dct-toolkit does not need to be upgraded with every new version of DCT. All of the new APIs that are part of the newer DCT releases will automatically be available in dct-toolkit. This is possible because dct-toolkit reads the api specification from the DCT instance (configurable) it is configured to connect to and dynamically generates the list of commands and their respective options.
Installation
Currently dct-toolkit is supported on Linux, Windows and macOS platforms. There are no special system requirements for running dct-toolkit.
Installing dct-toolkit is as simple as downloading the executable binaries from the downloads URL and extracting it to the machine from where it needs to run. Once the executable binary is extracted, grant the execute permission to the binary file.
On Linux and macOS this can be done from Terminal via:
chmod 777 ./dct-toolkit
For Windows this can be done from cmd via:
CACLS files /e /p <username>:F
Where <username>
is the user to whom the permission must be granted, F
is the Full Control permission that needs to be granted.
For macOS currently the binary is not verified hence macOS will give warning that the binary is untrusted. To get around this issue for now you will need to open this binary and explicitly whitelist it. One easy way to achieve this is to press CTRL key and click on the binary file and then select Open. On the resulting warning message dialog box select Open. Now the binary is allowed to be executed from the terminal.
Setup
A plain text configuration file is needed to get started. The recommended way to create this configuration file is via the create_config
command, available in dct-toolkit.
For creating a typical configuration with only the required properties, the following command can be used:
dct-toolkit create_config dctUrl=<URL of DCT instance> apiKey=<api key value>
This will create the configuration file in the default location under the user's home directory. The full path for configuration file will be: <users home directory>/.dct-toolkit/dct-toolkit.properties
create_config
command takes in below mentioned options:
Option name | Required/Optional | Description |
| Required | HTTP/S URL of the DCT instance. |
| Required | API key of the account used to connect to the DCT instance pointed by the |
| Optional | Fully qualified path of the properties file. If this option is not specified, the properties file will be created in the |
| Optional | API version to be used for DCT APIs. If this is not set then the latest API version from the DCT instance. |
| Optional | Location of the local api.yaml file. If this is not set, the latest api.yaml file will be downloaded from the DCT instance that is configured. |
| Optional | Whether to use insecure SSL connection to the DCT instance. By default this will be set to false. |
| Optional | Whether to disable hostname verifier checks for SSL connection to the DCT instance. By default this will be set to false. |
| Optional | PEM format SSL certificate path to be used for SSL connection to DCT instance. |
| Optional | Log level to set. Can be one of OFF, ERROR, WARN, INFO, DEBUG, TRACE, ALL. By default log level will be INFO. |
| Optional | Directory where the logs should be written. By default, logs will be written to the logs directory created under the |
All of these options and help can also be requested via:
./dct-toolkit create_config -h
All of the above properties can also be individually specified using environment variables. Environment variable mappings for each of the above properties is as follows:
Property Name | Environment Variable Name |
| DCT_TOOLKIT_DCT_URL |
| DCT_TOOLKIT_API_KEY |
| DCT_TOOLKIT_API_VERSION |
| DCT_TOOLKIT_API_YAML_LOCATION |
| DCT_TOOLKIT_SSL_INSECURE |
| DCT_TOOLKIT_SSL_UNSAFE_HOSTNAME_CHECK |
| DCT_TOOLKIT_SSL_CERT |
| DCT_TOOLKIT_LOG_LEVEL |
| DCT_TOOLKIT_LOG_DIR |
It’s acceptable to configure non-sensitive properties in a properties file and sensitive properties (like apiKey
) via an environment variable. Properties set via environment variable will take precedence over the ones specified in the properties file.
Once the required properties are available via either the properties file or via the environment variable, dct-toolkit is ready for use.
Usage guide
All of the DCT APIs are available as commands in dct-toolkit. To find the list of all commands which are available, use the command:
./dct-toolkit -h
This will print the list of all commands grouped by the appropriate entity names.
Examples
The list of available options for a particular command can be requested via:
./dct-toolkit <command_name> -h
There are currently a lot of options for provisioning a VDB, some options are only valid for a particular DB type. For example, the
unique_name
option is only applicable to Oracle DBs. For better ease of use, dct-toolkit has subcommands created under the provisioning command, with options that are relevant to that particular subcommand. For example, these are the subcommands under theprovision_vdb_by_snapshot
command:
oracle
sybase
mssql
appdata
postgres
For provisioning an Oracle VDB, the following command can be used:
dct-toolkit provision_vdb_by_snapshot oracle source_data_id=<dsourceId> --auto_select_repository unique_name=<uniqueName>
For provisioning a Sybase-ASE VDB, the following command can be used:
dct-toolkit provision_vdb_by_snapshot sybase source_data_id=<dsourceId> --auto_select_repository --truncate_log_on_checkpoint
For getting the list of registered engines, the following command can be used:
dct-toolkit get_registered_engines
The above command will only print important fields in the response. For printing all of the fields in the response, use:
-A/--all-columns
Option:
dct-toolkit get_registered_engines -A
There is also an option to list only the selected columns that are useful to the user:
--columns/-c
Option:
dct-toolkit get_registered_engines --columns=id,name,cpu_core_count...
For advanced use cases, dct-toolkit also provides an option to specify a jsonpath expression to extract required objects from the JSON response. This can be requested with:
--jsonpath/-jp
Option:
dct-toolkit get_registered_engines --jsonpath=<json path expression starting with $>
Note, these options are available for all of the commands available in dct-toolkit.
For commands that use a request body, dct-toolkit provides
-body
, which can be used to specify a JSON body (instead of using individual options).
dct-toolkit token_info --body=<JSON body to POST to DCT>
Help regarding the exact structure of JSON request and response body can be requested for all of the commands via:
-jh/--jsonhelp
Option:
dct-toolkit token_info -jh
dct-toolkit provides an easy to use and understand format for specifying tags. Example, this command to add two tags:
{key=purpose, value=testing}
and{key=key1, value=value1}
:
dct-toolkit create_environment_tags environmentId=<envId> tags purpose=testing key1=value1
Some of the DCT APIs trigger an asynchronous job and return a jobId in response. dct-toolkit, by default, will wait for the asynchronous job to get completed and will report the end state of the job. There is an option to NOT wait for the completion of an asynchronous job. For example, to NOT wait, use the
--no-wait
option:
dct-toolkit refresh_environment environmentId=<envId> --no-wait
Logging
dct-toolkit has inbuilt logging support which will export all of the logs to a default location which is under the user's home directory. The full path will be <user home directory>/.dct-toolkit/logs
. dct-toolkit creates a separate log file for every date.
Log level and log directory are both configurable and can be specified in the configuration file or via the environment variable. Please refer to the Setup section above for more information.