Skip to content

Commit a083d61

Browse files
DmitryTravyanDmitryTravyan
committed
feat: update en readme
1 parent 8bea57e commit a083d61

File tree

1 file changed

+334
-0
lines changed

1 file changed

+334
-0
lines changed

‎README.md‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@
2222
+ [Balancing and distribution control](#Balancing-and-distribution-control)
2323
+ [Reverse parsing config](#Reverse-parsing-config)
2424
+ [Flags and options](#flags-and-options)
25+
+ [Genin upgrade](#Genin-upgrade)
26+
+ [Genin state](#Genin-state)
2527
* [Building from sources](#building-from-sources)
2628
* [Contributing](#contributing)
2729
* [Versioning](#versioning)
@@ -724,6 +726,338 @@ genin build -o my-cluster.yml
724726
genin build -o my-cluster.yml --force
725727
```
726728
729+
The `--export-state` argument can be useful to export [state](#Genin-state) into a
730+
separate file.
731+
```shell
732+
genin build -s cluster.genin.yml --export-state my-state.gz
733+
```
734+
735+
The `quiet` option can be useful if you want to disable the display of the cluster in
736+
the console.
737+
```shell
738+
genin init --quiet
739+
genin build --quiet -s cluster.genin.yml
740+
genin upgrade --quiet --old cluster.genin.yml --new cluster-new.genin.yml
741+
```
742+
743+
Especially for cases when an idiomatic distribution is needed, an option has been added
744+
`--idiomatic-merge`. Without it, `genin` considers replicasets with the same name are
745+
equivalent. For example `api-1` and `api-1-1` will be considered replicas of the same
746+
replicaset. With the addition of the option without an exact match of the replica name,
747+
the replicas will never be merged to the replicaset.
748+
```shell
749+
genin upgrade --old cluster-old.genin.yml --new cluster-new.genin.yml
750+
751+
+-------------+-------------+-------------+-------------+
752+
| cluster |
753+
+-------------+-------------+-------------+-------------+
754+
| datacenter-1 | datacenter-2 |
755+
+-------------+-------------+-------------+-------------+
756+
| server-1 | server-2 | server-3 | server-4 |
757+
+-------------+-------------+-------------+-------------+
758+
| router-1 | router-2 | router-3 | router-4 |
759+
| 8081/3031 | 8081/3031 | 8081/3031 | 8081/3031 |
760+
+-------------+-------------+-------------+-------------+
761+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
762+
| 8082/3032 | 8082/3032 | 8082/3032 | 8082/3032 |
763+
+-------------+-------------+-------------+-------------+
764+
| api-1 | api-1-1 | api-1-2 | api-1-3 |
765+
| 8083/3033 | 8083/3033 | 8083/3033 | 8083/3033 |
766+
+-------------+-------------+-------------+-------------+
767+
```
768+
769+
```shell
770+
genin upgrade --idiomatic-merge --old cluster-old.genin.yml --new cluster-new.genin.yml
771+
772+
+-------------+-------------+-------------+-------------+
773+
| cluster |
774+
+-------------+-------------+-------------+-------------+
775+
| datacenter-1 | datacenter-2 |
776+
+-------------+-------------+-------------+-------------+
777+
| server-1 | server-2 | server-3 | server-4 |
778+
+-------------+-------------+-------------+-------------+
779+
| router-1 | router-2 | router-3 | router-4 |
780+
| 8081/3031 | 8081/3031 | 8081/3031 | 8081/3031 |
781+
+-------------+-------------+-------------+-------------+
782+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
783+
| 8082/3032 | 8082/3032 | 8082/3032 | 8082/3032 |
784+
+-------------+-------------+-------------+-------------+
785+
| api-1 | api-1-1 | api-1-2 | api-1-3 |
786+
| 8083/3033 | 8083/3033 | 8083/3033 | 8083/3033 |
787+
+-------------+-------------+-------------+-------------+
788+
| api-1-4 | |
789+
| 8083/3033 | |
790+
+-------------+-------------+-------------+-------------+
791+
```
792+
793+
---
794+
795+
### Genin upgrade
796+
797+
Almost from the first versions of `Genin` it supports the `upgrade` command which allows
798+
generating inventories based on two different cluster configurations. She has several
799+
significant differences from the `build` command. For example, if we take the initial
800+
configuration with 4 servers in 2 data centers, double the number of servers, and add
801+
several new replicas, `genin build` will generate a standard distribution.
802+
```shell
803+
genin build --source cluster-old.genin.yml
804+
805+
+-------------+-------------+-------------+-------------+
806+
| cluster |
807+
+-------------+-------------+-------------+-------------+
808+
| datacenter-1 | datacenter-2 |
809+
+-------------+-------------+-------------+-------------+
810+
| server-1 | server-2 | server-3 | server-4 |
811+
+-------------+-------------+-------------+-------------+
812+
| router-1 | router-2 | router-3 | router-4 |
813+
| 8081/3031 | 8081/3031 | 8081/3031 | 8081/3031 |
814+
+-------------+-------------+-------------+-------------+
815+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
816+
| 8082/3032 | 8082/3032 | 8082/3032 | 8082/3032 |
817+
+-------------+-------------+-------------+-------------+
818+
```
819+
820+
```shell
821+
genin build --source cluster-new.genin.yml
822+
823+
+-------------+-------------+-------------+-------------+
824+
| cluster |
825+
+-------------+-------------+-------------+-------------+
826+
| datacenter-1 | datacenter-2 |
827+
+-------------+-------------+-------------+-------------+
828+
| server-1 | server-2 | server-3 | server-4 |
829+
+-------------+-------------+-------------+-------------+
830+
| router-1 | router-2 | router-3 | router-4 |
831+
| 8081/3031 | 8081/3031 | 8081/3031 | 8081/3031 |
832+
+-------------+-------------+-------------+-------------+
833+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
834+
| 8082/3032 | 8082/3032 | 8082/3032 | 8082/3032 |
835+
+-------------+-------------+-------------+-------------+
836+
| storage-2-1 | storage-2-2 | storage-2-3 | storage-2-4 |
837+
| 8083/3033 | 8083/3033 | 8083/3033 | 8083/3033 |
838+
+-------------+-------------+-------------+-------------+
839+
```
840+
841+
In this case, any change in the configuration, for example, changing ports, will completely
842+
overwrite starting ports of the original cluster. Installation based on such inventory is
843+
completely will break an already existing cluster.
844+
```shell
845+
genin build --source cluster-old.genin.yml
846+
847+
+-------------+-------------+-------------+-------------+
848+
| cluster |
849+
+-------------+-------------+-------------+-------------+
850+
| datacenter-1 | datacenter-2 |
851+
+-------------+-------------+-------------+-------------+
852+
| server-1 | server-2 | server-3 | server-4 |
853+
+-------------+-------------+-------------+-------------+
854+
| router-1 | router-2 | router-3 | router-4 |
855+
| 8081/3031 | 8081/3031 | 8081/3031 | 8081/3031 |
856+
+-------------+-------------+-------------+-------------+
857+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
858+
| 8082/3032 | 8082/3032 | 8082/3032 | 8082/3032 |
859+
+-------------+-------------+-------------+-------------+
860+
```
861+
862+
```shell
863+
genin build --source cluster-new.genin.yml
864+
865+
+-------------+-------------+-------------+-------------+
866+
| cluster |
867+
+-------------+-------------+-------------+-------------+
868+
| datacenter-1 | datacenter-2 |
869+
+-------------+-------------+-------------+-------------+
870+
| server-1 | server-2 | server-3 | server-4 |
871+
+-------------+-------------+-------------+-------------+
872+
| router-1 | router-2 | router-3 | router-4 |
873+
| 9081/5031 | 9081/5031 | 9081/5031 | 9081/5031 |
874+
+-------------+-------------+-------------+-------------+
875+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
876+
| 9082/5032 | 9082/5032 | 9082/5032 | 9082/5032 |
877+
+-------------+-------------+-------------+-------------+
878+
| storage-2-1 | storage-2-2 | storage-2-3 | storage-2-4 |
879+
| 9083/5033 | 9083/5033 | 9083/5033 | 9083/5033 |
880+
+-------------+-------------+-------------+-------------+
881+
```
882+
883+
Therefore, there is a `genin upgrade` command specifically for **upgrade** cases.
884+
> **Note:** `upgrade` is a sequential cluster change based on source configuration
885+
> `--old` and target configuration `--new`. With which it is guaranteed that
886+
> ports/addresses and other unchanging parameters are saved on cluster instances `--old`.
887+
888+
```shell
889+
genin build --source cluster-old.genin.yml
890+
891+
+-------------+-------------+-------------+-------------+
892+
| cluster |
893+
+-------------+-------------+-------------+-------------+
894+
| datacenter-1 | datacenter-2 |
895+
+-------------+-------------+-------------+-------------+
896+
| server-1 | server-2 | server-3 | server-4 |
897+
+-------------+-------------+-------------+-------------+
898+
| router-1 | router-2 | router-3 | router-4 |
899+
| 8081/3031 | 8081/3031 | 8081/3031 | 8081/3031 |
900+
+-------------+-------------+-------------+-------------+
901+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
902+
| 8082/3032 | 8082/3032 | 8082/3032 | 8082/3032 |
903+
+-------------+-------------+-------------+-------------+
904+
```
905+
906+
```shell
907+
genin upgrade --old cluster-old.genin.yml --new cluster-new.genin.yml
908+
909+
+-------------+-------------+-------------+-------------+
910+
| cluster |
911+
+-------------+-------------+-------------+-------------+
912+
| datacenter-1 | datacenter-2 |
913+
+-------------+-------------+-------------+-------------+
914+
| server-1 | server-2 | server-3 | server-4 |
915+
+-------------+-------------+-------------+-------------+
916+
| router-1 | router-2 | router-3 | router-4 |
917+
| 8081/3031 | 8081/3031 | 8081/3031 | 8081/3031 |
918+
+-------------+-------------+-------------+-------------+
919+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
920+
| 8082/3032 | 8082/3032 | 8082/3032 | 8082/3032 |
921+
+-------------+-------------+-------------+-------------+
922+
| storage-2-1 | storage-2-2 | storage-2-3 | storage-2-4 |
923+
| 9083/5033 | 9083/5033 | 9083/5033 | 9083/5033 |
924+
+-------------+-------------+-------------+-------------+
925+
```
926+
927+
Such inventory can be safely applied over a cluster installed with using the first inventory,
928+
and all new instances will have a new configuration, and all the old ones will receive only
929+
those parameters that can be changed without breaking the cluster.
930+
931+
932+
---
933+
934+
### Genin state
935+
936+
When using `genin upgrade` we always get consistent changes in the cluster, but only within
937+
one single upgrade. This is because the configuration clusters passed in the `--old` and `--new`
938+
arguments are distributed in the same way as with `genin build`. That is, we first distribute the
939+
configuration passed to `--old` and then over it passed to `--new`. This means that if we want to
940+
`upgrade` again but already on top of the configuration passed to `--old` then this will be
941+
equivalent to calling `genin build`.
942+
```shell
943+
genin upgrade --old cluster-old.genin.yml --new cluster-new.genin.yml
944+
945+
+-------------+-------------+-------------+-------------+
946+
| cluster |
947+
+-------------+-------------+-------------+-------------+
948+
| datacenter-1 | datacenter-2 |
949+
+-------------+-------------+-------------+-------------+
950+
| server-1 | server-2 | server-3 | server-4 |
951+
+-------------+-------------+-------------+-------------+
952+
| router-1 | router-2 | router-3 | router-4 |
953+
| 8081/3031 | 8081/3031 | 8081/3031 | 8081/3031 |
954+
+-------------+-------------+-------------+-------------+
955+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
956+
| 8082/3032 | 8082/3032 | 8082/3032 | 8082/3032 |
957+
+-------------+-------------+-------------+-------------+
958+
| storage-2-1 | storage-2-2 | storage-2-3 | storage-2-4 |
959+
| 9083/5033 | 9083/5033 | 9083/5033 | 9083/5033 |
960+
+-------------+-------------+-------------+-------------+
961+
```
962+
963+
```shell
964+
genin upgrade --old cluster-new.genin.yml --new cluster-new-new.genin.yml
965+
966+
+-------------+-------------+-------------+-------------+
967+
| cluster |
968+
+-------------+-------------+-------------+-------------+
969+
| datacenter-1 | datacenter-2 |
970+
+-------------+-------------+-------------+-------------+
971+
| server-1 | server-2 | server-3 | server-4 |
972+
+-------------+-------------+-------------+-------------+
973+
| router-1 | router-2 | router-3 | router-4 |
974+
| 9081/5031 | 9081/5031 | 9081/5031 | 9081/5031 |
975+
+-------------+-------------+-------------+-------------+
976+
| storage-1-1 | storage-1-2 | storage-1-3 | storage-1-4 |
977+
| 9082/5032 | 9082/5032 | 9082/5032 | 9082/5032 |
978+
+-------------+-------------+-------------+-------------+
979+
| storage-2-1 | storage-2-2 | storage-2-3 | storage-2-4 |
980+
| 9083/5033 | 9083/5033 | 9083/5033 | 9083/5033 |
981+
+-------------+-------------+-------------+-------------+
982+
| storage-3-1 | storage-3-2 | storage-3-3 | storage-3-4 |
983+
| 9581/5531 | 9581/5531 | 9581/5531 | 9581/5531 |
984+
+-------------+-------------+-------------+-------------+
985+
```
986+
987+
Specially to avoid this, `genin` was added to save metadata and tree allocations to a special
988+
`geninstate`. In fact, this is just a cast of how `genin` allocated instances when
989+
`genin upgrade` is called, allowing `upgrade` to be called as much once and always receive
990+
only consistent (safe) inventory changes.
991+
992+
Starting from version `0.5.0` in the startup directory `genin` will create a directory
993+
`.geninstate` and save archives with the state in it. For example, a directory might look like
994+
this:
995+
```shell
996+
.geninstate
997+
├── 0b94d04e689d2a52048574903de899a36582a968a700095a019dc1097587054a.gz
998+
├── 14a3a6c82ec93b6a7e87bc09e086e42cdbca97c5ed158624054265e30036cbeb.gz
999+
├── 165582c99839c0dc3b6d918075128204da11116c5477f2cf839b608f06fddf11.gz
1000+
├── 47e85eb6762cba402308430277a3061cffc39b0b2a6cdabb53ec4d8951d1cd3f.gz
1001+
├── 92fe50ac32b1821d60aa41906500b8772360f005ebebb16efd405c513fd0e4bc.gz
1002+
├── bf8e0e2339e13eff95c7f6acfb1668d15638ca03e1250726aa03f8e356841d37.gz
1003+
└── latest.gz
1004+
```
1005+
1006+
`state` filenames can be of two types. The first is the `latest` state generated by last
1007+
successful run of `genin upgrade`. The second one is **sha256** sha sum computed on based
1008+
on `shasum256(shasum256 --old + shasum256 --new)`.
1009+
1010+
To view the states (their contents), a new command `genin list-state` has also been added which
1011+
will display the last 10 runs of the `genin upgrade` command. In the displayed information will be
1012+
the type of operation, the arguments with which `genin` was called, as well as the list of changes
1013+
(what has been added and removed).
1014+
1015+
```shell
1016+
---
1017+
Upgrade: --from-latest-state --new tests/resources/cluster-new-v5.genin.yml -f
1018+
State file: .geninstate/latest.gz
1019+
Topology changes:
1020+
+ storage-3-1
1021+
+ storage-3-2
1022+
+ storage-4-1
1023+
+ storage-4-2
1024+
- router-3
1025+
- storage-1-3
1026+
- storage-2-3
1027+
Hosts changes:
1028+
- server-3
1029+
---
1030+
Upgrade: --from-latest-state --new tests/resources/cluster-new-v4.genin.yml -f
1031+
State file: .geninstate/14a3a6c82ec93b6a7e87bc09e086e42cdbca97c5ed158624054265e30036cbeb.gz
1032+
Topology changes:
1033+
- storage-3-1
1034+
- storage-3-2
1035+
- storage-3-3
1036+
- router-4
1037+
- storage-1-4
1038+
- storage-2-4
1039+
- storage-3-4
1040+
Hosts changes:
1041+
- server-4
1042+
```
1043+
1044+
To perform an `upgrade` based on `state` (that is, based on a previous `upgrade`), you can:
1045+
- Pass the path to the file with the state to the `--old` argument.
1046+
```shell
1047+
genin upgrade --old .geninstate/14a3a6c82ec93b6a7e87bc09e086e42cdbca97c5ed158624054265e30036cbeb.gz --new cluster-new-new.genin.yml
1048+
```
1049+
- Replace `--old` argument with `--from-latest-state`.
1050+
```shell
1051+
genin upgrade --from-latest-state --new cluster-new-new.genin.yml
1052+
```
1053+
1054+
Also, in some cases it may be convenient to save the entire `geninstate` somewhere in one
1055+
directory. This can be done with the `--state-dir` argument or by setting the `GENIN_STATE_DIR`
1056+
environment variable.
1057+
1058+
The `--export-state` argument can be useful for keeping the upgrade state under some by another
1059+
name.
1060+
7271061
## Building from sources
7281062
7291063
At first, you need to clone the source code.

0 commit comments

Comments
 (0)