feat: minor fixes and docs update

.gitignore

@@ -37,6 +37,6 @@ node_modules
 /deploy/terraform.tfstate.backup
 *.genin.yml
 *.genin.yaml
+!/docs/examples/*
 inventory.yml
 inventory.yaml
-

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "genin"
-version = "0.4.14"
+version = "0.4.15"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2022, AUTHORS: please see AUTHORS file
+Copyright (c) 2023, AUTHORS: please see AUTHORS file
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

README.md

@@ -46,8 +46,8 @@ Download and unzip the archive for the desired architecture.
 
 Universal executable:
 ```shell
-curl -sLO https://binary.picodata.io/repository/raw/genin/bin/genin-0.4.14-x86_64-musl.tar.gz
-tar -xvf genin-0.4.14-x86_64-musl.tar.gz ; sudo install genin /usr/local/bin/
+curl -sLO https://binary.picodata.io/repository/raw/genin/bin/genin-0.4.15-x86_64-musl.tar.gz
+tar -xvf genin-0.4.15-x86_64-musl.tar.gz ; sudo install genin /usr/local/bin/
 ```
 
 ---
@@ -84,11 +84,11 @@ sudo yum install -y genin
 2. If you want to install `rpm` packages directly without 
 adding our repository.
 ```shell
-sudo rpm -i https://binary.picodata.io/repository/yum/el/8/x86_64/os/genin-0.4.14-1.el8.x86_64.rpm
+sudo rpm -i https://binary.picodata.io/repository/yum/el/8/x86_64/os/genin-0.4.15-1.el8.x86_64.rpm
 ```
 RHEL 7.x, CentOS 7.x
 ```shell
-sudo rpm -i https://binary.picodata.io/repository/yum/el/7/x86_64/os/genin-0.4.14-1.el7.x86_64.rpm
+sudo rpm -i https://binary.picodata.io/repository/yum/el/7/x86_64/os/genin-0.4.15-1.el7.x86_64.rpm
 ```
 
 ---
@@ -116,7 +116,7 @@ sudo apt install -y genin
 
 2. Downloading and installing the package directly:
 ```shell
-curl -sLO https://binary.picodata.io/repository/raw/genin/deb/genin-0.4.14.amd64.deb && sudo dpkg -i genin-0.4.14.amd64.deb
+curl -sLO https://binary.picodata.io/repository/raw/genin/deb/genin-0.4.15.amd64.deb && sudo dpkg -i genin-0.4.15.amd64.deb
 ```
 
 ---
@@ -142,7 +142,7 @@ sudo apt install -y genin
 
 2. Downloading and installing the package directly:
 ```shell
-curl -sLO https://binary.picodata.io/repository/raw/genin/deb/genin-0.4.14.amd64.deb && sudo dpkg -i genin-0.4.14.amd64.deb
+curl -sLO https://binary.picodata.io/repository/raw/genin/deb/genin-0.4.15.amd64.deb && sudo dpkg -i genin-0.4.15.amd64.deb
 ```
 
 ---
@@ -162,8 +162,8 @@ brew install genin
 Use the following command to grab and install Genin in macOS (10.10+) wihtout 
 homebrew:
 ```shell
-curl -L https://binary.picodata.io/repository/raw/genin/apple/genin-0.4.14-darwin-amd64.zip -o genin-0.4.14-darwin-amd64.zip 
-unzip genin-0.4.14-darwin-amd64.zip -d ~/bin/
+curl -L https://binary.picodata.io/repository/raw/genin/apple/genin-0.4.15-darwin-amd64.zip -o genin-0.4.15-darwin-amd64.zip 
+unzip genin-0.4.15-darwin-amd64.zip -d ~/bin/
 ```
 > **Note:** The application can then be found under the `~/bin` directory. 
 > Make sure the directory is in your `$PATH`.
@@ -181,8 +181,8 @@ brew install [email protected]
 #### Windows
 Use the following command to grab and install Genin in Windows 7 64 bit or newer:
 ```shell
-curl.exe -L https://binary.picodata.io/repository/raw/genin/windows/genin-0.4.14-darwin-amd64.zip -o genin-0.4.14-windows-amd64.zip 
-unzip.exe genin-0.4.14-windows-amd64.zip -d %HOME%/.cargo/bin/
+curl.exe -L https://binary.picodata.io/repository/raw/genin/windows/genin-0.4.15-darwin-amd64.zip -o genin-0.4.15-windows-amd64.zip 
+unzip.exe genin-0.4.15-windows-amd64.zip -d %HOME%/.cargo/bin/
 ```
 > **Note:** The application can then be found under the `.cargo/bin` folder inside 
 > your user profile folder. Make sure it is in your `%PATH%`.
@@ -340,6 +340,8 @@ hosts:
 This is a perfectly valid and working configuration file. The rest of the 
 parameters wil use their default values.
 
+A set of examples can be found in the directory [docs/examples](docs/examples).
+
 ---
 
 #### Changing the Topology

README.ru.md

@@ -49,8 +49,8 @@ Genin уже заранее скомпилирован под разные ар
 
 Универсальный исполняемый файл:
 ```shell
-curl -sLO https://binary.picodata.io/repository/raw/genin/bin/genin-0.4.14-x86_64-musl.tar.gz
-tar -xvf genin-0.4.14-x86_64-musl.tar.gz ; sudo install genin /usr/local/bin/
+curl -sLO https://binary.picodata.io/repository/raw/genin/bin/genin-0.4.15-x86_64-musl.tar.gz
+tar -xvf genin-0.4.15-x86_64-musl.tar.gz ; sudo install genin /usr/local/bin/
 ```
 
 ---
@@ -87,11 +87,11 @@ sudo yum install -y genin
 2. Так же вы можете установить пакет `rpm` напрямую без добавления нашего репозитория.
 RHEL 8.x, CentOS 8.x, Rockylinux 8.x, recent Fedora version
 ```shell
-sudo rpm -i https://binary.picodata.io/repository/yum/el/8/x86_64/os/genin-0.4.14-1.el8.x86_64.rpm
+sudo rpm -i https://binary.picodata.io/repository/yum/el/8/x86_64/os/genin-0.4.15-1.el8.x86_64.rpm
 ```
 RHEL 7.x, CentOS 7.x
 ```shell
-sudo rpm -i https://binary.picodata.io/repository/yum/el/7/x86_64/os/genin-0.4.14-1.el7.x86_64.rpm
+sudo rpm -i https://binary.picodata.io/repository/yum/el/7/x86_64/os/genin-0.4.15-1.el7.x86_64.rpm
 ```
 > **Note:** будьте внимательны, так как при выборе не правильной версии ос могут быть ошибки 
 > при установке `rpm` 
@@ -118,7 +118,7 @@ sudo apt install -y genin
 
 2. Загрузкой и установкой пакета напрямую:
 ```shell
-curl -sLO https://binary.picodata.io/repository/raw/genin/deb/genin-0.4.14.amd64.deb && sudo dpkg -i genin-0.4.14.amd64.deb
+curl -sLO https://binary.picodata.io/repository/raw/genin/deb/genin-0.4.15.amd64.deb && sudo dpkg -i genin-0.4.15.amd64.deb
 ```
 
 ---
@@ -143,7 +143,7 @@ sudo apt install -y genin
 
 2. Загрузкой и установкой пакета напрямую:
 ```shell
-curl -sLO https://binary.picodata.io/repository/raw/genin/deb/genin-0.4.14.amd64.deb && sudo dpkg -i genin-0.4.14.amd64.deb
+curl -sLO https://binary.picodata.io/repository/raw/genin/deb/genin-0.4.15.amd64.deb && sudo dpkg -i genin-0.4.15.amd64.deb
 ```
 
 ---
@@ -163,8 +163,8 @@ brew install genin
 Для установки без помощи homebrew используйте следующие команды для загрузки и установки 
 Genin на macOS (10.10+):
 ```shell
-curl -sLO https://binary.picodata.io/repository/raw/genin/osx/genin-0.4.14-x86_64-macosx.tar.gz
-unzip genin-0.4.14-darwin-amd64.zip -d ~/bin/
+curl -sLO https://binary.picodata.io/repository/raw/genin/osx/genin-0.4.15-x86_64-macosx.tar.gz
+unzip genin-0.4.15-darwin-amd64.zip -d ~/bin/
 ```
 
 ---
@@ -188,8 +188,8 @@ brew install [email protected]
 Используйте следующие команды для скачивания и установки Genin на операционных системах
 Windows 7 64 и новее.
 ```shell
-curl.exe -sLO https://binary.picodata.io/repository/raw/genin/win/genin-0.4.14-win64.zip
-unzip.exe genin-0.4.14-win64.zip -d %HOME%/.cargo/bin/
+curl.exe -sLO https://binary.picodata.io/repository/raw/genin/win/genin-0.4.15-win64.zip
+unzip.exe genin-0.4.15-win64.zip -d %HOME%/.cargo/bin/
 ```
 > **Note:** Genin будет распакован в директорию `.cargo/bin` которая находится в домашнем
 > каталоге важего пользователя. Перед использованием приложения пожалуйста удостоверьтесь 
@@ -199,7 +199,7 @@ unzip.exe genin-0.4.14-win64.zip -d %HOME%/.cargo/bin/
 ```
 genin --version
 ```
-Если вы видите сообщение `genin 0.4.14` значит установка прошла успешно.
+Если вы видите сообщение `genin 0.4.15` значит установка прошла успешно.
 
 ---
 ## Руководство по использованию
@@ -357,6 +357,8 @@ hosts:
 не задали (по сравнению с файлом сгенерированным командой `genin init`), будут 
 заменены дефолтными значениями в процессе генерации инвентаря.
 
+Набор примеров можно найти в директории [docs/examples](docs/examples).
+
 ---
 
 #### Изменение топологии

docs/examples/cluster.genin.yml

@@ -0,0 +1,53 @@
+---
+topology:
+  - name: router
+    replicasets_count: <<replicasets_count>>        # How many masters we want, by default equal 1
+    replication_factor: <<replication_factor>>      # Number of replicas in replicaset, default 0
+    roles: [ router, failover-coordinator ]
+    weight: <<weight>>                              # Vshard replicaset weight (matters only if `vshard-storage` role is enabled)
+    cartridge_extra_env:                            # Environment variables for instance service (systemd service)
+      REMOTE_SERVER: db1.pg.svc.cluster.local
+      REMOTE_USER: user
+      REMOTE_PASSWORD: password
+    config:                                         # Config with arbitrary key-values pairs
+      http_port: <<http_start_port>>                # Specify http port to start counting from
+      binary_port: <<binary_start_port>>            # Specify binary port to start counting from
+      all_rw: false                                 # A flag indicating that all servers in the replicaset should be read-write
+      zone: server-1                                # Zone parameter for ansible cartridge playbook
+      vshard_group:                                 # Vshard group for vshard-storage
+      additional_config:                            # Additional parameters to be added to the host config
+        server_url: foo.bar.baz
+    vars:                                           # Ansible wars to be added to hosts
+      ansible_user: user
+      ansible_password: password
+  - name: storage
+    replicasets_count: <<replicasets_count>>        # How many masters we want, by default equal 1
+    replication_factor: <<replication_factor>>      # Number of replicas in replicaset, default 0
+    roles: [ storage ]
+hosts:
+  - name: datacenter-1
+    config:
+      http_port: <<http_start_port>>                # Specify http port to start counting from
+      binary_port: <<binary_start_port>>            # Specify binary port to start counting from
+    hosts:
+      - name: server-1
+        config:
+          http_port: <<http_start_port>>            # Specify http port to start counting from
+          binary_port: <<binary_start_port>>        # Specify binary port to start counting from
+          address: <<host_address>>                 # Host or instance address (maybe IP or URI)
+      - name: server-2
+        config:
+          address: <<host_address>>                 # Host or instance address (maybe IP or URI)
+failover:
+  mode: stateful                                    # Failover mode (stateful, eventual, disabled)
+  state_provider: stateboard                        # What is serve failover (stateboard, stateful)
+  stateboard_params:
+    uri: <<host_address_and_port>>                 # Uri on which the stateboard will be available (ip:port)
+    password: <<stateboard_password>>               # Stateboard password
+vars:
+  ansible_user: <<ansible_user>>                    # Username under which the ansible will connect to the servers
+  ansible_password: <<ansible_password>>            # Ansible's user password
+  cartridge_app_name: <<application_name>>
+  cartridge_cluster_cookie: <<cookie>>              # Cookie for connecting to the administrative console of the instances
+  cartridge_package_path: <<absolute_path>>         # Path to the application package
+  cartridge_bootstrap_vshard: true

docs/examples/fd-cluster.genin.yml

@@ -0,0 +1,39 @@
+---
+topology:
+  - name: router
+    replicasets_count: 1
+    roles: [ router, failover-coordinator ]
+    failure_domains: [ server-2 ]                   # In this case, all router instances will be distributed to server-2
+  - name: storage
+    replicasets_count: 2
+    replication_factor: 2
+    roles: [ storage ]
+  - name: cache
+    replicasets_count: 3
+    roles: [ cache ]
+    failure_domains: [ server-1 ]                   # In this case, all 3 instances will be distributed to server-1
+hosts:
+  - name: datacenter-1
+    config:
+      http_port: <<http_start_port>>                # Specify http port to start counting from
+      binary_port: <<binary_start_port>>            # Specify binary port to start counting from
+    hosts:
+      - name: server-1
+        config:
+          address: <<host_address>>                 # Host or instance address (maybe IP or URI)
+      - name: server-2
+        config:
+          address: <<host_address>>                 # Host or instance address (maybe IP or URI)
+failover:
+  mode: stateful                                    # Failover mode (stateful, eventual, disabled)
+  state_provider: stateboard                        # What is serve failover (stateboard, stateful)
+  stateboard_params:
+    uri: <<host_address_and_port>>                 # Uri on which the stateboard will be available (ip:port)
+    password: <<stateboard_password>>               # Stateboard password
+vars:
+  ansible_user: <<ansible_user>>                    # Username under which the ansible will connect to the servers
+  ansible_password: <<ansible_password>>            # Ansible's user password
+  cartridge_app_name: <<application_name>>
+  cartridge_cluster_cookie: <<cookie>>              # Cookie for connecting to the administrative console of the instances
+  cartridge_package_path: <<absolute_path>>         # Path to the application package
+  cartridge_bootstrap_vshard: true

docs/examples/tdg-cluster.genin.yaml

@@ -0,0 +1,68 @@
+---
+instances:
+  - name: logger
+    type: custom
+    replicasets_count: 1
+    replication_factor: 0
+    weight: 10
+    roles:
+      - logger
+      - notifier
+  - name: runner
+    type: custom
+    replicasets_count: 2
+    replication_factor: 0
+    weight: 10
+    roles:
+      - output_processor
+      - task_runner
+  - name: processor
+    type: custom
+    replicasets_count: 2
+    replication_factor: 0
+    weight: 10
+    roles:
+      - connector
+      - input_processor
+      - failover-coordinator
+  - name: scheduler
+    type: custom
+    replicasets_count: 1
+    replication_factor: 0
+    weight: 10
+    roles:
+      - scheduler
+  - name: storage
+    type: storage
+    replicasets_count: 1
+    replication_factor: 2
+    weight: 10
+    roles:
+      - storage
+hosts:
+  - name: vagrant
+    type: datacenter
+    ports:
+      http: 8081
+      binary: 3031
+    hosts:
+      - name: tdg-1
+        ip: 192.168.1.2
+      - name: tdg-2
+        ip: 192.168.1.3
+      - name: tdg-3
+        ip: 192.168.1.4
+failover:
+  mode: stateful
+  state_provider: etcd2
+  etcd2_params:
+    prefix: cartridge/tdg
+    lock_delay: 30
+    endpoints:
+      - "http://192.168.1.2:2379"
+vars:
+  ansible_user: vagrant
+  ansible_password: vagrant
+  cartridge_app_name: tdg
+  cartridge_cluster_cookie: myapp-cookie
+  cartridge_package_path: ./tdg-1.7.17.rpm