TrueCloudLab/frostfs-node
21
1
Fork 27
Code Issues 105 Pull requests 4 Projects Releases 2 Activity Actions 10

[#841] doc: Describe epoch
All checks were successful
DCO action / DCO (pull_request) Successful in 4m50s
Details
Vulncheck / Vulncheck (pull_request) Successful in 5m28s
Details
Build / Build Components (1.21) (pull_request) Successful in 7m6s
Details
Build / Build Components (1.20) (pull_request) Successful in 7m15s
Details
Tests and linters / Staticcheck (pull_request) Successful in 4m19s
Details
Tests and linters / Lint (pull_request) Successful in 5m32s
Details
Tests and linters / Tests (1.20) (pull_request) Successful in 10m14s
Details
Tests and linters / Tests with -race (pull_request) Successful in 10m22s
Details
Tests and linters / Tests (1.21) (pull_request) Successful in 10m27s
Details

Browse source 
Signed-off-by: Anton Nikiforov <an.nikiforov@yadro.com>
This commit is contained in:
Anton Nikiforov 2023-12-05 11:18:25 +03:00
parent 9d51142696
commit 05249e6c6b
1 changed files with 43 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
docs/epoch.md Normal file
View file

@ -0,0 +1,43 @@
# Epoch
The main purpose of the `epoch` in `frostfs` environment is to manipulate `netmap`.
Each new epoch, `ir` service trigger revision content of the `netmap` by adding or removing nodes to or from it.
`node` service trigger few internal processes each new epoch - for example, running GC.
Epoch also used in an object lifecycle.
At the startup, `ir` service initializes an epoch timer which handles new epoch tick.
Epoch timer is a block timer - which means that this timer ticks each block or set of blocks.
The epoch duration stores in the configurable parameter `EpochDuration` in the blockchain.
It is possible to get it via `frostfs-adm`:
```shell
> frostfs-adm morph dump-config -c config.yml -r http://morph-chain.frostfs.devenv:30333
...
EpochDuration: 240 (int)
...
>
```
Once epoch timer ticks, `ir` service call method [NewEpoch](https://git.frostfs.info/TrueCloudLab/frostfs-contract/src/commit/a1b61d3949581f4d65b0d32a33d98ba9c193dc2a/netmap/netmap_contract.go#L238)
of the `netmap` contract. Each `ir` instance can do this at the same time, but it is not an issue,
because multiple call of this method with the same set of parameters will give us the same result.
Utility `frostfs-adm` have a command to trigger new epoch:
```shell
> frostfs-adm morph force-new-epoch -c config.yml -r http://morph-chain.frostfs.devenv:30333
```
Command goes directly to the `netmap` contract and call method `NewEpoch`.
Method checks alphabet witness and stores candidates nodes which are not in the `OFFLINE` state as a current netmap.
Then executes method `NewEpoch` in `balance` and `container` contracts.
At the end it produces notification `NewEpoch` which is handled by `node` and `ir` services.
`ir` handler for `NewEpoch` updates internal state of the netmap, if it is necessary, updates state of the nodes or
marks for exclusion from netmap in the blockchain.
`node` handler for `NewEpoch` executes method `addPeer` of the `netmap` contract.
This method do nothing, but produces notification which handled by `ir` service.
`ir` in handler for `AddPeer` may update node state in the netmap if it is necessary.
At the startup, node bootstraps with state `ONLINE`. From the online state, it is possible to move to `MAINTENANCE` or `OFFLINE`.
Node moved to `OFFLINE` state automatically, when there is no bootstrap request from it for a number of epochs.
This number stored in the `ir` config `netmap_cleaner.threshold`.
From `OFFLINE` state node, once it bootstrapped, moves to `ONLINE`.
`MAINTENANCE` state persists even if node rebooted or unavailable for a few epochs.