Reference

• 1: Jikkou CLI
• 1.1: Overview
• 1.2: Configuration
• 1.3: Commands
• 1.3.1: jikkou action
• 1.3.2: jikkou api-extensions
• 1.3.3: jikkou api-resources
• 1.3.4: jikkou apply
• 1.3.5: jikkou config
• 1.3.6: jikkou config current-context
• 1.3.7: jikkou config get-contexts
• 1.3.8: jikkou config set-context
• 1.3.9: jikkou config use-context
• 1.3.10: jikkou config view
• 1.3.11: jikkou create
• 1.3.12: jikkou delete
• 1.3.13: jikkou diff
• 1.3.14: jikkou get
• 1.3.15: jikkou health
• 1.3.16: jikkou patch
• 1.3.17: jikkou prepare
• 1.3.18: jikkou replace
• 1.3.19: jikkou server-info
• 1.3.20: jikkou update
• 1.3.21: jikkou validate
• 2: Jikkou API Server Documentation
• 2.1: Configurations
• 2.1.1: API Server
• 2.1.2: Authentication
• 2.1.2.1: Basic Auth
• 2.1.2.2: JWT
• 2.1.3: CLI Proxy Mode
• 2.2: Jikkou - API References
• 3: Extension Providers
• 3.1: Core Extensions
• 3.1.1: Resource Repositories
• 3.1.1.1: Github Resource Repository
• 3.1.1.2: Local Resource Repository
• 3.1.2: Resources
• 3.1.2.1: ConfigMap
• 3.1.2.2: ValidatingResourcePolicy
• 3.2: Apache Kafka
• 3.2.1: Configuration
• 3.2.2: Resources
• 3.2.2.1: Kafka Brokers
• 3.2.2.2: Kafka Consumer Groups
• 3.2.2.3: Kafka Topics
• 3.2.2.4: Kafka Users
• 3.2.2.5: Kafka Share Groups
• 3.2.2.6: Kafka Authorizations
• 3.2.2.7: Kafka Quotas
• 3.2.2.8: Kafka Table Records
• 3.2.3: Transformations
• 3.2.3.1: KafkaTopicMaxNumPartitions
• 3.2.3.2: KafkaTopicMaxRetentionMs
• 3.2.3.3: KafkaTopicMinInSyncReplicas
• 3.2.3.4: KafkaTopicMinReplicas
• 3.2.3.5: KafkaTopicMinRetentionMs
• 3.2.4: Validations
• 3.2.5: Annotations
• 3.2.6: Actions
• 3.2.6.1: KafkaConsumerGroupsResetOffsets
• 3.2.6.2: KafkaShareGroupsResetOffsets
• 3.2.7: Compatibility
• 3.3: Apache Kafka Connect
• 3.3.1: Configuration
• 3.3.2: Resources
• 3.3.2.1: KafkaConnectors
• 3.3.3: Validations
• 3.3.4: Annotations
• 3.3.5: Labels
• 3.3.6: Actions
• 3.3.6.1: KafkaConnectRestartConnectors
• 3.4: Schema Registry
• 3.4.1: Configuration
• 3.4.2: Resources
• 3.4.2.1: Schema Registry Subjects
• 3.4.3: Validations
• 3.4.4: Annotations
• 3.5: Aiven
• 3.5.1: Configuration
• 3.5.2: Resources
• 3.5.2.1: ACL for Aiven Apache Kafka®
• 3.5.2.2: Quotas for Aiven Apache Kafka®
• 3.5.2.3: ACL for Aiven Schema Registry
• 3.5.2.4: Subject for Aiven Schema Registry
• 3.5.3: Validations
• 3.5.4: Annotations
• 3.6: AWS
• 3.6.1: Configuration
• 3.6.2: Resources
• 3.6.2.1: Schema for AWS Glue Schema Registry
• 3.6.3: Validations
• 3.6.4: Annotations
• 3.7: Apache Iceberg
• 3.7.1: Configuration
• 3.7.2: Resources
• 3.7.2.1: Iceberg Namespace
• 3.7.2.2: Iceberg Table
• 3.7.2.3: Iceberg View
• 3.7.3: Annotations
• 3.8: Confluent Cloud
• 3.8.1: Configuration
• 3.8.2: Resources
• 3.8.2.1: Role Bindings for Confluent Cloud
• 3.8.3: Annotations

1 - Jikkou CLI

The Jikkou CLI (jikkou) is the primary interface for managing infrastructure resources. This reference covers:

• CLI Features — Global options, version check, and shell tab-completion
• CLI Configuration — Contexts, configuration files, and HOCON settings
• Commands — Complete reference for every command

To automate Jikkou in CI/CD, see the Automating guide.

1.1 - Overview

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 resources.

Find more information at: https://www.jikkou.io/.

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 resource changes required by the current resource definitions.
  get                       Display one or many specific resources.
  patch                     Execute all changes for the specified reconciliation mode.
  prepare                   Prepare the resource definition files for validation.
  replace                   Replace all resources.
  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.

See 'jikkou --help' for more information about a command.

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

For detailed options and usage examples for each command, see the Commands Reference.

Checking Jikkou Version

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

Jikkou version "0.37.0" 2026-02-17
JVM: 25.0.1 (GraalVM Community Substrate VM 25.0.1+8)

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 -O jikkou_completion

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

source <(jikkou generate-completion)

1.2 - 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-file>] [--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": {
      "provider.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 {

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

  # Configure Extension Providers
  extension {
  }

  # Core
  provider.core {
    enabled = true
  }
  # Apache Kafka Provider
  provider.kafka {
    enabled = true
    type = io.jikkou.kafka.KafkaExtensionProvider
    config = {
      # 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}
      }
    }
  }
  # Schema Registry Provider
  provider.schemaregistry {
    enabled = true
    type = io.jikkou.schema.registry.SchemaRegistryExtensionProvider
    config = {
      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.jikkou.kafka.validation.TopicNameRegexValidation
      priority = 100
      config = {
        topicNameRegex = "[a-zA-Z0-9\\._\\-]+"
        topicNameRegex = ${?VALIDATION_DEFAULT_TOPIC_NAME_REGEX}
      }
    },
    {
      name = "topicMustHavePartitionsEqualsOrGreaterThanOne"
      type = io.jikkou.kafka.validation.TopicMinNumPartitionsValidation
      priority = 100
      config = {
        topicMinNumPartitions = 1
        topicMinNumPartitions = ${?VALIDATION_DEFAULT_TOPIC_MIN_NUM_PARTITIONS}
      }
    },
    {
      name = "topicMustHaveReplicasEqualsOrGreaterThanOne"
      type = io.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.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"
    #          }
    #        }
    #      }
    #    }
  ]

  jinja {
    enableRecursiveMacroCalls = false
  }
}

Managing Contexts

For detailed usage of all configuration commands, see the Commands Reference:

• jikkou config set-context - Create or update a configuration context
• jikkou config get-contexts - List all configured contexts
• jikkou config current-context - Show the current context
• jikkou config use-context - Switch to a different context
• jikkou config view - Show the merged configuration

1.3 - Commands

You can also run jikkou <command> --help from the terminal to view built-in help for any command.

Global Options

The following options are available on all commands:

Core Commands

Commands for reconciling and inspecting resources against your target platform.

Reconciliation

These commands apply changes to your target platform based on resource definition files. Each command corresponds to a specific reconciliation mode.

Inspect & Validate

System Management Commands

Configuration & Discovery Commands

1.3.1 - jikkou action

List and execute actions.

Synopsis

The action command manages Jikkou actions. Actions are named operations that can be executed on the target platform. Like the get command, action uses dynamic subcommands based on the actions available from your configured providers.

Each action is registered as a subcommand under jikkou action, and has an execute subcommand to run it.

jikkou action <action-name> execute [flags]

Examples

# List all available actions (shown as subcommands in help)
jikkou action --help

# Execute an action
jikkou action KafkaConsumerGroupsResetOffsets execute --options topic=my-topic --options group=my-group

# Execute an action with YAML output
jikkou action KafkaConsumerGroupsResetOffsets execute -o YAML

# Execute an action targeting a specific provider
jikkou action KafkaConsumerGroupsResetOffsets execute --provider kafka-prod --options topic=my-topic

Options (execute subcommand)

Additional options may be available depending on the action. These are dynamically registered based on the action’s ApiOptionSpec definitions. Use jikkou api-extensions get <action-name> to view options for a specific action.

Options inherited from parent commands

SEE ALSO

• jikkou api-extensions - List and inspect available extensions
• jikkou get - Display resources from the platform

1.3.2 - jikkou api-extensions

Print the supported API extensions.

Synopsis

The api-extensions command lists and inspects the API extensions registered in Jikkou. Extensions include resource collectors, transformations, validations, actions, health indicators, and controllers.

This command has two subcommands:

• api-extensions list - List all extensions
• api-extensions get - Get details about a specific extension

Subcommands

jikkou api-extensions list

Print a summary table of all supported API extensions.

jikkou api-extensions list [flags]

Examples

# List all extensions
jikkou api-extensions list

# List extensions of a specific category
jikkou api-extensions list --category Transformation

# List extensions from a specific provider
jikkou api-extensions list --provider kafka

# List extensions that support a specific resource kind
jikkou api-extensions list --kind KafkaTopic

Options

jikkou api-extensions get

Print detailed information about a specific API extension, including its title, description, configuration options, and usage examples.

jikkou api-extensions get <name> [flags]

Examples

# Get details about an extension in WIDE format (default)
jikkou api-extensions get KafkaTopicMaxRetentionMs

# Get details in JSON format
jikkou api-extensions get KafkaTopicMaxRetentionMs -o JSON

# Get details in YAML format
jikkou api-extensions get KafkaTopicMaxRetentionMs -o YAML

Options

Options inherited from parent commands

SEE ALSO

• jikkou api-resources - List available resource types
• jikkou get - Display resources of a given type

1.3.3 - jikkou api-resources

Print the supported API resources.

Synopsis

List the API resources supported by the Jikkou CLI or Jikkou API Server (in proxy mode). This command shows the resource name, short names, API version, kind, and supported verbs for each resource type.

Use this command to discover which resource types are available with your current configuration and providers.

jikkou api-resources [flags]

Examples

# List all available API resources
jikkou api-resources

# List resources for a specific API group
jikkou api-resources --api-group kafka.jikkou.io

# List resources that support specific verbs
jikkou api-resources --verbs LIST,GET

# List resources that support CREATE
jikkou api-resources --verbs CREATE

# Combine filters
jikkou api-resources --api-group kafka.jikkou.io --verbs LIST

Sample output

NAME               SHORTNAMES   APIVERSION               KIND                  VERBS
kafkatopics        kt           kafka.jikkou.io/v1beta2  KafkaTopic            CREATE, DELETE, GET, LIST, UPDATE
kafkaconsumergroups              kafka.jikkou.io/v1beta2  KafkaConsumerGroup    DELETE, GET, LIST

Options

Options inherited from parent commands

SEE ALSO

• jikkou api-extensions - List and inspect available extensions
• jikkou get - Display resources of a given type

1.3.4 - jikkou apply

Update the resources aand as described by the resource definition files.

Synopsis

Reconciles the target platform so that the resources match the resource definition files passed as arguments. This command uses the FULL reconciliation mode, meaning it will create, update, and delete resources as needed to match the desired state defined in your resource files.

jikkou apply [flags]

Examples

# Apply resources defined in a YAML file
jikkou apply -f my-resources.yaml

# Apply resources from a directory
jikkou apply -f ./resources/

# Apply resources with dry-run to preview changes
jikkou apply -f my-resources.yaml --dry-run

# Apply resources with specific selector
jikkou apply -f my-resources.yaml --selector 'metadata.name IN (my-topic)'

# Apply resources with template values
jikkou apply -f my-resources.yaml --values-files values.yaml

# Apply with inline template variable
jikkou apply -f my-resources.yaml -v topicName=my-topic

# Apply with custom labels
jikkou apply -f my-resources.yaml -l environment=production

# Apply with controller options
jikkou apply -f my-resources.yaml --options delete-orphans=true

# Apply targeting a specific provider
jikkou apply -f my-resources.yaml --provider kafka-prod

# Apply with JSON output format
jikkou apply -f my-resources.yaml -o JSON --pretty

Options

Options inherited from parent commands

SEE ALSO

• jikkou create - Create resources (CREATE mode only)
• jikkou update - Create or update resources (UPDATE mode only)
• jikkou delete - Delete resources (DELETE mode only)
• jikkou diff - Show changes without applying
• jikkou validate - Validate resource definitions

1.3.5 - jikkou config

Sets or retrieves the configuration of this client.

Synopsis

The config command manages Jikkou CLI configuration contexts. A context defines the configuration settings (config file path, inline properties, provider bindings) used when running Jikkou commands.

Configuration is stored in the Jikkou config file, located by default at $HOME/.jikkou/config.

Subcommands

Options inherited from parent commands

SEE ALSO

• Configuration - Learn how to configure Jikkou CLI

1.3.6 - jikkou config current-context

Display the current context.

Synopsis

Displays the current context used by Jikkou CLI, including the configuration file path and inline configuration properties associated with it.

jikkou config current-context

Examples

# Show the current context
$ jikkou config current-context
Using context 'localhost'

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

Options

This command has no specific options.

Options inherited from parent commands

SEE ALSO

• jikkou config get-contexts - List all contexts
• jikkou config use-context - Switch to a different context
• jikkou config view - Show the merged configuration
• jikkou config - Config command overview

1.3.7 - jikkou config get-contexts

List all configured contexts.

Synopsis

Get all contexts defined in the Jikkou config file. The current context is marked with an asterisk (*).

jikkou config get-contexts

Examples

# List all contexts
$ jikkou config get-contexts

 NAME
 localhost *
 development
 staging
 production

Options

This command has no specific options.

Options inherited from parent commands

SEE ALSO

• jikkou config current-context - Show the current context details
• jikkou config use-context - Switch to a context
• jikkou config set-context - Create or update a context
• jikkou config - Config command overview

1.3.8 - jikkou config set-context

Configure a context with the provided arguments.

Synopsis

Configures the specified context with the provided arguments. A context stores a reference to a configuration file and/or inline configuration properties. If the context already exists, it will be updated.

After setting a context, use jikkou config use-context to switch to it.

jikkou config set-context <context-name> [flags]

Examples

# Create a context with inline Kafka bootstrap server
jikkou config set-context localhost \
  --config-props=provider.kafka.config.client.bootstrap.servers=localhost:9092

# Create a context pointing to a configuration file
jikkou config set-context production --config-file=/path/to/production.conf

# Create a context with a properties file
jikkou config set-context staging --config-props-file=/path/to/staging.properties

# Create a context with provider-scoped properties
jikkou config set-context dev \
  --provider kafka \
  --config-props=client.bootstrap.servers=kafka-dev:9092

# Create a context with a config prefix
jikkou config set-context dev \
  --config-prefix=provider.kafka.config \
  --config-props=client.bootstrap.servers=kafka-dev:9092

Options

Arguments

Options inherited from parent commands

SEE ALSO

• jikkou config use-context - Switch to a context
• jikkou config get-contexts - List all contexts
• jikkou config - Config command overview

1.3.9 - jikkou config use-context

Switch to a specified context.

Synopsis

Configures Jikkou to use the specified context. All subsequent commands will use the configuration associated with this context.

jikkou config use-context <context-name>

Examples

# Switch to the production context
$ jikkou config use-context production
Using context 'production'

# If already using the specified context
$ jikkou config use-context production
Already using context production

Arguments

Options

This command has no specific options.

Options inherited from parent commands

SEE ALSO

• jikkou config get-contexts - List all available contexts
• jikkou config current-context - Display the current context
• jikkou config set-context - Create or update a context
• jikkou config - Config command overview

1.3.10 - jikkou config view

Show merged configuration settings.

Synopsis

Show the merged Jikkou configuration settings for the current context (or a named context). The configuration is rendered in HOCON format, showing all resolved values from the config file, inline properties, and defaults.

Use --debug to see the origin of each setting, or --comments to include human-written comments from the configuration files.

jikkou config view [flags]

Examples

# View the current configuration
jikkou config view

# View configuration for a specific context
jikkou config view --name production

# View configuration with origin comments (useful for debugging)
jikkou config view --debug

# View configuration with human-written comments
jikkou config view --comments

Options

Options inherited from parent commands

SEE ALSO

• jikkou config current-context - Display the current context
• jikkou config set-context - Create or update a context
• jikkou config - Config command overview

1.3.11 - jikkou create

Create resources from the resource definition files (only non-existing resources will be created).

Synopsis

Reconcile the target platform by creating all non-existing resources that are described by the resource definition files passed as arguments. This command uses the CREATE reconciliation mode, meaning only new resources will be created. Existing resources will not be updated or deleted.

jikkou create [flags]

Examples

# Create resources defined in a YAML file
jikkou create -f my-resources.yaml

# Preview what would be created
jikkou create -f my-resources.yaml --dry-run

# Create resources from a directory
jikkou create -f ./resources/

# Create resources with template values
jikkou create -f my-resources.yaml --values-files values.yaml

# Create resources targeting a specific provider
jikkou create -f my-resources.yaml --provider kafka-dev

Options

Options inherited from parent commands

SEE ALSO

• jikkou apply - Apply all changes (FULL mode)
• jikkou update - Create or update resources (UPDATE mode)
• jikkou delete - Delete resources (DELETE mode)
• jikkou diff - Show changes without applying

1.3.12 - jikkou delete

Delete resources that are no longer described by the resource definition files.

Synopsis

Reconcile the target platform by deleting all existing resources that are no longer described by the resource definition files passed as arguments. This command uses the DELETE reconciliation mode, meaning only deletions will be performed. No resources will be created or updated.

jikkou delete [flags]

Examples

# Delete resources no longer defined in a YAML file
jikkou delete -f my-resources.yaml

# Preview what would be deleted
jikkou delete -f my-resources.yaml --dry-run

# Delete resources from a directory
jikkou delete -f ./resources/

# Delete with selector to target specific resources
jikkou delete -f my-resources.yaml -s 'metadata.name IN (old-topic)'

# Delete resources targeting a specific provider
jikkou delete -f my-resources.yaml --provider kafka-dev

Options

Options inherited from parent commands

SEE ALSO

• jikkou apply - Apply all changes (FULL mode)
• jikkou create - Create resources only (CREATE mode)
• jikkou update - Create or update resources (UPDATE mode)
• jikkou diff - Show changes without applying

1.3.13 - jikkou diff

Show resource changes required by the current resource definitions.

Synopsis

Generates a speculative reconciliation plan, showing the resource changes Jikkou would apply to reconcile the resource definitions. This command does not actually perform the reconciliation actions.

Use diff to preview what changes would be made before running apply, create, update, or delete.

jikkou diff [flags]

Examples

# Show changes required by a resource definition file
jikkou diff -f my-resources.yaml

# Show only resources that would be created
jikkou diff -f my-resources.yaml --filter-resource-op CREATE

# Show only resources that would be created or deleted
jikkou diff -f my-resources.yaml --filter-resource-op CREATE,DELETE

# Filter changes to show only update operations
jikkou diff -f my-resources.yaml --filter-change-op UPDATE

# Output as a resource list
jikkou diff -f my-resources.yaml --list

# Output in JSON format
jikkou diff -f my-resources.yaml -o JSON

# Diff with a specific provider
jikkou diff -f my-resources.yaml --provider kafka-prod

# Diff with selector
jikkou diff -f my-resources.yaml -s 'metadata.name MATCHES (my-topic-.*)'

Options

Options inherited from parent commands

SEE ALSO

• jikkou apply - Apply all changes
• jikkou validate - Validate resource definitions
• jikkou prepare - Prepare resources for validation

1.3.14 - jikkou get

Display one or many specific resources.

Synopsis

Display one or many resources of a given type from the target platform. The get command groups resources under their provider (e.g. kafka, schemaregistry, aiven), so invocations follow the form jikkou get <provider> <kind>. Use jikkou api-providers list to discover the available providers and jikkou api-resources to discover the available resource types.

When a resource name is specified via --name, it retrieves that specific resource. Otherwise, it lists all resources of the given type.

jikkou get <provider> <resource-type> [flags]

Resource naming. Under a provider, each resource is exposed by its provider-local name when one is declared (e.g. topics under kafka, subjects under schemaregistry). The full plural name (e.g. kafkatopics, schemaregistrysubjects) and any short names (e.g. kt, sr) remain valid aliases inside the provider scope.

Backward compatibility. The flat form jikkou get <resource-type> is still supported but prints a deprecation notice on stderr and will be removed in a future release. Prefer the qualified form jikkou get <provider> <resource-type>.

Examples

# List all Kafka topics (canonical form)
jikkou get kafka topics

# Same, using the plural name as alias
jikkou get kafka kafkatopics

# Same, using the short name as alias
jikkou get kafka kt

# Get a specific Kafka topic by name
jikkou get kafka topics --name my-topic

# List resources with a selector
jikkou get kafka topics -s 'metadata.name MATCHES (my-.*)'

# List resources with JSON output
jikkou get kafka topics -o JSON

# List resources as a ResourceListObject
jikkou get kafka topics --list

# List resources with custom options
jikkou get kafka topics --options describe-default-configs=true

# List resources targeting a specific provider instance
jikkou get kafka topics --provider kafka-prod

# List schema registry subjects
jikkou get schemaregistry subjects

# Discover available resource types
jikkou api-resources --verbs LIST,GET

Options

Additional options may be available depending on the resource type. These are dynamically registered based on the provider’s ApiOptionSpec definitions. Use jikkou api-extensions get <extension-name> to view options for a specific resource collector.

Options inherited from parent commands

SEE ALSO

• jikkou api-resources - List available resource types
• jikkou api-extensions - List and inspect extensions
• jikkou diff - Show changes between desired and actual state

1.3.15 - jikkou health

Print or describe health indicators.

Synopsis

The health command provides information about the health of target environments. It has two subcommands:

• health get - Retrieve health status for one or all indicators
• health get-indicators - List all available health indicators

Subcommands

jikkou health get

Get health information for a specific indicator or all indicators.

jikkou health get <indicator|all> [flags]

Examples

# Get health for all indicators
jikkou health get all

# Get health for a specific indicator
jikkou health get kafka

# Get health with a custom timeout
jikkou health get all --timeout-ms 5000

# Get health in JSON format
jikkou health get all -o JSON

# Get health targeting a specific provider
jikkou health get kafka --provider kafka-prod

Options

The command exits with code 0 if the health status is UP, or a non-zero code otherwise.

jikkou health get-indicators

List all available health indicators. This command takes no options and displays the name and description of each registered health indicator.

jikkou health get-indicators

Examples

# List all health indicators
jikkou health get-indicators

Options

This subcommand has no specific options.

Options inherited from parent commands

SEE ALSO

• jikkou api-extensions - List and inspect extensions
• jikkou server-info - Display server information (proxy mode)

1.3.16 - jikkou patch

Execute all changes for the specified reconciliation mode.

Synopsis

Reconcile resources by applying all the changes as defined in the resource descriptor files passed through the arguments. Unlike the other reconciliation commands (apply, create, update, delete), patch requires you to explicitly specify the reconciliation mode using the --mode flag.

The patch command applies changes to existing resources on the platform by computing a diff between the current and desired states, then executing only the operations allowed by the selected mode.

jikkou patch --mode <mode> [flags]

Examples

# Patch resources using FULL reconciliation mode
jikkou patch --mode FULL -f my-resources.yaml

# Patch resources - create only
jikkou patch --mode CREATE -f my-resources.yaml

# Patch resources - update only
jikkou patch --mode UPDATE -f my-resources.yaml

# Preview patches without applying
jikkou patch --mode FULL -f my-resources.yaml --dry-run

# Patch with a specific provider
jikkou patch --mode UPDATE -f my-resources.yaml --provider kafka-prod

Options

Options inherited from parent commands

SEE ALSO

• jikkou apply - Apply all changes (FULL mode)
• jikkou replace - Replace resources by deleting and recreating
• jikkou diff - Show changes without applying

1.3.17 - jikkou prepare

Prepare the resource definition files for validation.

Synopsis

Prepare the resource definition files specified through the command line arguments for validation. This command applies all configured transformations to the resource definitions and outputs the result, without running validation rules or performing reconciliation.

Use prepare to inspect how your resources look after template rendering and transformations, before validation and reconciliation happen.

jikkou prepare [flags]

Examples

# Prepare resources from a YAML file
jikkou prepare -f my-resources.yaml

# Prepare resources from a directory
jikkou prepare -f ./resources/

# Prepare with template values
jikkou prepare -f my-resources.yaml --values-files values.yaml

# Prepare with JSON output
jikkou prepare -f my-resources.yaml -o JSON

# Prepare with selector
jikkou prepare -f my-resources.yaml -s 'metadata.name IN (my-topic)'

# Prepare targeting a specific provider
jikkou prepare -f my-resources.yaml --provider kafka-prod

Options

Options inherited from parent commands

SEE ALSO

• jikkou validate - Validate prepared resources
• jikkou apply - Apply changes
• jikkou diff - Show changes without applying

1.3.18 - jikkou replace

Replace all resources.

Synopsis

Replaces resources by deleting and (re)creating all the resources as defined in the resource descriptor files passed through the arguments. Unlike apply, which performs incremental updates, replace performs a full replacement of resources: existing resources are deleted first and then recreated from scratch.

Use replace when you need to ensure resources exactly match the desired state without any leftover configuration from previous versions.

jikkou replace [flags]

Examples

# Replace resources defined in a YAML file
jikkou replace -f my-resources.yaml

# Preview what would be replaced
jikkou replace -f my-resources.yaml --dry-run

# Replace resources from a directory
jikkou replace -f ./resources/

# Replace resources targeting a specific provider
jikkou replace -f my-resources.yaml --provider kafka-prod

# Replace with JSON output
jikkou replace -f my-resources.yaml -o JSON --pretty

Options

Options inherited from parent commands

SEE ALSO

• jikkou apply - Apply all changes (FULL mode)
• jikkou patch - Patch resources with a specified mode
• jikkou diff - Show changes without applying

1.3.19 - jikkou server-info

Display Jikkou API server information.

Synopsis

Print information about the Jikkou API server. This command is only available when Jikkou is configured in proxy mode (i.e., when jikkou.proxy.url is set in your configuration).

jikkou server-info [flags]

Examples

# Get server information in YAML format (default)
jikkou server-info

# Get server information in JSON format
jikkou server-info -o JSON

Options

Options inherited from parent commands

SEE ALSO

• jikkou health - Check health of target environments
• Configuration - Learn how to configure proxy mode

1.3.20 - jikkou update

Create or update resources from the resource definition files.

Synopsis

Reconcile the target platform by creating or updating resources that are described by the resource definition files passed as arguments. This command uses the UPDATE reconciliation mode, meaning new resources will be created and existing resources will be updated. Resources that exist on the platform but are not described in the resource files will not be deleted.

jikkou update [flags]

Examples

# Update resources defined in a YAML file
jikkou update -f my-resources.yaml

# Preview what would be created or updated
jikkou update -f my-resources.yaml --dry-run

# Update resources from a directory
jikkou update -f ./resources/

# Update resources with selector to filter specific resources
jikkou update -f my-resources.yaml -s 'metadata.name MATCHES (my-topic-.*)'

# Update resources targeting a specific provider
jikkou update -f my-resources.yaml --provider kafka-prod

Options

Options inherited from parent commands

SEE ALSO

• jikkou apply - Apply all changes (FULL mode)
• jikkou create - Create resources only (CREATE mode)
• jikkou delete - Delete resources (DELETE mode)
• jikkou diff - Show changes without applying

1.3.21 - jikkou validate

Check whether the resources definitions meet all validation requirements.

Synopsis

Validate the resource definition files specified through the command line arguments.

Validate runs all the user-defined validation requirements after performing any relevant resource transformations. Validation rules are applied only to resources matching the selectors passed through the command line arguments.

If validation passes, the command outputs the validated resources. If validation fails, the command prints the validation errors and exits with a non-zero status code.

jikkou validate [flags]

Examples

# Validate resources defined in a YAML file
jikkou validate -f my-resources.yaml

# Validate resources from a directory
jikkou validate -f ./resources/

# Validate with a selector to filter specific resources
jikkou validate -f my-resources.yaml -s 'metadata.name MATCHES (my-topic-.*)'

# Validate with template values
jikkou validate -f my-resources.yaml --values-files values.yaml

# Validate with JSON output
jikkou validate -f my-resources.yaml -o JSON

# Validate targeting a specific provider
jikkou validate -f my-resources.yaml --provider kafka-prod

Options

Options inherited from parent commands

SEE ALSO

• jikkou prepare - Prepare resources for validation
• jikkou apply - Apply changes after validation
• jikkou diff - Show changes without applying

2 - Jikkou API Server Documentation

Jikkou API Server provides a REST interface to any platform supported by Jikkou, making it even easier to manage, automate and visualise all your data platform assets.

Jikkou CLI can be used in combination with Jikkou API Server by configuring it in proxy mode. In this mode, the CLI no longer connects directly to your various platforms, but forwards all operations to the API server. This deployment method allows you to enhance the overall security of the platforms managed through Jikkou.

2.1 - Configurations

Jikkou API Server is built with Micronaut Framework.

The default configuration file is located in the installation directory of you server under the path /etc/application.yaml.

You can either modify this configuration file directly or create a new one. Then, your configuration file path can be targeted through the MICRONAUT_CONFIG_FILES environment variable.

A YAML Configuration file example can be found here: application.yaml

2.1.1 - API Server

Running Server on a Specific Port

By default, the server runs on port 28082. However, you can set the server to run on a specific port:

# ./etc/application.yaml
micronaut:
  server:
    port: 80  # Port used to access APIs

endpoints:
  all:
    port: 80  # Port used to access Health endpoints

Enabling Specific Extension Providers

By default, the server is configured to run only with the core and kafka extension providers. However, you can enable (or disable) additional providers:

jikkou:
  # The providers
  provider:
    # Core
    core:
      enabled: true
      type: io.jikkou.core.CoreExtensionProvider
      
    # Default configuration for Apache Kafka
    kafka:
      enabled: true
      type: io.jikkou.kafka.KafkaExtensionProvider
      config:
        client:
          bootstrap.servers: localhost:9092
          
    # Default configuration for Schema Registry
    schemaregistry:
      enabled: true
      type: io.jikkou.schema.registry.SchemaRegistryExtensionProvider
      config:
        url: http://localhost:8081
        
    # Default configuration for Kafka Connect
    kafkaconnect:
      enabled: true
      type: io.jikkou.kafka.connect.KafkaConnectExtensionProvider
      config:
        clusters:
          - name: localhost
            url: http://localhost:8083

2.1.2 - Authentication

Enable Security

To enable secure access to the API Server:

Configuration File

Update the configuration file (i.e., application.yaml) of the server with:

micronaut:
  security:
    enabled: true

Environment Variable

As an alternative, you can set the following environment variable MICRONAUT_SECUTIRY_ENABLED=true.

Unauthorized Access

When accessing a secured path, the server will return the following response if access is not authorized:

{
  "message": "Unauthorized",
  "errors": [
    {
      "status": 401,
      "error_code": "authentication_user_unauthorized",
      "message": "Unauthorized"
    }
  ]
}

2.1.2.1 - Basic Auth

Jikkou API Server can be secured using a Basic HTTP Authentication Scheme.

RFC7617 defines the “Basic” Hypertext Transfer Protocol (HTTP) authentication scheme, which transmits credentials as user-id/password pairs, encoded using Base64.

Basic Authentication should be used over a secured connection using HTTPS.

Configure Basic HTTP Authentication

Step1: Enable security

Add the following configuration to your server configuration.

# ./etc/application.yaml
micronaut:
  security:
    enabled: true

Step2: Configure the list of users

The list of username/password authorized to connect to the API server can be configured as follows:

# ./etc/application.yaml
jikkou:
  security:
    basic-auth:
      - username: "admin"
        password: "{noop}password"

For production environment, password must not be configured in plaintext. Password can be passed encoded in bcrypt, scrypt, argon2, and sha256.

Example

echo -n password | sha256sum
5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8

# ./etc/application.yaml
jikkou:
  security:
    basic-auth:
      - username: "admin"
        password: "{sha256}5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"

Step3: Validate authentication

Encode credentials

echo -n "admin:password" | base64 
YWRtaW46cGFzc3dvcmQ=

Send request

curl -IX GET http://localhost:28082/apis/kafka.jikkou.io/v1beta2/kafkabrokers \
-H "Accept: application/json" \
-H "Authorization: Basic YWRtaW46cGFzc3dvcmQ"

HTTP/1.1 200 OK
Content-Type: application/hal+json
content-length: 576

2.1.2.2 - JWT

Jikkou API Server can be secured using JWT (JSON Web Token) Authentication.

Configure JWT

Step1: Set JWT signature secret

Add the following configuration to your server configuration.

# ./etc/application.yaml
micronaut:
  security:
    enabled: true
    authentication: bearer <1>
    token:
      enabled: true
      jwt:
        signatures:
          secret:
            generator:
              secret: ${JWT_GENERATOR_SIGNATURE_SECRET:pleaseChangeThisSecretForANewOne} <2>

• <1> Set authentication to bearer to receive a JSON response from the login endpoint.
• <2> Change this to your own secret and keep it safe (do not store this in your VCS).

Step2: Generate a Token

Generate a valid JSON Web Token on https://jwt.io/ using your secret.

Example with pleaseChangeThisSecretForANewOne as signature secret.

TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.6cD3MnZmX2xyEAWyh-GgGD11TX8SmvmHVLknuAIJ8yE

Step3: Validate authentication

$ curl -I -X GET http://localhost:28082/apis/kafka.jikkou.io/v1beta2/kafkabrokers \
-H "Accept: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.6cD3MnZmX2xyEAWyh-GgGD11TX8SmvmHVLknuAIJ8yE"

HTTP/1.1 200 OK
Content-Type: application/hal+json
content-length: 576

2.1.3 - CLI Proxy Mode

Configuration

Step 1: Enable Proxy Mode

To enable proxy mode so that the CLI communicates directly with your API Server, add the following parameters to your configuration:

jikkou {
  # Proxy Configuration
  proxy {
    # Specify whether proxy mode is enabled (default: false).
    enabled = true
    # URL of the API Server
    url = "http://localhost:28082"
    # Specifcy whether HTTP request debugging should be enabled (default: false)
    debugging = false
    # The connect timeout in millisecond (if not configured used ` default-timeout` ).
    connect-timeout = 10000
    # The read timeout in millisecond (if not configured used ` default-timeout` ).
    read-timeout = 10000
    # The write timeout in millisecond (if not configured used ` default-timeout` ).
    write-timeout = 10000
    # The default timeout (i.e., for read/connect) in millisecond (default: 10000)
    default-timeout = 10000
    # Security settings to authenticate to the API Server.
    security = {
      # For Token based Authentication.
      # access-token = ""
      # For Username/Password Basic-Authentication.
      # basic-auth = {
      #   username = ""
      #   password = ""
      # }
    }
  }
}

Step 2: Check connection

When enabling Proxy Mode, Jikkou CLI provides the additional command server-info. You can use it to verify the connectivity with teh server.

$ jikkou server-info -o JSON | jq

{
  "version": "0.31.0",
  "build_time": "2023-11-15T10:35:22+0100",
  "commit_id": "f3384d38e606fb32599c175895d0cbef28258540"
}

2.2 - Jikkou - API References

3 - Extension Providers

3.1 - Core Extensions

More information:

3.1.1 - Resource Repositories

Core Repositories

More information:

3.1.1.1 - Github Resource Repository

Overview

The GithubResourceRepository can be used to load resources from a public or private GitHub repository.

Configuration

jikkou {
  repositories = [
    {
      # Name of your local repositories  
      name = "<string>"
      # The fully qualified class name (FQCN) of the repository
      type = io.jikkou.core.repository.GithubResourceRepository
      config {
        # Specify the GitHub repository in the format 'owner/repo'
        repository = "<string>"
  
        # Specify the branch or ref to load resources from
        branch = main
  
        # Specify the paths/directories in the repository containing the resource definitions
        paths = []    # Default: **/*.{yaml,yml}
  
        # Specify the pattern used to match YAML file paths.
        # Pattern should be passed in the form of 'syntax:pattern'. The "glob" and "regex" syntaxes are supported (e.g.: **/*.{yaml,yml}).
        # If no syntax is specified the 'glob' syntax is used.
        file-pattern = "**/*.{yaml,yml}"
        
        # Specify the locations of the values-files containing the variables to pass into the template engine built-in object 'Values'.
        values-files = []
        
        # Specify the pattern used to match YAML file paths when one or multiple directories are given through the `values-files` property.
        # Pattern should be passed in the form of 'syntax:pattern'. The "glob" and "regex" syntaxes are supported (e.g.: **/*.{yaml,yml}).
        # If no syntax is specified the 'glob' syntax is used.
        values-file-name = "<string>" # Default: **/*.{yaml,yml}
        
        # The labels to be added to all resources loaded from the repository
        labels {
          <label_key> = <label_value>
        }
      }
    }
  ]
}

3.1.1.2 - Local Resource Repository

Overview

The LocalResourceRepository can be used to load resources from local files or directories.

Configuration

jikkou {
  repositories = [
    {
      # Name of your local repositories  
      name = "<string>"
      # The fully qualified class name (FQCN) of the repository
      type = io.jikkou.core.repository.LocalResourceRepository
      config {
        # Specify the locations containing the definitions for resources in a YAML file, a directory.
        files = []
        
        # Specify the pattern used to match YAML file paths when one or multiple directories are given through the `files` property.
        # Pattern should be passed in the form of 'syntax:pattern'. The "glob" and "regex" syntaxes are supported (e.g.: **/*.{yaml,yml}).
        # If no syntax is specified the 'glob' syntax is used.
        file-name = "<string>"    # Default: **/*.{yaml,yml}
        
        # Specify the locations of the values-files containing the variables to pass into the template engine built-in object 'Values'.
        values-files = []
        
        # Specify the pattern used to match YAML file paths when one or multiple directories are given through the `values-files` property.
        # Pattern should be passed in the form of 'syntax:pattern'. The "glob" and "regex" syntaxes are supported (e.g.: **/*.{yaml,yml}).
        # If no syntax is specified the 'glob' syntax is used.
        values-file-name = "<string>" # Default: **/*.{yaml,yml}
        
        # The labels to add to all resources loaded from the repository
        labels {
          <label_key> = <label_value>
        }
      }
    }
  ]
}

3.1.2 - Resources

Core Resources

More information:

3.1.2.1 - ConfigMap

You can use a ConfigMap to define reusable data in the form of key/value pairs that can then be referenced and used by other resources.

Specification

---
apiVersion: "core.jikkou.io/v1beta2"
kind: ConfigMap
metadata:
  name: '<CONFIG-MAP-NAME>'   # Name of the ConfigMap (required)
data:                         # Map of key-value pairs (required)
  <KEY_1>: "<VALUE_1>" 

Example

For example, the below ConfigMap show how to define default config properties namedcKafkaTopicConfig that can then reference and used to define multiple KafkaTopic. resources.

---
apiVersion: "core.jikkou.io/v1beta2"
kind: ConfigMap
metadata:
name: 'KafkaTopicConfig'
data:
  cleanup.policy: 'delete'
  min.insync.replicas: 2
  retention.ms: 86400000 # (1 day)

3.1.2.2 - ValidatingResourcePolicy

The ValidatingResourcePolicy resource is used to define validation rules applied to resources or resource changes before they are applied by Jikkou.
It allows enforcing organizational policies, validating constraints, or filtering out undesired operations.

Each policy can select one or more resource kinds and define rules expressed in Google CEL (Common Expression Language).
Rules can either fail the execution or filter the invalid resources, depending on the configured failurePolicy.

Specification

apiVersion: core.jikkou.io/v1
kind: ValidatingResourcePolicy
metadata:
  name: <string> # Required. Unique policy name.
spec:
  failurePolicy: <string> # Required. One of: FAIL | FILTER
  selector:
    matchingStrategy: <string> # Optional. One of: ALL | ANY (default: ALL)
    matchResources:
      - apiVersion: <string> # Optional. API version to match (e.g., core.jikkou.io/v1)
        kind: <string>       # Required. Resource kind (e.g., KafkaTopic)
    matchLabels:
      - key: <string>       # Label key to match
        operator: <string>  # One of: In | NotIn | Exists | DoesNotExist
        values: [<string>]  # Optional list of values
    matchExpressions:
      - <string> # CEL expression
  rules:
    - name: <string> # Required. Rule identifier.
      expression: <string> # Required. A CEL expression evaluated against the resource.
      message: <string> # Optional. Static message returned when the rule fails.
      messageExpression: <string> # Optional. CEL expression to generate a dynamic error message.

Fields

Resource Selection

Policies define which resources they apply to using a selector.
A selector can combine multiple strategies to target resources based on:

• Resource metadata (kind, apiVersion).
• Labels (with operators like In, NotIn, Exists, DoesNotExist).
• CEL expressions (arbitrary conditions on resource content).

Matching Strategy

Default: ALL

matchResources

Selects resources by API version and/or kind.

matchResources:
  - apiVersion: core.jikkou.io/v1
    kind: KafkaTopic

• apiVersion → Optional. Restricts matching to a specific API group/version.
• kind → Required. Matches the resource kind (e.g. KafkaTopic, KafkaTopicChange).

matchLabels

Selects resources based on their metadata labels using operators.

matchLabels:
  - key: environment
    operator: In
    values: ["prod", "staging"]
  - key: team
    operator: NotIn
    values: ["test"]
  - key: critical
    operator: Exists

Supported operators:

matchExpressions

Selects resources using CEL expressions for maximum flexibility.

matchExpressions:
  - "resource.metadata.name.startsWith('topic-')"
  - "resource.spec.partitions > 10"

Examples:

• Match resources with names starting with topic-.
• Match topics with more than 10 partitions.

Examples

Example 1: Filtering DELETE operations on KafkaTopic resources

apiVersion: core.jikkou.io/v1
kind: ValidatingResourcePolicy
metadata:
  name: KafkaTopicPolicy
spec:
  failurePolicy: FILTER
  selector:
    matchResources:
      - kind: KafkaTopicChange
  rules:
    - name: FilterDeleteOperation
      expression: "size(resource.spec.changes) > 0 && resource.spec.op == 'DELETE'"
      messageExpression: "'Operation ' + resource.spec.op + ' on topics is not authorized'"

This policy prevents delete operations on Kafka topics from being executed by filtering them out.

Example 2: Validating partitions count for KafkaTopic

apiVersion: core.jikkou.io/v1
kind: ValidatingResourcePolicy
metadata:
  name: KafkaTopicPolicy
spec:
  failurePolicy: FAIL
  selector:
    matchResources:
      - kind: KafkaTopic
  rules:
    - name: MaxTopicPartitions
      expression: "resource.spec.partitions >= 50"
      messageExpression: "'Topic partition MUST be inferior to 50, but was: ' + string(resource.spec.partitions)"

    - name: MinTopicPartitions
      expression: "resource.spec.partitions < 3"
      message: "Topic must have at-least 3 partitions"

This policy enforces a minimum of 3 partitions and a maximum of 49 partitions for Kafka topics.

Example 3: Match only KafkaTopic in prod environment

selector:
  matchingStrategy: ALL
  matchResources:
    - kind: KafkaTopic
  matchLabels:
    - key: environment
      operator: In
      values: ["prod"]

Example 4: Match any KafkaTopic OR resources with label critical=true

selector:
  matchingStrategy: ANY
  matchResources:
    - kind: KafkaTopic
  matchLabels:
    - key: critical
      operator: In
      values: ["true"]

Example 5: Match using CEL expression

selector:
  matchExpressions:
    - "resource.spec.replicationFactor < 3"

Use cases

• Preventing destructive operations (e.g., deleting topics, removing configs).
• Enforcing resource limits (e.g., partition count, replication factor).
• Ensuring naming conventions or metadata compliance.
• Dynamically generating error messages with contextual information.

3.2 - Apache Kafka

More information:

3.2.1 - Configuration

Configuration

The Apache Kafka extension is built on top of the Kafka Admin Client. You can configure the properties to be passed to kafka client through the Jikkou client configuration property jikkou.provider.kafka.

Example:

jikkou {
  provider.kafka {
    enabled = true
    type = io.jikkou.kafka.KafkaExtensionProvider
    config = {
      client {
        bootstrap.servers = "localhost:9092"
        security.protocol = "SSL"
        ssl.keystore.location = "/tmp/client.keystore.p12"
        ssl.keystore.password = "password"
        ssl.keystore.type = "PKCS12"
        ssl.truststore.location = "/tmp/client.truststore.jks"
        ssl.truststore.password = "password"
        ssl.key.password = "password"
      }
    }
  }
}

In addition, the extension support configuration settings to wait for at least a minimal number of brokers before processing.

jikkou {
  provider.kafka {
    enabled = true
    type = io.jikkou.kafka.KafkaExtensionProvider
    config = {
      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}
      }
    }
  }
}

3.2.2 - Resources

Apache Kafka Resources

More information:

3.2.2.1 - Kafka Brokers

Listing KafkaBroker

You can retrieve the state of Kafka Consumer Groups using the jikkou get kafkabrokers (or jikkou get kb) command.

Usage

Usage:

Get all 'KafkaBroker' resources.

jikkou get kafkabrokers [-hV] [--default-configs] [--dynamic-broker-configs]
                        [--list] [--static-broker-configs]
                        [--logger-level=<level>] [-o=<format>]
                        [-s=<expressions>]...

DESCRIPTION:

Use jikkou get kafkabrokers when you want to describe the state of all
resources of type 'KafkaBroker'.

OPTIONS:

      --default-configs   Describe built-in default configuration for configs
                            that have a default value.
      --dynamic-broker-configs
                          Describe dynamic configs that are configured as
                            default for all brokers or for specific broker in
                            the cluster.
  -h, --help              Show this help message and exit.
      --list              Get resources as ResourceListObject.
      --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`
  -o, --output=<format>   Prints the output in the specified format. Allowed
                            values: json, yaml (default yaml).
  -s, --selector=<expressions>
                          The selector expression used for including or
                            excluding resources.
      --static-broker-configs
                          Describe static configs provided as broker properties
                            at start up (e.g. server.properties file).
  -V, --version           Print version information and exit.

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

Examples

(command)

$ jikkou get kafkabrokers --static-broker-configs

(output)

---
apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaBroker"
metadata:
  name: "101"
  labels: {}
  annotations:
    kafka.jikkou.io/cluster-id: "xtzWWN4bTjitpL3kfd9s5g"
spec:
  id: "101"
  host: "localhost"
  port: 9092
  configs:
    advertised.listeners: "PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092"
    authorizer.class.name: "org.apache.kafka.metadata.authorizer.StandardAuthorizer"
    broker.id: "101"
    controller.listener.names: "CONTROLLER"
    controller.quorum.voters: "101@kafka:29093"
    inter.broker.listener.name: "PLAINTEXT"
    listener.security.protocol.map: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT"
    listeners: "PLAINTEXT://kafka:29092,PLAINTEXT_HOST://0.0.0.0:9092,CONTROLLER://kafka:29093"
    log.dirs: "/var/lib/kafka/data"
    node.id: "101"
    offsets.topic.replication.factor: "1"
    process.roles: "broker,controller"
    transaction.state.log.replication.factor: "1"
    zookeeper.connect: ""

3.2.2.2 - Kafka Consumer Groups

Listing KafkaConsumerGroup

You can retrieve the state of Kafka Consumer Groups using the jikkou get kafkaconsumergroups (or jikkou get kcg) command.

Usage

$ jikkou get kafkaconsumergroups --help

Usage:

Get all 'KafkaConsumerGroup' resources.

jikkou get kafkaconsumergroups [-hV] [--list] [--offsets]
                               [--logger-level=<level>] [-o=<format>]
                               [--in-states=PARAM]... [-s=<expressions>]...

DESCRIPTION:

Use jikkou get kafkaconsumergroups when you want to describe the state of all
resources of type 'KafkaConsumerGroup'.

OPTIONS:

  -h, --help              Show this help message and exit.
      --in-states=PARAM   If states is set, only groups in these states will be
                            returned. Otherwise, all groups are returned. This
                            operation is supported by brokers with version
                            2.6.0 or later
      --list              Get resources as ResourceListObject.
      --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
  -o, --output=<format>   Prints the output in the specified format. Allowed
                            values: json, yaml (default yaml).
      --offsets           Specify whether consumer group offsets should be
                            described.
  -s, --selector=<expressions>
                          The selector expression used for including or
                            excluding resources.
  -V, --version           Print version information and exit

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

Examples

(command)

$ jikkou get kafkaconsumergroups --in-states STABLE --offsets

(output)

---
apiVersion: "kafka.jikkou.io/v1beta1"
kind: "KafkaConsumerGroup"
metadata:
  name: "my-group"
  labels:
    kafka.jikkou.io/is-simple-consumer: false
status:
  state: "STABLE"
  members:
    - memberId: "console-consumer-b103994e-bcd5-4236-9d03-97065057e594"
      clientId: "console-consumer"
      host: "/127.0.0.1"
      assignments:
        - "my-topic-0"
      offsets:
        - topic: "my-topic"
          partition: 0
          offset: 0
  coordinator:
    id: "101"
    host: "localhost"
    port: 9092

Managing consumer group configuration

Since Kafka 4.x, consumer groups support dynamic group-level configuration. You can manage these declaratively through the spec.configs map, which is reconciled against the Kafka GROUP configuration resource (drift detection + incremental alter), just like topic configs.

apiVersion: "kafka.jikkou.io/v1"
kind: "KafkaConsumerGroup"
metadata:
  name: "my-group"
spec:
  configs:
    consumer.session.timeout.ms: 50000

By default, group configs present on the cluster but absent from the resource are removed (config-delete-orphans=true). Set it to false to leave externally-managed configs untouched.

3.2.2.3 - Kafka Topics

KafkaTopic

Specification

Here is the resource definition file for defining a KafkaTopic.

apiVersion: "kafka.jikkou.io/v1beta2"  # The api version (required)
kind: "KafkaTopic"                     # The resource kind (required)
metadata:
  name: <The name of the topic>        # (required)
  labels: { }
  annotations: { }
spec:
  partitions: <Number of partitions>   # (optional)
  replicas: <Number of replicas>       # (optional)
  configs:
    <config_key>: <Config Value>       # The topic config properties keyed by name to override (optional)
  configMapRefs: [ ]                   # The list of ConfigMap to be applied to this topic (optional)

The metadata.name property is mandatory and specifies the name of the kafka topic.

To use the cluster default values for the number of partitions and replicas you can set the property spec.partitions and spec.replicas to -1.

Example

Here is a simple example that shows how to define a single YAML file containing two topic definition using the KafkaTopic resource type.

file: kafka-topics.yaml

---
apiVersion: "kafka.jikkou.io/v1beta2"
kind: KafkaTopic
metadata:
  name: 'my-topic-p1-r1'  # Name of the topic
  labels:
    environment: example
spec:
  partitions: 1           # Number of topic partitions (use -1 to use cluster default)
  replicas: 1             # Replication factor per partition (use -1 to use cluster default)
  configs:
    min.insync.replicas: 1
    cleanup.policy: 'delete'
---
apiVersion: "kafka.jikkou.io/v1beta2"
kind: KafkaTopic
metadata:
  name: 'my-topic-p2-r1'   # Name of the topic 
  labels:
    environment: example
spec:
  partitions: 2             # Number of topic partitions (use -1 to use cluster default)
  replicas: 1               # Replication factor per partition (use -1 to use cluster default)
  configs:
    min.insync.replicas: 1
    cleanup.policy: 'delete'

See official Apache Kafka documentation for details about the topic-level configs.

KafkaTopicList

If you need to define multiple topics (e.g. using a template), it may be easier to use a KafkaTopicList resource.

Specification

Here the resource definition file for defining a KafkaTopicList.

apiVersion: "kafka.jikkou.io/v1beta2"  # The api version (required)
kind: "KafkaTopicList"                 # The resource kind (required)
metadata: # (optional)
  labels: { }
  annotations: { }
items: [ ]                             # An array of KafkaTopic

Example

Here is a simple example that shows how to define a single YAML file containing two topic definitions using the KafkaTopicList resource type. In addition, the example uses a ConfigMap object to define the topic configuration only once.

file: kafka-topics.yaml

---
apiVersion: "kafka.jikkou.io/v1beta2"
kind: KafkaTopicList
metadata:
  labels:
    environment: example
items:
  - metadata:
      name: 'my-topic-p1-r1'
    spec:
      partitions: 1
      replicas: 1
      configMapRefs: [ "TopicConfig" ]

  - metadata:
      name: 'my-topic-p2-r1'
    spec:
      partitions: 2
      replicas: 1
      configMapRefs: [ "TopicConfig" ]
---
apiVersion: "core.jikkou.io/v1beta2"
kind: ConfigMap
metadata:
  name: 'TopicConfig'
data:
  min.insync.replicas: 1
  cleanup.policy: 'delete'

3.2.2.4 - Kafka Users

Definition Format of KafkaUser

Below is the overall structure of the KafkaUser resource.

---
apiVersion: kafka.jikkou.io/v1  # The api version (required)
kind: KafkaUser                 # The resource kind (required)
metadata:
  name: <string>
  annotations:
    # force update
    kafka.jikkou.io/force-password-renewal: <boolean>
spec:
  authentications:
    - type: <enum> # or 
      password: <string>  # leave empty to generate secure password

See below for details about all these fields.

Metadata

metadata.name [required]

The name of the User.

kafka.jikkou.io/force-password-renewal [optional]

Specification

spec.authentications [required]

The list of authentications to manage for the user.

spec.authentications[].type [required]

The authentication type:

• scram-sha-256
• scram-sha-512

spec.authentications[].password [required]

The password of the user.

Examples

The following is an example of a resource describing a User:

---
# Example: file: kafka-scram-users.yaml
apiVersion: "kafka.jikkou.io/v1"
kind: "User"
metadata:
  name: "Bob"
spec:
  authentications:
    - type: scram-sha-256
      password: null
    - type: scram-sha-512
      password: null

Listing Kafka Users

You can retrieve the SCRAM users of a Kafka cluster using the jikkou get kafkausers (or jikkou get ku) command.

Usage

$ jikkou get kc --help

Usage:

Get all 'KafkaUser' resources.

jikkou get kafkausers [-hV] [--list] [--logger-level=<level>] [--name=<name>]
                      [-o=<format>]
                      [--selector-match=<selectorMatchingStrategy>]
                      [-s=<expressions>]...

DESCRIPTION:

Use jikkou get kafkausers when you want to describe the state of all resources
of type 'KafkaUser'.

OPTIONS:

  -h, --help              Show this help message and exit.
      --list              Get resources as ResourceListObject (default: false).
      --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`
      --name=<name>       The name of the resource.
  -o, --output=<format>   Prints the output in the specified format. Valid
                            values: JSON, YAML (default: YAML).
  -s, --selector=<expressions>
                          The selector expression used for including or
                            excluding resources.
      --selector-match=<selectorMatchingStrategy>
                          The selector matching strategy. Valid values: NONE,
                            ALL, ANY (default: ALL)
  -V, --version           Print version information and exit.

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

Examples

(command)

$ jikkou get ku

(output)

apiVersion: "kafka.jikkou.io/v1"
kind: "KafkaUser"
metadata:
  name: "Bob"
  labels: {}
  annotations:
    kafka.jikkou.io/cluster-id: "xtzWWN4bTjitpL3kfd9s5g"
spec:
  authentications:
    - type: "scram-sha-256"
      iterations: 8192
    - type: "scram-sha-512"
      iterations: 8192

3.2.2.5 - Kafka Share Groups

Listing KafkaShareGroup

You can retrieve the state of Kafka Share Groups using the jikkou get kafkasharegroups (or jikkou get ksg) command.

Examples

(command)

$ jikkou get kafkasharegroups --in-states STABLE --offsets

(output)

---
apiVersion: "kafka.jikkou.io/v1"
kind: "KafkaShareGroup"
metadata:
  name: "my-share-group"
spec:
  configs:
    share.auto.offset.reset: "earliest"
status:
  state: "STABLE"
  members:
    - memberId: "share-consumer-b103994e-bcd5-4236-9d03-97065057e594"
      clientId: "share-consumer"
      host: "/127.0.0.1"
      rackId: "rack-1"
      assignments:
        - "my-topic-0"
  offsets:
    - topic: "my-topic"
      partition: 0
      offset: 0
  coordinator:
    id: "101"
    host: "localhost"
    port: 9092

Managing share group configuration

The spec.configs map lets you declaratively manage the dynamic group configuration of a share group (e.g. share.auto.offset.reset, share.record.lock.duration.ms, share.isolation.level). These are applied against the Kafka GROUP configuration resource and are reconciled like topic configs (drift detection + incremental alter).

apiVersion: "kafka.jikkou.io/v1"
kind: "KafkaShareGroup"
metadata:
  name: "orders-queue"
spec:
  configs:
    share.record.lock.duration.ms: 30000
    share.auto.offset.reset: "earliest"

Apply it with:

$ jikkou apply --files orders-queue.yaml

By default, group configs present on the cluster but absent from the resource are removed (config-delete-orphans=true). Set it to false to leave externally-managed configs untouched.

Deleting KafkaShareGroup

A share group can be deleted by reconciling a resource flagged for deletion (jikkou delete), which removes the group via the AdminClient deleteShareGroups API.

Resetting share group offsets

See the KafkaShareGroupsResetOffsets action to reset the Share-Partition Start Offset (SPSO) of one or more share groups.

3.2.2.6 - Kafka Authorizations

Jikkou can be used to describe all ACL policies that need to be created on Kafka Cluster

KafkaPrincipalAuthorization

Specification

---
apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaPrincipalAuthorization"
metadata:
  name: "User:Alice"
spec:
  roles: [ ]                     # List of roles to be added to the principal (optional)
  acls:                          # List of KafkaPrincipalACL (required)
    - resource:
        type: <The type of the resource>                            #  (required)
        pattern: <The pattern to be used for matching resources>    #  (required) 
        patternType: <The pattern type>                             #  (required) 
      type: <The type of this ACL>     # ALLOW or DENY (required) 
      operations: [ ]                  # Operation that will be allowed or denied (required) 
      host: <HOST>                     # IP address from which principal will have access or will be denied (optional)

For more information on how to define authorization and ACLs, see the official Apache Kafka documentation: Security

Operations

The list below describes the valid values for the spec.acls.[].operations property :

• READ
• WRITE
• CREATE
• DELETE
• ALTER
• DESCRIBE
• CLUSTER_ACTION
• DESCRIBE_CONFIGS
• ALTER_CONFIGS
• IDEMPOTENT_WRITE
• CREATE_TOKEN
• DESCRIBE_TOKENS
• ALL

For more information see official Apache Kafka documentation: Operations in Kafka

Resource Types

The list below describes the valid values for the spec.acls.[].resource.type property :

• TOPIC
• GROUP
• CLUSTER
• USER
• TRANSACTIONAL_ID

For more information see official Apache Kafka documentation: Resources in Kafka

Pattern Types

The list below describes the valid values for the spec.acls.[].resource.patternType property :

• LITERAL: Use to allow or denied a principal to have access to a specific resource name.
• MATCH: Use to allow or denied a principal to have access to all resources matching the given regex.
• PREFIXED: Use to allow or denied a principal to have access to all resources having the given prefix.

Example

---
apiVersion: "kafka.jikkou.io/v1beta2"    # The api version (required)
kind: "KafkaPrincipalAuthorization"      # The resource kind (required)
metadata:
  name: "User:Alice"
spec:
  acls:
    - resource:
        type: 'topic'
        pattern: 'my-topic-'
        patternType: 'PREFIXED'
      type: "ALLOW"
      operations: [ 'READ', 'WRITE' ]
      host: "*"
    - resource:
        type: 'topic'
        pattern: 'my-other-topic-.*'
        patternType: 'MATCH'
      type: 'ALLOW'
      operations: [ 'READ' ]
      host: "*"
---
apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaPrincipalAuthorization"
metadata:
  name: "User:Bob"
spec:
  acls:
    - resource:
        type: 'topic'
        pattern: 'my-topic-'
        patternType: 'PREFIXED'
      type: 'ALLOW'
      operations: [ 'READ', 'WRITE' ]
      host: "*"