diff --git a/README.adoc b/README.adoc index cfed79d9c..bb173593c 100644 --- a/README.adoc +++ b/README.adoc @@ -17,13 +17,12 @@ See: https://streamthoughts.github.io/jikkou/[official documentation] == Introduction -**https://github.com/streamthoughts/jikkou[Jikkou]** (jikkō / 実行) is an open-source tool designed to provide an efficient and easy way to -manage, automate, and provision resource configurations for Kafka, Schema Registry, etc. +**https://github.com/streamthoughts/jikkou[Jikkou]** (jikkō / 実行) is an open-source tool built to provide an efficient +and easy way to manage, automate, and provision resources on your event-stream platform. -Developed by Kafka ❤️, Jikkou aims to streamline daily operations on https://kafka.apache.org/documentation/[Apache Kafka], -ensuring that platform governance is no longer a boring and tedious task for both **Developers** and **Administrators**. +Developed by Kafka ❤️, Jikkou aims to streamline daily operations on https://kafka.apache.org/documentation/[Apache Kafka], ensuring that platform governance is no longer a boring and tedious task for both **Developers** and **Administrators**. -Jikkou enables a declarative management approach of **Topics**, **ACLs**, **Quotas**, **Schemas** and even more with the use of YAML files called **_Resource Definitions_**. +Jikkou enables a declarative management approach of **Topics**, **ACLs**, **Quotas**, **Schemas**, **Connectors** and even more with the use of YAML files called **_Resource Definitions_**. Taking inspiration from `kubectl` and Kubernetes resource definition files, Jikkou offers an intuitive and user-friendly approach to configuration management. @@ -35,53 +34,57 @@ See https://medium.com/@fhussonnois/why-is-managing-kafka-topics-still-such-a-pa == Installation -The latest stable release of jikkou (x86) for Linux, and macOS can be downloaded from https://github.com/streamthoughts/jikkou/releases/latest[GitHub Releases] +The latest stable release of jikkou (x86) for Linux, and macOS can be retrieved via https://sdkman.io/[SDKMan]: + +```bash +sdk install jikkou +``` + +Alternatively, the latest stable release of jikkou (x86) for Linux, and macOS can be downloaded from https://github.com/streamthoughts/jikkou/releases/latest[GitHub Releases] Below are the convenience links for the base downloads of Jikkou. [%header,format=csv] |=== Platform,Link -Linux, ⬇️ https://github.com/streamthoughts/jikkou/releases/download/v0.29.0/jikkou-0.29.0-linux-x86_64.zip[download (jikkou-0.29.0-linux-x86_64.zip)] -macOS,⬇️ https://github.com/streamthoughts/jikkou/releases/download/v0.29.0/jikkou-0.29.0-osx-x86_64.zip[download (jikkou-0.29.0-osx-x86_64.zip)] +Linux, ⬇️ https://github.com/streamthoughts/jikkou/releases/download/v0.30.0/jikkou-0.30.0-linux-x86_64.zip[download (jikkou-0.30.0-linux-x86_64.zip)] +macOS,⬇️ https://github.com/streamthoughts/jikkou/releases/download/v0.30.0/jikkou-0.30.0-osx-x86_64.zip[download (jikkou-0.30.0-osx-x86_64.zip)] |=== -Alternatively, jikkou is also available: - -* As a fatJar available from https://repo.maven.apache.org/maven2/io/streamthoughts/jikkou/0.29.0/[Maven Central] -* As a Docker Image available from https://hub.docker.com/r/streamthoughts/jikkou[Docker Hub]. - -Download the jikkou binary from the https://github.com/streamthoughts/jikkou/releases[releases page], uncompress -and copy to the desired location. +Download the jikkou binary from the https://github.com/streamthoughts/jikkou/releases[releases page], uncompress and copy to the desired location. -[source, bash] +[source,bash] ---- # Download the latest stable release -wget https://github.com/streamthoughts/jikkou/releases/download/v0.29.0/jikkou-0.29.0-linux-x86_64.zip +wget https://github.com/streamthoughts/jikkou/releases/download/v0.30.0/jikkou-0.30.0-linux-x86_64.zip # Uncompress -unzip jikkou-0.29.0-linux-x86_64.zip +unzip jikkou-0.30.0-linux-x86_64.zip # Copy to the desired location -cp jikkou-0.29.0-linux-x86_64/bin/jikkou $HOME/.local/bin +cp jikkou-0.30.0-linux-x86_64/bin/jikkou $HOME/.local/bin ---- -It is recommended to install the bash/zsh completion script `jikkou_completion`: +Finally, Jikkou is can also be retrieved : + +* As a **fatJar** from https://repo.maven.apache.org/maven2/io/streamthoughts/jikkou/0.30.0/[Maven Central] +* As a **Docker Image** from https://hub.docker.com/r/streamthoughts/jikkou[Docker Hub]. + +Note, it is recommended to install the bash/zsh completion script `jikkou_completion`: -[source, bash] +[source,bash] ---- wget https://raw.githubusercontent.com/streamthoughts/jikkou/main/jikkou_completion . jikkou_completion ---- or alternatively, run the following command for generation the completion script. -[source, bash] +[source,bash] ---- source <(jikkou generate-completion) ---- -WARNING: If you are using macOS you may need to remove the quarantine attribute from the bits before you can use them - To do this, run the following: `sudo xattr -r -d com.apple.quarantine path/to/jikkou/folder/` +WARNING: If you are using macOS you may need to remove the quarantine attribute from the bits before you can use them To do this, run the following: `sudo xattr -r -d com.apple.quarantine path/to/jikkou/folder/` == Overview @@ -89,6 +92,7 @@ Here is an example of how to create and manage a _Kafka topic_ using Jikkou: * Create a resource file _kafka-topics.yaml_: kafka-topics.yaml::: + [source,yaml] ---- # file:./kafka-topics.yaml @@ -107,7 +111,7 @@ spec: * Then run the following command: -[source, bash] +[source,bash] ---- $ jikkou apply --files ./kafka-topics.yaml ---- @@ -115,11 +119,13 @@ $ jikkou apply --files ./kafka-topics.yaml Jikkou will then take care of computing and applying the necessary changes directly to your cluster. _(output)_: + [source] ---- TASK [CREATE] Create a new topic my-first-topic-with-jikkou (partitions=12, replicas=3) - CHANGED ********************** ---- -[source, json] + +[source,json] ---- { "changed" : true, @@ -146,6 +152,7 @@ TASK [CREATE] Create a new topic my-first-topic-with-jikkou (partitions=12, repl "status" : "CHANGED" } ---- + [source] ---- EXECUTION in 2s 661ms (DRY_RUN) diff --git a/docs/content/en/about/_index.md b/docs/content/en/about/_index.md deleted file mode 100644 index 15d50eaf6..000000000 --- a/docs/content/en/about/_index.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: About Jikkou -linkTitle: About -description: > - What is Jikkou and why using it ? -weight: 20 -menu: - main: - weight: 20 -ui.breadcrumb_disable: false ---- - -{{< blocks/cover title="" image_anchor="bottom" height="min" class="text-left">}} -{{< page/header >}} -{{< /blocks/cover >}} - -
- -
-{{< page/toc collapsed=true placement="inline" >}} -
- -
-
- -**https://github.com/streamthoughts/jikkou[Jikkou]** (jikkō / 実行) is an open-source tool designed to provide an efficient and easy way to -manage, automate, and provision resource configurations for Kafka, Schema Registry, etc. - -Developed by Kafka ❤️, Jikkou aims to streamline daily operations on https://kafka.apache.org/documentation/[Apache Kafka], -ensuring that platform governance is no longer a boring and tedious task for both **Developers** and **Administrators**. - -Jikkou enables a declarative management approach of **Topics**, **ACLs**, **Quotas**, **Schema** and even more with the use of YAML files called **_Resource Definitions_**. - -Taking inspiration from `kubectl` and Kubernetes resource definition files, Jikkou offers an intuitive and user-friendly approach to configuration management. - -Jikkou can be used on on-premise Apache Kafka, https://aiven.io/kafka[Aiven], and https://www.confluent.io/confluent-cloud/[Confluent Cloud]. - -

The main usage scenarios

- -* Create new resource entities for Apache Kafka (i.e., _Topics_, _ACLs_, and _Quotas_). -* Update the configurations of existing resource entities. -* Delete resource entities which are not anymore managed. -* Describe all the configuration defined for Brokers. -* Describe all the configuration defined for _Topics_, _ACLs_, and _Quotas_. -* Replicate configurations of a production cluster to another with a few command lines. -* Initialize a new cluster for testing purpose. - -

Core features that make it awesome

- -* Simple command line interface (CLI) for end user. -* Simple Java API on top of the Kafka's [Java AdminClient](https://kafka.apache.org/30/javadoc/org/apache/kafka/clients/admin/Admin.html). -* Completely stateless and thus does not store any state (Basically: _Your kafka cluster is the state of Jikkou_). -* Pluggable validation rules to ensure that resources meet your requirement before being created or updated ona target cluster. -* Pluggable resource manager to extend Jikkou with cloud managed services for Apache Kafka which are supported out-of-the-box. -* Simple templating mechanism using [Jinja](https://jinja.palletsprojects.com/en/3.0.x/) notation. - -

The story behind Jikkou

-Jikkou was initially created as a side project to help the development teams to quickly re-create topics on Apache Kafka clusters used for testing purpose. -The goal was to ensure that environments was always cleanup and ready for running integration tests. Over time, new features have been added to Jikkou so that it can also be used by Kafka administrators on Kafka environments. - - -Today we continue to make the tool evolve in open-source because we find that the solutions that have appeared over time in the Kafka ecosystem do not respond as well to Kafka developers and administrators. -In addition, existing solutions are either designed to work only with Kubernetes or rely on dedicated services to manage the state of the solution. - -

Credits

-Images used on this website documentation: - -* Page Cover: Photo by [Anton Ivanov](https://unsplash.com/es/@bradanton?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/). - - - -
-{{< page/toc placement="sidebar" >}} -
- -{{< page/page-meta-links >}} - -
\ No newline at end of file diff --git a/docs/content/en/about/featured-background.jpg b/docs/content/en/about/featured-background.jpg deleted file mode 100644 index b2b71395a..000000000 Binary files a/docs/content/en/about/featured-background.jpg and /dev/null differ diff --git a/docs/content/en/docs/Install/_index.md b/docs/content/en/docs/Install/_index.md index f45734b07..cf22bd94f 100644 --- a/docs/content/en/docs/Install/_index.md +++ b/docs/content/en/docs/Install/_index.md @@ -1,15 +1,26 @@ --- title: "Install Jikkou" linkTitle: "Install" -weight: 1 +weight: 2 description: > This guide shows how to install the Jikkou CLI. +menu: + main: + weight: 20 --- {{% pageinfo %}} Jikkou can be installed either from source, or from releases. {{% /pageinfo %}} +## From SDKMan! (recommanded) + +The latest stable release of jikkou (x86) for Linux, and macOS can be retrieved via https://sdkman.io/[SDKMan]: + +```bash +sdk install jikkou +``` + ## From The Jikkou Project ### Releases @@ -17,7 +28,7 @@ Jikkou can be installed either from source, or from releases. Every [`release`](https://github.com/streamthoughts/jikkou/releases) released versions of Jikkou is available: * As a zip/tar.gz package from [GitHub Releases](https://github.com/streamthoughts/jikkou/releases) (for Linux, MacOS) -* As a fatJar available from [Maven Central](https://repo.maven.apache.org/maven2/io/streamthoughts/jikkou/0.26.0/) +* As a fatJar available from [Maven Central](https://repo.maven.apache.org/maven2/io/streamthoughts/jikkou/0.30.0/) * As a docker image available from [Docker Hub](https://hub.docker.com/r/streamthoughts/jikkou). These are the official ways to get Jikkou releases that you manually downloaded and installed. @@ -25,8 +36,8 @@ These are the official ways to get Jikkou releases that you manually downloaded #### Install From Release distribution 1. Download your desired [version](https://github.com/streamthoughts/jikkou/releases) -2. Unpack it (`unzip jikkou-0.26.0-linux-x86_64.zip`) -3. Move the unpacked directory to the desired destination (`mv jikkou-0.26.0-linux-x86_64 /opt/jikkou`) +2. Unpack it (`unzip jikkou-0.30.0-linux-x86_64.zip`) +3. Move the unpacked directory to the desired destination (`mv jikkou-0.30.0-linux-x86_64 /opt/jikkou`) 4. Add the executable to your PATH (`export PATH=$PATH:/opt/jikkou/bin`) From there, you should be able to run the client: `jikkou help`. diff --git a/docs/content/en/docs/Overview/_index.md b/docs/content/en/docs/Overview/_index.md new file mode 100755 index 000000000..fee6d95af --- /dev/null +++ b/docs/content/en/docs/Overview/_index.md @@ -0,0 +1,76 @@ +--- +title: "Overview" +linkTitle: "Overview" +description: "What is Jikkou ?" +weight: 1 +menu: + main: + weight: 10 +ui.breadcrumb_disable: false +--- + +{{% pageinfo %}} +Welcome to the Jikkou documentation! Jikkou, means “execution (e.g. of a plan) or actual state (of things)” in Japanese. +{{% /pageinfo %}} + +## What is Jikkou ? + +Jikkou is a lightweight open-source tool designed to provide an efficient and easy way to manage, automate and provision +resources on **Event-Driven Data Mesh platforms** (or, more simply, on any **Apache Kafka Infrastructures**). + +## How does Jikkou work ? + +Jikkou adopts a stateless approach and thus does not store any state internally. Instead, it leverages your platforms +or services as the source of truth. This design allows you to seamlessly integrate Jikkou with other solutions +(such as Ansible, Terraform, etc.) or use it on an ad hoc basis for specific needs, making it incredibly flexible and versatile + +## Why Jikkou ? The Story Behind Jikkou. + +Jikkou was originally created as a side project to help development teams quickly recreate topics on Apache Kafka +clusters used for testing purposes (the project was called _Kafka Specs_). At the time, the aim was to ensure +that environments were always clean and ready to run integration tests. + +But over time, new features were added, and so Jikkou was born with the aim to streamline day-to-day operations +on Apache Kafka, ensuring that platform governance is no longer a tedious and boring task for both developers and +administrators. + +Today, Jikkou is used in production on several projects, providing efficient management of Kafka resources through +a GitOps approach. The project continues to evolve as an open-source project, as the solutions that have +appeared over time in the Kafka ecosystem do not meet the needs of Kafka developers and administrators as well. +In fact, existing solutions are either designed to work only with Kubernetes, or rely on dedicated services to manage +the state of the solution. + +Now, we sincerely believe that Jikkou can play a role in bootstrapping a _self-service platform_ for a Data Mesh +organization, by unifying the way to manage the various assets required to create and manage a Data Product +exposed through Apache Kafka. + +## Is Jikkou for me ? + +Jikkou can be implemented regardless of the size of your team or data platform. + +### Small Development Team + +Jikkou is particularly useful for small development teams looking to quickly automate the creation and +maintenance of their topics without having to implement a complex solution that requires learning a new technology +or language. + +### Centralized Infrastructure (DevOps) Team + +Jikkou can be very effective in larger contexts, where the configuration of your Kafka Topics, ACLs, and Quotas +for all your data platform is managed by a single and centralized devops team. + +### Decentralized Data Product Teams + +In an organization adopting Data Mesh principles, Jikkou can be leveraged in a decentralized way by each of your +Data Teams to manage all the assets (e.g. Topics, ACLs, Schemas, Connectors, etc.) necessary to expose and manage +their Data Products. + +## Can I Use Jikkou with my Apache Kafka vendor ? + +Jikkou can be used any Apache Kafka infrastructures, including: + +* [Apache Kafka](https://kafka.apache.org/) +* [Aiven](https://aiven.io/kafka) +* [Amazon MSK](https://aws.amazon.com/fr/msk/) +* [Confluent Cloud](https://www.confluent.io/confluent-cloud/) +* [Redpanda](https://redpanda.com/) diff --git a/docs/content/en/docs/_index.md b/docs/content/en/docs/_index.md index 5aa73fa68..370da6410 100755 --- a/docs/content/en/docs/_index.md +++ b/docs/content/en/docs/_index.md @@ -2,26 +2,12 @@ --- title: "Documentation" linkTitle: "Documentation" -weight: 20 +weight: 10 menu: main: - weight: 20 + weight: 30 --- -## Welcome to Jikkou - -Welcome to the Jikkou documentation. Jikkou is the tool to automate the management of the configurations that live on your Apache Kafka clusters. -This guide shows you how to get started managing configurations for Topics, ACLS, Quotas, and more in the simplest and most seamless way possible. - -## Is Jikkou for me ? - -Jikkou is particularly useful for small development teams that want to quickly automate the creation and updating of their topics without having to implement complex solutions. -But, it can be also very effective in larger contexts, where the configuration of your topics for all your projects are managed by a single centralized administration team. - -In addition, it is built on top of the Kafka's [Java AdminClient](https://kafka.apache.org/30/javadoc/org/apache/kafka/clients/admin/Admin.html). -Thus, it works out-of-the-box with most the Apache Kafka distributions and cloud provider managed services (e.g., [Aiven](https://aiven.io/), [Confluent Cloud](https://confluent.cloud/), etc). -However, you may find some limitations with some managed services for Apache Kafka depending on which APIs are allowed to be used. Indeed, some providers limit for example some config properties to be overloaded or use own ACL management mechanisms. -