DIHCTL

Overview

The DIHCTL command line application is intended to perform different actions on the working Smart DIHClosed installation (environment). It can be run manually, or as part of a CI/CD pipeline.

DIHCTL can connect to multiple Smart DIHClosed environments, and can be used to clone Smart DIH configurations from one environment to another. dihctl operates by sending RESTClosed/GraphQL requests to the dih-admin service, which is part of the Smart DIH installation. For that purpose, dih-admin is added to the ingress of the KubernetesClosed cluster.

To authenticate DIHCTL use dedicated User Access Token configuration screen.

In order to authenticate DIHCTL, a dedicated User Access Token must be configured.

DIHCTL Installation

  1. Download the DIHCTL installer for your operating system:

    Operating system

    Arch

    Download link

    macOS

    arm64

    Download

    Linux

    x86_64

    Download

  2. Open a terminal in the download location and run the following command:

    tar -xzvf dihctl-1.0.0-Darwin-arm64.tgz -C ~ cd ~ sudo xattr -r -d com.apple.quarantine dihctl/ dihctl/dihctl version

Creating a User Access Token for DIHCTL

A user access token is needed to authenticate DIHCTL.

To create a user access token:

  1. In SpaceDeckClosed, click Settings and go to User Access Tokens.

  2. Click New.

  3. Enter a Description.

  4. Select the Duration in Days.

  5. Click Create Token.

  6. After the new token is created, a popup window appears, showing the access key and the command required for DIHCTL to login.

    You have only one chance to copy the access key and command. Copy the command and execute it from the DIHCTL installation folder (i.e. ~/dihctl):

    ch ~/dihctl ./dihctl -e team9.gigaspaces.net login http://team9.gigaspaces.net/dih-admin --bearer TOKEN

    The -e parameter specifies the alias name for the Smart DIH environment.

    SpaceDeck generates environment names by the ingress hostname. You can modify these environment names, for example: staging, production, dev.

Show Entities

You can use DIHCTL to show entities in a Smart DIH environment. For example, to show entities in an environment with the alias name staging:

./dihctl help show ./dihctl -e staging show pipelines ./dihctl -e staging show pipelines --help ./dihctl -e staging show services -f csv ./dihctl -e staging show spaces ./dihctl -e staging show datasources

Export Existing Configurations

Description:

To export definitions of existing pipelines, services, spaces, or relations in a certain environment into a specified output file in yaml format.

Command:

dihctl -e <environment_name> export <entity_name> <name1 name2 ...> -o <output.yaml>

Parameters:

Parameter Name Description

Required

environment_name

The environment to where the configuration will be exported.

Yes

entity_name

Which entity to export: pipelines, services, spaces, relations.

Yes

name1, name2,...

A list of entities to export, for example:

myPipelineName1 myPipelineName2

If this is not provided, all existing entities will be exported.

No

output.yaml

The full path of the output file.

Yes

Examples:

  1. Export pipelines myPipelineName1 myPipelineName2 from myEnv1 environment:

    dihctl -e myEnv1 export pipelines myPipelineName1 myPipelineName2 -o /home/user/pipelines.yaml

    Example of output pipelines.yaml:

    pipelines: - name: "myPipelineName1" datasource: "ORA1" spaceName: "demo" tablePipelines: - schema: "RETAIL_DEMO" name: "PRODUCTS" spaceTypeName: "PRODUCTS3" spaceId: [] routingKey: "PRODUCT_ID" indexes: [] tieredStorageConfig: rule: "DEFAULT" transformations: [] - name: "myPipelineName2" datasource: "ORA1" spaceName: "demo1" advanced: checkpointInterval: 2000 batchWrite: 10 tablePipelines: - schema: "RETAIL_DEMO" name: "CUSTOMERS" spaceTypeName: "CUSTOMERS3" spaceId: [] routingKey: "CUSTOMER_ID" indexes: [] tieredStorageConfig: rule: "DEFAULT" transformations: []
  2. Export all relations from myEnv1 environment:

    dihctl -e myEnv1 export relations -o /home/user/relations.yaml

Apply New Configurations (Import)

Description:

To apply a new configuration to the certain environment from the specified yaml file. Apply will attempt to create specified entities based on a conflict resolution mechanism and start/deploy them.

Command:

dihctl -e <environment_name> apply -s -f <input.yaml> --force --continue-on-errors

Parameters:

Parameter Name Description

Required

environment_name

The environment to which the configuration will be applied.

Yes

-fis

The full path of the input file containing the configuration definition in yaml format. It can contain any mix of configuration entities: pipelines, services, spaces, relations.

Yes

-s

For applying pipelines only. Whether to start the pipelines after the import.

No

--force

For applying pipelines only. Whether to try and override existing pipelines, if possible.

No

--continue-on-errors

For applying pipelines only. Whether to continue execution even if an error occurs in any of the table pipelines.

No

Examples:

  1. Force apply pipelines myPipelineName1 myPipelineName2 to myEnv1 environment and start them:

    dihctl -e myEnv1 apply -s -f /home/user/input.yaml --force --continue-on-errors

    Apply pipelines myPipelineName1 myPipelineName2 to myEnv1 environment, but do not start them:

    dihctl -e myEnv1 apply -f /home/user/input.yaml

    Example input.yaml:

    pipelines: - name: "myPipelineName1" datasource: "ORA1" spaceName: "demo" tablePipelines: - schema: "RETAIL_DEMO" name: "PRODUCTS" spaceTypeName: "PRODUCTS3" spaceId: [] routingKey: "PRODUCT_ID" indexes: [] tieredStorageConfig: rule: "DEFAULT" transformations: [] - name: "myPipelineName2" datasource: "ORA1" spaceName: "demo1" advanced: checkpointInterval: 2000 batchWrite: 10 tablePipelines: - schema: "RETAIL_DEMO" name: "CUSTOMERS" spaceTypeName: "CUSTOMERS3" spaceId: [] routingKey: "CUSTOMER_ID" indexes: [] tieredStorageConfig: rule: "DEFAULT" transformations: []
  2. Apply and deploy service myService1 to myEnv1 environment:

    dihctl -e myEnv1 apply -f /home/user/input.yaml

    Example input.yaml:

    services: - serviceName: "myService1" spaceName: "demo" sqlTemplate: "select * from CUSTOMERS" description: "" replicas: 1

Delete Entities

Description:

To delete specific pipelines or services in a specific environment.

Command:

dihctl -e <environment_name> delete <entity_name> <name1 name2 ...> --delete-subscription

Parameters:

Parameter Name Description

Required

environment_name

The environment from which the configuration will be deleted.

Yes

entity_name

Which entity to delete, pipelines or services.

Yes

name1, name2,...

A list of entities to delete, for example:

myPipelineName1 myPipelineName2

Yes

--delete-subscription

For deleting pipelines only. Whether or not to delete the pipeline subscription. The default value is 'yes'.

No

Examples:

  1. Delete pipelines myPipelineName1 myPipelineName2 from myEnv1 environment:

    dihctl -e myEnv1 delete pipelines myPipelineName1 myPipelineName2
  2. Delete service myService1 from myEnv1 environment:

    dihctl -e myEnv1 delete services myService1