Using the Cogynt Delivery Tool

The Cogynt Delivery Tool is designed to simplify the configuration and deployment process for Cogynt. It comes in the form of a downloadable binary that is run from the command line.

The following builds are currently available:

• MacOS: Darwin AMD64 and ARM64
• Linux: AMD64 and ARM64
• Windows: AMD64

Configuring the Cogynt Delivery Tool

The configuration for the Cogynt Delivery Tool is defined in the ia.env.yaml file. This YAML file sets the parameters for the Cogynt environment that the tool will set up. The various field values can be modified as needed in any text editor.

For detailed descriptions of the ia.env.yaml fields, see the API Reference.

note

Blank field values in the ia.env.yaml file indicate that the field's default value should be used.

Running the Cogynt Delivery Tool

The Cogynt Delivery Tool applies the configurations specified in the manifest files to the cluster where your Cogynt instance will be hosted. (For more information about the manifest files, see Readying Terraform Modules and Configuring the Cogynt Delivery Tool.) With a handful of command line inputs, the tool configures and deploys the necessary Cogynt infrastructure, including licenses.

For information about performing dry (test) runs of the setup process, see Performing Test Runs.

Cogynt Delivery Tool Commands

All Cogynt Delivery Tool commands use the syntax kubectl-cogynt <COMMAND>, where <COMMAND> is one of the commands listed in the following table.

Command	Description
apply	Deploys Cogynt using manifest files. For more information, see Deploying Cogynt.
completion	Generates the autocompletion script for the specified shell.
hcvault	Interacts with the Cogynt-installed hcvault (HashiCorp Vault).
help	Help about any command or flag.
license	Interacts with the Cogynt license. For more information, see Working with Licenses.

The tool also supports a number of flags to direct and control its operations. For more information, see CLI Flags.

Deploying Cogynt

The main use of the Cogynt Delivery Tool is to set up Cogynt on an existing cluster.

To set up Cogynt using the Cogynt Delivery Tool:

1. Open a terminal.

2. In the command line interface, navigate to the cogynt-delivery root directory.

3. From the root directory, enter and run the following command:

   kubectl-cogynt apply -f <PATH TO IA.ENV.YAML> --debug --tlspem <PATH TO TLS CERTIFICATE> --tlskey <PATH TO PRIVATE KEY> --storePath <PATH TO LICENSE STORAGE> --clusterName <CLUSTER NAME>

   Where:

   • <PATH TO IA.ENV.YAML> is the path to the ia.env.yaml configuration file.
   • <PATH TO TLS CERTIFICATE> is the path to the TLS certificate file. It is typically stored under a directory named ssl-certs in the infrastructure of the cluster that will host Cogynt.
   • <PATH TO PRIVATE KEY> is the path to the key file. It is typically stored under a directory named ssl-certs in the infrastructure of the cluster that will host Cogynt.
   • <PATH TO LICENSE STORAGE> is the path to where the HashiCorp Vault credential will be stored. When the Cogynt Delivery Tool is run, it creates a database consisting of a single .db file on the local machine. This database stores a HashiCorp Vault credential for later access. Cogynt uses HashiCorp Vault for managing security, secrets, and licensing. The stored credential is needed as a security measure for future cluster communications.
   • <CLUSTER NAME> is the name of the cluster that the kubectl-cogynt command should run against. (Note: This parameter is optional.)

4. The cluster status is deplayed. Take note of the Cluster ID if you need to request a Cogynt license. For more information, see Acquiring Licenses.

note

When the tool is run for the first time, it prompts the user to create a store passphrase. This encrypts and decrypts the license database.

Using the environment variable COGYNT_PASSPHRASE automatically adds the passphrase to the list of the user's commands.

Performing Test Runs

The Cogynt Delivery Tool provides an option to perform a test run of the deployment process.

To perform a test run, add the --dry flag to the command in Step 3 of Deploying Cogynt. This flag instructs the tool to output a raw manifest without applying it to the target cluster. The manifest can then be reviewed for errors before it is applied.

Working with Licenses

The Cogynt Delivery Tool has mechanisms for creating and applying Cogynt licenses.

Acquiring Licenses

Cogility provides license files to customers based on the cluster information that the tool returns.

To acquire a license from Cogility:

1. Run the Cogynt Delivery Tool and deploy Cogynt. For more information, see Deploying Cogynt.
2. Obtain the Cluster ID of your cluster using one of the following methods:
   • Take note of the Cluster ID that is displayed after the apply command is successfully run.
   • Run the following command in the cogynt-delivery root directory: kubectl-cogynt license --clusterName <CLUSTER NAME> --storePath <PATH TO LICENSE STORAGE> --status, where:
     • <CLUSTER NAME> is the name of the cluster that the kubectl-cogynt command should run against.
     • <PATH TO LICENSE STORAGE> is the path to the HashiCorp Vault credential (a .db file).
3. Send the Cluster ID to Cogility.
4. Cogility will send a unique JSON license file in reply.

Applying Licenses

Once Cogility has provided a JSON license file, the Cogynt Delivery Tool can apply the license to your Cogynt instance.

To apply a license:

1. Open a terminal.
2. In the command line interface, navigate to the cogynt-delivery root directory.
3. From the root directory, enter and run the following command: kubectl-cogynt license --clusterName <CLUSTER NAME> --storePath <PATH TO LICENSE STORAGE> -f <PATH TO LICENSE FILE>, where:
   • <CLUSTER NAME> is the name of the cluster that the kubectl-cogynt command should run against.
   • <PATH TO LICENSE STORAGE> is the path to the HashiCorp Vault credential (a .db file).
   • <PATH TO LICENSE FILE> is the path to the JSON license file that Cogility provided.

Once the command is run, the license is uploaded to the HashiCorp Vault, which then manages the license lifecycle from that point forward.

CLI Flags

The Cogynt Delivery Tool supports of a number of flags to direct and control the installation process.

To see a list of all the flags from the command line, use the command kubectl-cogynt help, or the --help or -h options. Use kubectl-cogynt <COMMAND> --help for more information about a specific command, where <COMMAND> is the command to describe (such as apply or license).

The available flags and their functions are described in the following table.

Flag	Description
--as string	Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
--as-group stringArray	Group to impersonate for the operation. This flag can be repeated to specify multiple groups.
--as-uid string	UID to impersonate for the operation.
--cache-dir string	Default cache directory.
--certificate-authority string	Path to a cert file for the certificate authority.
--client-certificate string	Path to a client certificate file for TLS.
--client-key string	Path to a client key file for TLS.
--cluster string	The name of the kubeconfig cluster to use.
--clusterName string	Unique name for this cluster.
--context string	The name of the kubeconfig context to use.
--debug	Set log level to debug.
--debugManifests	Set log level to debug for manifests also.
-h or --help	Help for kubectl-cogynt, its commands, and its flags.
--insecure-skip-tls-verify	If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
-m or --k8sManifests string	Path to local file system manifests (default: .).
--kubeconfig string	Path to the kubeconfig file to use for CLI requests.
-l or --license string	Name of the license for the project.
-n or --namespace string	If present, the namespace scope for this CLI request.
--request-timeout string	The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (Default: 0).
-s or --server string	The address and port of the Kubernetes API server.
--storePath string	Path to local file system k/v store (default: ./cogynt.db).
--tls-server-name string	Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used.
--tlskey string	Path to the TLS Key file.
--tlspem string	Path to the TLS PEM file.
--token string	Bearer token for authentication to the API server.
--user string	The name of the kubeconfig user to use.