Jikkou CLI Documentation

• 1: Basic CLI Features
• 2: CLI Configuration
• 3: Automating Jikkou
• 3.1: Automate Jikkou with GitHub Actions

1 - Basic CLI Features

The command line interface to Jikkou is the jikkou command, which accepts a variety of subcommands such as jikkou apply or jikkou validate.

To view a list of the commands available in your current Jikkou version, run jikkou with no additional arguments:

Usage: 
jikkou [-hV] [--logger-level=<level>] [COMMAND]


Jikkou CLI:: A command-line client designed to provide an efficient and easy way to manage, automate, and provision all the assets of your data infrastructure.

Find more information at: https://streamthoughts.github.io/jikkou/.

OPTIONS:

  -h, --help      Show this help message and exit.
      --logger-level=<level>
                  Specify the log level verbosity to be used while running a command.
                  Valid level values are: TRACE, DEBUG, INFO, WARN, ERROR.
                  For example, `--logger-level=INFO`
  -V, --version   Print version information and exit.

CORE COMMANDS:
  apply                     Update the resources as described by the resource definition files.
  create                    Create resources from the resource definition files (only non-existing resources will be created).
  delete                    Delete resources that are no longer described by the resource definition files.
  diff                      Show changes required by the current resource definitions.
  get                       Display one or many specific resources.
  prepare                   Prepare the resource definition files for validation.
  update                    Create or update resources from the resource definition files
  validate                  Check whether the resources definitions meet all validation requirements.

SYSTEM MANAGEMENT COMMANDS:
  action                    List/execute actions.
  health                    Print or describe health indicators.

ADDITIONAL COMMANDS:
  api-extensions            Print the supported API extensions
  api-resources             Print the supported API resources
  config                    Sets or retrieves the configuration of this client
  generate-completion       Generate bash/zsh completion script for jikkou.
  help                      Display help information about the specified command.

(The output from your current Jikkou version may be different than the above example.)

Checking Jikkou Version

Run the jikkou --version to display your current installation version:

Jikkou version "0.32.0" 2023-11-28
JVM: 21.0.1 (GraalVM Community Substrate VM 21.0.1+12)

Shell Tab-completion

It is recommended to install the bash/zsh completion script jikkou_completion.

The completion script can be downloaded from the project Github repository:

wget https://raw.githubusercontent.com/streamthoughts/jikkou/main/jikkou_completion . jikkou_completion

or alternatively, you can run the following command to generate it.

source <(jikkou generate-completion)

2 - CLI Configuration

Configuration

To set up the configuration settings used by Jikkou CLI, you will need create a jikkou config file, which is created automatically when you create a configuration context using:

jikkou config set-context <context-name> [--config-file=<config-gile>] [--config-props=<config-value>]

By default, the configuration of jikkou is located under the path $HOME/.jikkou/config.

This jikkou config file defines all the contexts that can be used by jikkou CLI.

For example, below is the config file created during the Getting Started.

{
  "currentContext": "localhost",
  "localhost": {
    "configFile": null,
    "configProps": {
      "kafka.client.bootstrap.servers": "localhost:9092"
    }
  }
}

Most of the time, a context does not directly contain the configuration properties to be used, but rather points to a specific HOCON (Human-Optimized Config Object Notation) through the configFile property.

Then, the configProps allows you to override some of the property define by this file.

In addition, if no configuration file path is specified, Jikkou will lookup for an application.conf to those following locations:

• ./application.conf
• $HOME/.jikkou/application.conf

Finally, Jikkou always fallback to a reference.conf file that you can use as a template to define your own configuration.

reference.conf:

jikkou {

  extension.providers {
    # By default, disable all extensions
    default.enabled: true
    # Explicitly enabled/disable extensions
    #<provider_name>.enabled: <boolean>
    # schemaregistry.enabled = true
    # kafka.enabled = true
    # aiven.enabled = true
    # kafkaconnect.enabled = true
  }

  # Configure Jikkou Proxy Mode
  # proxy {
  #  url = "http://localhost:8080"
  # }

  # Kafka Extension
  kafka {
    # The default Kafka Client configuration
    client {
      bootstrap.servers = "localhost:9092"
      bootstrap.servers = ${?JIKKOU_DEFAULT_KAFKA_BOOTSTRAP_SERVERS}
    }
    brokers {
      # If 'True' 
      waitForEnabled = true
      waitForEnabled = ${?JIKKOU_KAFKA_BROKERS_WAIT_FOR_ENABLED}
      # The minimal number of brokers that should be alive for the CLI stops waiting.
      waitForMinAvailable = 1
      waitForMinAvailable = ${?JIKKOU_KAFKA_BROKERS_WAIT_FOR_MIN_AVAILABLE}
      # The amount of time to wait before verifying that brokers are available.
      waitForRetryBackoffMs = 1000
      waitForRetryBackoffMs = ${?JIKKOU_KAFKA_BROKERS_WAIT_FOR_RETRY_BACKOFF_MS}
      # Wait until brokers are available or this timeout is reached.
      waitForTimeoutMs = 60000
      waitForTimeoutMs = ${?JIKKOU_KAFKA_BROKERS_WAIT_FOR_TIMEOUT_MS}
    }
  }

  schemaRegistry {
    url = "http://localhost:8081"
    url = ${?JIKKOU_DEFAULT_SCHEMA_REGISTRY_URL}
  }

  # The default custom transformations to apply on any resources.
  transformations = []

  # The default custom validations to apply on any resources.
  validations = [
    {
      name = "topicMustHaveValidName"
      type = io.streamthoughts.jikkou.kafka.validation.TopicNameRegexValidation
      priority = 100
      config = {
        topicNameRegex = "[a-zA-Z0-9\\._\\-]+"
        topicNameRegex = ${?VALIDATION_DEFAULT_TOPIC_NAME_REGEX}
      }
    },
    {
      name = "topicMustHavePartitionsEqualsOrGreaterThanOne"
      type = io.streamthoughts.jikkou.kafka.validation.TopicMinNumPartitionsValidation
      priority = 100
      config = {
        topicMinNumPartitions = 1
        topicMinNumPartitions = ${?VALIDATION_DEFAULT_TOPIC_MIN_NUM_PARTITIONS}
      }
    },
    {
      name = "topicMustHaveReplicasEqualsOrGreaterThanOne"
      type = io.streamthoughts.jikkou.kafka.validation.TopicMinReplicationFactorValidation
      priority = 100
      config = {
        topicMinReplicationFactor = 1
        topicMinReplicationFactor = ${?VALIDATION_DEFAULT_TOPIC_MIN_REPLICATION_FACTOR}
      }
    }
  ]
  # The default custom reporters to report applied changes.
  reporters = [
    # Uncomment following lines to enable default kafka reporter
    #    {
    #     name = "default"
    #      type = io.streamthoughts.jikkou.kafka.reporter.KafkaChangeReporter
    #      config = {
    #        event.source = "jikkou/cli"
    #        kafka = {
    #          topic.creation.enabled = true
    #          topic.creation.defaultReplicationFactor = 1
    #          topic.name = "jikkou-resource-change-event"
    #          client = ${jikkou.kafka.client} {
    #            client.id = "jikkou-reporter-producer"
    #          }
    #        }
    #      }
    #    }
  ]
}

Listing Contexts

$ jikkou config get-contexts 
 
 NAME         
 localhost *
 development
 staging
 production

Verify Current Context

You can use jikkou config current-context command to show the context currently used by Jikkou CLI.

$ jikkou config current-context
Using context 'localhost'

 KEY          VALUE                                                                         
 ConfigFile   
 ConfigProps  {"kafka.client.bootstrap.servers": "localhost:9092"}  

Verify Current Configuration

You can use jikkou config view command to show the configuration currently used by Jikkou CLI.

3 - Automating Jikkou

3.1 - Automate Jikkou with GitHub Actions

Setup Jikkou

The streamthoughts/setup-jikkou action is a JavaScript action that sets up Jikkou in your GitHub Actions workflow by:

• Downloading a specific version of Jikkou CLI and adding it to the PATH.
• Configuring JIKKOU CLI with a custom configuration file.

After you’ve used the action, subsequent steps in the same job can run arbitrary Jikkou commands using the GitHub Actions run syntax. This allows most Jikkou commands to work exactly like they do on your local command line.

Usage

steps:
  - uses: streamthoughts/setup-jikkou@v1

A specific version of Jikkou CLI can be installed:

steps:
  - uses: streamthoughts/setup-jikkou@v0.1.0
    with:
      jikkou_version: 0.29.0

A custom configuration file can be specified:

steps:
  - uses: streamthoughts/setup-jikkou@v0.1.0
    with:
      jikkou_config: ./config/jikkouconfig.json

Inputs

This Action additionally supports the following inputs :