Jikkou Concepts

• 1: Jikkou Resources
• 2: Labels and Annotations
• 3: Jikkou Reconciliation
• 4: Jikkou Selectors
• 5: Jikkou Transformations
• 6: Jikkou Validations
• 7: Jikkou Templates
• 8: Jikkou Collectors
• 9: Jikkou Controllers
• 10: Jikkou Providers
• 11: Jikkou Reporters
• 12: Jikkou Actions
• 13: Jikkou Resource Repositories

1 - Jikkou Resources

Resource Objects

All resources can be distinguished between persistent objects, which are used to describe the desired state of your system, and transient objects, which are only used to enrich or provide additional capabilities for the definition of persistent objects.

A resource is an object with a type (called a Kind) and a concrete model that describe the associated data. All resource are scoped by an API Group and Version.

Resource Definition

Resources are described in YAML format.

Here is a sample resource that described a Kafka Topic.

apiVersion: "kafka.jikkou.io/v1beta2"
kind: KafkaTopic
metadata:
  name: 'my-topic'
  labels:
    environment: test
  annotations: {}
spec:
  partitions: 1
  replicas: 1
  configs:
    min.insync.replicas: 1
    cleanup.policy: 'delete'

Resource Properties

The following are the properties that can be set to describe a resource:

2 - Labels and Annotations

Labels

You can use labels to attach arbitrary identifying metadata to objects.

Labels are key/value maps:

metadata:
  labels:
    "key1": "value-1"
    "key2": "value-2"

Example

metadata:
  labels:
    environment: "stating"

Annotations

You can use annotations to attach arbitrary non-identifying metadata to objects.

Annotations are key/value maps:

metadata:
  annotations:
    key1: "value-1"
    key2: "value-2"

Built-in Annotations

jikkou.io/ignore

Used on: All Objects.

This annotation indicates whether the object should be ignored for reconciliation.

jikkou.io/bypass-validations

Used on: All Objects.

This annotation indicates whether the object should bypass the validation chain. In other words, no validations will be applied on the object.

jikkou.io/delete

Used on: All Objects.

This annotation indicates (when set to true) that the object should be deleted from your system.

jikkou.io/resource-location

Used by jikkou.

This annotation is automatically added by Jikkou to an object when loaded from your local filesystem.

jikkou.io/items-count

Used by jikkou.

This annotation is automatically added by Jikkou to an object collection grouping several resources of homogeneous type.

3 - Jikkou Reconciliation

Changes

A Change represents a difference, detected during reconciliation, between two objects that can reconciled or corrected by adding, updating, or deleting an object or property attached to the actual state of the system.

A Change represents a detected difference between two objects during the reconciliation process. These differences can be reconciled or corrected by adding, updating, or deleting an object or property associated with the actual state of the system

• Jikkou identifies four types of changes:

• ADD: Indicates the addition of a new object or property to an existing object.

• UPDATE: Indicates modifications made to an existing object or property of an existing object.

• DELETE: Indicates the removal of an existing object or property of an existing object.

• NONE: Indicates that no changes were made to an existing object or property.

Reconciliation Modes

Depending on the chosen reconciliation mode, only specific types of changes will be applied.

Jikkou provides four distinct reconciliation modes that determine the types of changes to be applied:

• CREATE: This mode only applies changes that create new resource objects in your system.
• DELETE: This mode only applies changes that delete existing resource objects in your system.
• UPDATE: This mode only applies changes that create or update existing resource objects in your system.
• APPLY_ALL: This mode applies all changes to ensure that the actual state of a resource in the cluster matches the desired state defined in your resource definition file, regardless of the specific type of change.

Each mode corresponds to a command offered by the Jikkou CLI (i.e., create, update, delete, and apply). Choose the appropriate mode based on your requirements.

Reconciliation Options

Depending on the type of resources being reconciled, the controller that will be involved in the reconciliation process might accept some options (i.e., using --options argument).

Mark Resource for Deletion

To delete all the states associated with resource’s entities, you must add the following annotation to the resource definition:

metadata:
  annotations:
    jikkou.io/delete: true

4 - Jikkou Selectors

Overview

Selectors filter which resources Jikkou operates on. They are passed via the --selector (or -s) CLI option and can be used with any command that accepts resources, including get, apply, create, update, delete, diff, validate, and prepare.

You can specify multiple selectors by repeating the --selector flag, and control how they are combined using the --selector-match option.

Selector Expression Syntax

A selector expression follows one of two formats:

• With an explicit selector type prefix:

<SELECTOR_TYPE>: <EXPRESSION>

• Using the default field selector (the prefix can be omitted):

<KEY> <OPERATOR> <VALUE>
<KEY> <OPERATOR> (VALUE1, VALUE2, ...)

Supported Selectors

Field (default)

The field selector filters resources based on any field in the resource object, using dot-notation to navigate nested properties.

field: <KEY> <OPERATOR> <VALUE>
field: <KEY> <OPERATOR> (VALUE1, VALUE2, ...)

Since field is the default selector type, the field: prefix can be omitted.

Examples

# Select resources by name
jikkou get kafkatopics -s 'metadata.name IN (my-topic, other-topic)'

# Select by kind
jikkou get kafkatopics -s 'kind IN (KafkaTopic)'

# Select by label (using field selector)
jikkou get kafkatopics -s 'metadata.labels.environment IN (staging, production)'

# Select topics matching a regex pattern
jikkou get kafkatopics -s 'metadata.name MATCHES (^public-.*)'

# Exclude internal topics
jikkou get kafkatopics -s 'metadata.name DOESNOTMATCH (^__.*)'

# With explicit field: prefix (equivalent to above)
jikkou get kafkatopics -s 'field: metadata.name MATCHES (^public-.*)'

Label

The label selector provides a shorthand to filter resources by their metadata labels, without needing the full metadata.labels. path prefix.

label: <LABEL_KEY> <OPERATOR> <VALUE>
label: <LABEL_KEY> <OPERATOR> (VALUE1, VALUE2, ...)

Examples

# Select resources with a specific label value
jikkou get kafkatopics -s 'label: environment IN (staging, production)'

# Select resources that have a specific label (regardless of value)
jikkou get kafkatopics -s 'label: team EXISTS'

# Select resources that do NOT have a specific label
jikkou get kafkatopics -s 'label: deprecated DOESNOTEXIST'

Expression (since Jikkou v0.36)

The expr selector enables complex filtering using the Common Expression Language (CEL). This is the most powerful selector type, supporting conditions on nested fields, arrays, maps, and computed expressions.

The resource being evaluated is available as the resource variable.

expr: <CEL_EXPRESSION>

Examples

# Select resources with a label value in a list
jikkou get kafkatopics \
  -s 'expr: has(resource.metadata.labels.env) && resource.metadata.labels.env in ["staging", "production"]'

# Select Kafka topics with at least 12 partitions
jikkou get kafkatopics \
  -s 'expr: resource.kind == "KafkaTopic" && resource.spec.partitions >= 12'

# Select resources missing a specific annotation
jikkou get kafkatopics \
  -s 'expr: !has(resource.metadata.annotations["mycompany.io/owner"])'

Expression Operators

The following operators are available for field and label selectors:

Matching Strategies

When specifying multiple selectors, use --selector-match to control how they are combined:

The default strategy is ALL.

Examples

# Match resources whose name starts with "__" OR is exactly "_schemas" (ANY)
jikkou get kafkatopics \
  --selector 'metadata.name MATCHES (^__.*)' \
  --selector 'metadata.name IN (_schemas)' \
  --selector-match ANY

# Match resources that have both labels (ALL - default)
jikkou get kafkatopics \
  -s 'label: environment IN (production)' \
  -s 'label: team EXISTS'

# Exclude resources matching any selector (NONE)
jikkou get kafkatopics \
  -s 'metadata.name MATCHES (^__.*)' \
  -s 'metadata.name IN (_schemas)' \
  --selector-match NONE

SEE ALSO

• jikkou get - Display resources with selectors
• jikkou apply - Apply resources with selectors
• jikkou diff - Diff resources with selectors
• Labels and annotations - Using labels for resource organization

5 - Jikkou Transformations

Available Transformations

You can list all the available transformations using the Jikkou CLI command:

jikkou extensions list --type=Transformation [-kinds <a resource kind to filter returned results>]

Transformation chain

When using Jikkou CLI, you can configure a transformation chain that will be applied to every resource. This chain consists of multiple transformations, each designed to handle different types of resources. Jikkou ensures that a transformation is executed only for the resource types it supports. In cases where a resource is not accepted by a transformation, it is passed to the next transformation in the chain. This process continues until a suitable transformation is found or until all transformations have been attempted.

Configuration

jikkou {
  # The list of transformations to execute
  transformations: [
    {
      # Simple or fully qualified class name of the transformation extension.
      type = ""
      # Priority to be used for executing this transformation extension.
      # The lowest value has the highest priority, so it's run first. Minimum value is -2^31 (highest) and a maximum value is 2^31-1 (lowest).
      # Usually, values under 0 should be reserved for internal transformation extensions.
      priority = 0
      config = {
        # Configuration properties for this transformation
      }
    }
  ]
}

Example

jikkou {
  # The list of transformations to execute
  transformations: [
    {
      # Enforce a minimum number of replicas for a kafka topic
      type = KafkaTopicMinReplicasTransformation
      priority = 100
      config = {
        minReplicationFactor = 4
      }
    },
    {
      # Enforce a {@code min.insync.replicas} for a kafka topic.
      type = KafkaTopicMinInSyncReplicasTransformation
      priority = 100
      config = {
        minInSyncReplicas = 2
      }
    }
  ]
}

6 - Jikkou Validations

Available Validations

You can list all the available validations using the Jikkou CLI command:

jikkou api-extensions list --category=validation [--kinds <a resource kind to filter returned results>]

Validation chain

When using Jikkou CLI, you can configure a validation chain that will be applied to every resource. This chain consists of multiple validations, each designed to handle different types of resources. Jikkou ensures that a validation is executed only for the resource types it supports. In cases where a resource is not accepted by a validation, it is passed to the next validation in the chain. This process continues until a suitable validation is found or until all validations have been attempted.

Configuration

jikkou {
  # The list of validations to execute
  validations: [
    {
      # Custom name for the validation rule
      name = ""
      # Simple or fully qualified class name of the validation extension.
      type = ""
      config = {
        # Configuration properties for this validation
      }
    }
  ]
}

Example

jikkou {
  # The list of transformations to execute
  validations: [
    {
      # Custom name for the validation rule
      name = topicMustBePrefixedWithRegion
      # Simple or fully qualified class name of the validation extension.
      type = TopicNameRegexValidation
      # The config values that will be passed to the validation.
      config = {
        topicNameRegex = "(europe|northamerica|asiapacific)-.+"
      }
    }
  ]
}

7 - Jikkou Templates

Template Engine

Jikkou provides a simple templating mechanism based-on Jinjava, a Jinja template engine for Java.

Read the official documentation of Jinja to learn more about the syntax and semantics of the template engine.

How Does It Work ?

Jikkou performs the rendering of your template in two phases:

1. First, an initial rendering is performed using only the values and labels passed through the command-lines arguments.
   • Thus, it is perfectly OK if your resource file is not initially a valid YAML file.
2. Then, a second and final rendering is performed after parsing the YAML resource file using the additional values and labels as defined into the YAML resource file.
   • Therefore, it’s important that your resource file is converted into a valid YAML file after the first rendering.

Variables

Jikkou defines a number of top-level variables that are passed to the template engine.

• values:

  • The values passed into the template through the command-line --values-files and/or --set-value arguments
  • In addition, values can be defined into the application.conf file and directly into the template file using the property template.values.
  • By default, values is empty.

• labels:

  • The labels passed into the template through the command-line argument: --set-label.
  • In addition, labels can be defined into the template file using the property metadata.labels.
  • By default, labels is empty.

• system.env:

  • This provides access to all environment variables.

• system.props:

  • This provides access to all system properties.

Template Values

When using templating, a resource definition file may contain the additional property template. fields:

apiVersion: The api version (required)
kind: The resource kind (required)
metadata:
  labels: The set of key/value pairs that you can use to describe your resource file (optional)
  annotations: The set of key/value pairs automatically generated by the tool (optional)
template:
  values: The set of key/value pairs to be passed to the template engine (optional)
spec: Specification of the resource

Values Data File

Values Data File are used to define all the necessary values (i.e., the variables) to be used for generating a template.

Example

# file: ./values.yaml
topicConfigs:
  partitions: 4
  replicas: 3
topicPrefix: "{{ system.env.TOPIC_PREFIX | default('test', true) }}"
countryCodes:
  - fr
  - be
  - de
  - es
  - uk
  - us

Template Resource File

Example

# file: ./kafka-topics.tpl
apiVersion: 'kafka.jikkou.io/v1beta2'
kind: 'KafkaTopicList'
items:
  { % for country in values.countryCodes % }
  - metadata:
      name: "{{ values.topicPrefix}}-iot-events-{{ country }}"
    spec:
      partitions: { { values.topicConfigs.partitions } }
      replicas: { { values.topicConfigs.replicas } }
      configMapRefs:
        - TopicConfig
    { % endfor % }
---
apiVersion: "core.jikkou.io/v1beta2"
kind: "ConfigMap"
metadata:
  name: TopicConfig
template:
  values:
    default_min_insync_replicas: "{{ values.topicConfigs.replicas | default(3, true) | int | add(-1) }}"
data:
  retention.ms: 3600000
  max.message.bytes: 20971520
  min.insync.replicas: '{% raw %}{{ values.default_min_insync_replicas }}{% endraw %}'

Command

$  TOPIC_PREFIX=local jikkou validate --files topics.tpl --values-files values.yaml 

(Output)

---
apiVersion: "kafka.jikkou.io/v1beta2"
kind: "KafkaTopicList"
metadata:
  labels: { }
  annotations:
    jikkou.io/resource-location: "file:///tmp/jikkou/topics.tpl"
spec:
  topics:
    - metadata:
        name: "local-iot-events-fr"
      spec:
        partitions: 4
        replicas: 3
        configs:
          min.insync.replicas: "2"
          retention.ms: 3600000
          max.message.bytes: 20971520
    - metadata:
        name: "local-iot-events-be"
      spec:
        partitions: 4
        replicas: 3
        configs:
          min.insync.replicas: "2"
          retention.ms: 3600000
          max.message.bytes: 20971520
    - metadata:
        name: "local-iot-events-de"
      spec:
        partitions: 4
        replicas: 3
        configs:
          min.insync.replicas: "2"
          max.message.bytes: 20971520
          retention.ms: 3600000
    - metadata:
        name: "local-iot-events-es"
      spec:
        partitions: 4
        replicas: 3
        configs:
          min.insync.replicas: "2"
          max.message.bytes: 20971520
          retention.ms: 3600000
    - metadata:
        name: "local-iot-events-uk"
      spec:
        partitions: 4
        replicas: 3
        configs:
          min.insync.replicas: "2"
          max.message.bytes: 20971520
          retention.ms: 3600000
    - metadata:
        name: "local-iot-events-us"
      spec:
        partitions: 4
        replicas: 3
        configs:
          min.insync.replicas: "2"
          max.message.bytes: 20971520
          retention.ms: 3600000

Configuration

jinja {
  # Enable/Disable recursive macro calls for rendering
  enableRecursiveMacroCalls = false
}

8 - Jikkou Collectors

Available Collectors

You can list all the available collectors using the Jikkou CLI command:

jikkou extensions list --type=Collector [-kinds <a resource kind to filter returned results>]

9 - Jikkou Controllers

Available Controllers

You can list all the available controllers using the Jikkou CLI command:

jikkou extensions list --type=Controller [-kinds <a resource kind to filter returned results>]

10 - Jikkou Providers

What is a Provider?

A provider is a pluggable module that registers a cohesive set of extensions (controllers, collectors, transformations, validations, actions, health indicators) and resource types into Jikkou at runtime.

Each provider targets a specific platform and is responsible for:

• Registering extensions such as controllers, collectors, transformations, validations, and actions.
• Registering resource types that describe the API resources it manages.
• Accepting configuration specific to its platform (e.g., Kafka bootstrap servers, Schema Registry URL).

Configuration

Providers are configured in the Jikkou configuration file under the jikkou.provider namespace. Each provider entry has a unique name and includes its type, an enabled flag, and a config block.

jikkou {
  provider.kafka {
    enabled = true
    type = io.streamthoughts.jikkou.kafka.KafkaExtensionProvider
    config = {
      client {
        bootstrap.servers = "localhost:9092"
      }
    }
  }
}

Configuration Properties

Multiple Instances

You can configure multiple instances of the same provider type by giving each a unique name. This is useful when you need to manage resources across different environments (e.g., dev vs. production Kafka clusters) from a single Jikkou installation.

Use default = true to mark one instance as the default for its provider type:

jikkou {
  provider.kafka-prod {
    enabled = true
    type = io.streamthoughts.jikkou.kafka.KafkaExtensionProvider
    default = true
    config = {
      client.bootstrap.servers = "kafka-prod:9092"
    }
  }
  provider.kafka-staging {
    enabled = true
    type = io.streamthoughts.jikkou.kafka.KafkaExtensionProvider
    config = {
      client.bootstrap.servers = "kafka-staging:9092"
    }
  }
}

Use the --provider flag to target a specific provider instance when running commands:

# Uses the default provider (kafka-prod)
jikkou get kafkatopics

# Explicitly target the staging provider
jikkou get kafkatopics --provider kafka-staging

# Apply resources to staging
jikkou apply -f my-resources.yaml --provider kafka-staging

Provider Resolution

The --provider flag is always optional. Jikkou resolves the target provider using the following fallback chain:

1. Single provider of a given type: It is used automatically — no --provider flag needed, no default property needed. If you only have one Kafka provider configured, everything works exactly as before.
2. Multiple providers, one marked default = true: The default is used when --provider is omitted. You only need the flag when targeting a non-default instance.
3. Multiple providers, no default: You must specify --provider on every command. Omitting it results in an error: “No default configuration defined, and multiple configurations found for provider type”.

Provider selection works across all commands — apply, create, update, delete, diff, validate, replace, patch, get, action, and health — and extends to the REST API server with a provider field in reconciliation request bodies.

Built-in Providers

Jikkou ships with the following built-in extension providers:

Discovering Providers

You can inspect providers and the extensions they contribute using the CLI:

# List all registered extensions with their provider
jikkou api-extensions list

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

# List API resources and their supported verbs
jikkou api-resources

SEE ALSO

• Controllers - Extensions that reconcile resources
• Collectors - Extensions that collect resource state
• Configuration - How to configure providers via contexts

11 - Jikkou Reporters

Configuration

Jikkou allows you to configure multiple reporters as follows:

jikkou {
  # The list of reporters to execute
  reporters: [
    {
      # Custom name for the reporter
      name = ""
      # Simple or fully qualified class name of the transformation extension.
      type = ""
      config = {
        # Configuration properties for this reporter
      }
    }
  ]
}

Built-in implementations

Jikkou packs with some built-in ChangeReporter implementations:

KafkaChangeReporter

The KafkaChangeReporter can be used to send change results into a given kafka topic. Changes will be published as Cloud Events.

Configuration

The below example shows how to configure the KafkaChangeReporter.

jikkou {
  # The default custom reporters to report applied changes.
  reporters = [
    {
      name = "kafka-reporter"
      type = io.streamthoughts.jikkou.kafka.reporter.KafkaChangeReporter
      config = {
        # The 'source' of the event that will be generated.
        event.source = "jikkou/cli"
        kafka = {
          # If 'true', topic will be automatically created if it does not already exist.
          topic.creation.enabled = true
          # The default replication factor used for creating topic.
          topic.creation.defaultReplicationFactor = 1
          # The name of the topic the events will be sent.
          topic.name = "jikkou-resource-change-event"
          # The configuration settings for Kafka Producer and AdminClient
          client = ${jikkou.kafka.client} {
            client.id = "jikkou-reporter-producer"
          }
        }
      }
    }
  ]
}

12 - Jikkou Actions

Available Actions (CLI)

You can list all the available actions using the Jikkou CLI command:

jikkou api-extensions list --category=action [-kinds <a resource kind to filter returned results>]

Execution Actions (CLI)

You can execute a specific extension using the Jikkou CLI command:

jikkou action <ACTION_NAME> execute [<options>]

13 - Jikkou Resource Repositories

Overview

A Resource Repository is an extensible component in Jikkou that enables dynamic loading of resources from various sources (e.g., local directories, remote Git repositories) into the execution context.

Repositories are typically used to:

• Load reusable resources across multiple environments or teams
• Keep transient or computed resources separate from persistent definitions
• Inject configuration or validation policies dynamically

This feature is particularly useful when you want to define shareable or transient resources such as ConfigMap, ValidatingResourcePolicy, or other resource types outside the CLI input or local context.

Configuration

Jikkou allows you to configure multiple repositories as follows:

jikkou {
  repositories: [
    {
      # Unique name for the repository
      name = "<repository-name>"

      # Fully qualified class name or alias for the repository type
      type = "<repository-class-or-alias>"

      # Optional configuration specific to the repository implementation
      config = {
        # key = value
      }
    }
  ]
}

Built-in implementations

Jikkou ships with the following built-in ResourceRepository implementations:

LocalResourceRepository

Loads resources from local files or directories.

Type: io.streamthoughts.jikkou.core.repository.LocalResourceRepository

Example Configuration

jikkou {
  repositories = [
    {
      name = "local"
      type = io.streamthoughts.jikkou.core.repository.LocalResourceRepository
      config {
        files = [
          "./resources/",
          "./policies/"
        ]
      }
    }
  ]
}

See more: LocalResourceRepository Configuration

GitHubResourceRepository

Loads resources from a public or private GitHub repository.

Type: io.streamthoughts.jikkou.core.repository.GitHubResourceRepository

Example Configuration

jikkou {
  repositories = [
    {
      name = "github-repository"
      type = io.streamthoughts.jikkou.core.repository.GitHubResourceRepository
      config {
        repository = "streamthoughts/jikkou"
        branch = "main"
        paths = [
          "examples/",
          "config/"
        ]
        # Optionally set an access token for private repositories
        # token = ${?GITHUB_TOKEN}
      }
    }
  ]
}

See more: GitHubResourceRepository Configuration