Skip to content

Commit be20cf9

Browse files
maru-avamaru-ava
committed
fixup: More README cleanup
1 parent 054e021 commit be20cf9

File tree

1 file changed

+49
-44
lines changed

1 file changed

+49
-44
lines changed

‎tests/fixture/bootstrapmonitor/README.md

Lines changed: 49 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,9 @@ To enable, supply `state-sync-enabled: false` as C-Chain configuration.
3131

3232
## Overview
3333

34-
The intention of `bootstrap-monitor` is to enable a `StatefulSet` to
35-
perform continous bootstrap testing for a given avalanchego
34+
The intention of `bootstrap-monitor` is to enable a Kubernetes
35+
[StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/)
36+
to perform continous bootstrap testing for a given avalanchego
3637
configuration. It ensures that a testing pod either starts or resumes
3738
a test, and upon completion of a test, polls for a new image to test
3839
and initiates a new test when one is found.
@@ -62,13 +63,17 @@ and initiates a new test when one is found.
6263
- Both the `init` and `wait-for-completion` commands of the
6364
`bootstrap-monitor` attempt to read serialized test details (namely
6465
the image used for the test and the start time of the test) from
65-
the same data volume used by the avalanchego node.
66-
- The `bootstrap-monitor init` command is intended to run as as the
67-
an init container of an avalanchego node and ensure that the ID of
68-
the image and its associated versions are recorded for the test and
69-
that the contents of the pod's data volume is either cleared for a
70-
new test or retained to enable resuming a previously started
71-
test. It accomplishes this by:
66+
the same data volume used by the avalanchego node. These details
67+
are written by the `init` command when it determines that new test
68+
is starting.
69+
- The `bootstrap-monitor init` command is intended to run as as an
70+
[init
71+
container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)
72+
of an avalanchego node and ensure that the ID of the image and its
73+
associated versions are recorded for the test and that the contents
74+
of the pod's data volume is either cleared for a new test or
75+
retained to enable resuming a previously started test. It
76+
accomplishes this by:
7277
- Mounting the same data volume as the avalanchego node
7378
- Reading bootstrap test configuration as described previously
7479
- Determining the image ID and versions for an image if the
@@ -77,26 +82,25 @@ and initiates a new test when one is found.
7782
`StatefulSet` runs. Subsequent pods from the same `StatefulSet`
7883
should have an image qualified with its SHA and version details
7984
set by the previous test run's `wait-for-completion` pod.
80-
- A new pod will be started with with the `latest` image to
81-
execute `avalanchego --versions-json` to determine the exact
82-
version of the image and update the `StatefulSet` managing the
83-
pod which will prompt a pod restart. This ensures both that a
84-
test result can be associated with a specific image SHA and the
85-
avalanchego versions (including commit hash) of the binary that
86-
the image provides.
85+
- A new pod will be started with the `latest` image to execute
86+
`avalanchego --versions-json` to determine the image ID (which
87+
includes a sha256 hash) of the image and its avalanchego
88+
versions. Those values will then be applied to the `StatefulSet`
89+
managing the pod which will prompt pod deletion and recreation
90+
with the updated values. This ensures that a test result can be
91+
associated with both a specific image SHA and the avalanchego
92+
versions (including commit hash) of the binary that the image
93+
provides.
8794
- A separate pod is used because the image ID of a non-init
8895
avalanchego container using a `latest`-tagged image is only
8996
available when that container runs rather than when an init container runs.
9097
- While it would be possible to add an init container running the
9198
same avalanchego image as the primary avalanchego container,
92-
have it run the version command, and then have the
93-
`bootstrap-monitor init` container read those results, the
94-
method of discoverying the versions and image of the
95-
avalanchego image currently tagged with `latest` would still be
96-
required by the `wait-for-completion` command (described in a
97-
subsequent section) to enable discovery of a new image to
98-
test. It seemed preferable to have only a single way to
99-
discover image details.
99+
have it run the version command, and then have a subsequent
100+
`bootstrap-monitor init` container read those results, the use
101+
of a separate pod for SHA and versions discovery would still be
102+
required by the `wait-for-completion` command. It seemed
103+
preferable to have only a single way to discover image details.
100104
- Attempting to read the serialized test details from a file on the
101105
data volume. This file will not exist if the data volume has not
102106
been used before.
@@ -105,38 +109,39 @@ and initiates a new test when one is found.
105109
- If the images differ (or the file was not present), the data
106110
volume is initialized for a new test:
107111
- The data volume is cleared
108-
- The image from the test configuration and and time are written to the data volume
112+
- The image from the test configuration and and time are
113+
serialized to a file on the data volume
109114
- If the images are the same, the data volume is used as-is to
110-
enable resuming the in-progress test.
115+
enable resuming an in-progress test.
111116
- `bootstrap-monitor wait-for-completion` is intended to run as a
112117
sidecar of the avalanchego container. It polls the health of the
113118
node container to detect when a bootstrap test has completed
114119
successfully, then polls for a new image to test and when one is
115-
found, updates the managing `StatefulSet` with that image to
116-
trigger the start of a new test. The process to detect a new image
117-
is the same as was described for the `init` command.
120+
found, updates the managing `StatefulSet` with the details of that
121+
image to trigger a new test. The process to detect a new image is
122+
the same as was described for the `init` command.
118123

119124
## Package details
120125

121-
| Filename | Purpose |
122-
|:-------------------------|:-----------------------------------------------------------------------|
123-
| bootstrap_test_config.go | Defines how the configuration for a bootstrap test is read from a pod. |
124-
| common.go | Defines code common between init and wait |
125-
| init.go | Defines how a bootstrap test is initialized |
126-
| wait.go | Defines the loop that waits for completion of a bootstrap test |
127-
| cmd/main.go | The binary entrypoint for the bootstrap-monitor |
128-
| e2e/e2e_test.go | The e2e test that validates the bootstrap-monitor |
126+
| Filename | Purpose |
127+
|:-------------------------|:--------------------------------------------------------------------------------------------|
128+
| bootstrap_test_config.go | Defines how the configuration for a bootstrap test is read from a pod. |
129+
| common.go | Defines code common between init and wait |
130+
| init.go | Defines how a bootstrap test is initialized |
131+
| wait.go | Defines how a bootstrap test is determined to have completed and how a new one is initiated |
132+
| cmd/main.go | The binary entrypoint for the `bootstrap-monitor` |
133+
| e2e/e2e_test.go | The e2e test that validates `bootstrap-monitor` |
129134

130135
## Supporting files
131136

132137
| Filename | Purpose |
133138
|:-----------------------------------------|:--------------------------------------------------|
134-
| scripts/build_bootstrap_monitor.sh | Builds the bootstrap-monitor binary |
135-
| scripts/build_bootstrap_monitor_image.sh | Builds the image for the bootstrap-monitor |
136-
| scripts/tests.e2e.bootstrap_monitor.go | Script for running the bootstrap-monitor e2e test |
139+
| scripts/build_bootstrap_monitor.sh | Builds the `bootstrap-monitor` binary |
140+
| scripts/build_bootstrap_monitor_image.sh | Builds the image for the `bootstrap-monitor` |
141+
| scripts/tests.e2e.bootstrap_monitor.go | Script for running the `bootstrap-monitor` e2e test |
137142

138-
- The test script is used by the primary github action workflow to
139-
validate the `bootstrap-monitor` binary and image.
143+
- The test script is used by the github action workflow that
144+
validates the `bootstrap-monitor` binary and image.
140145
- The image build script is used by the github action workflow that
141146
publishes repo images post-merge.
142147

@@ -160,8 +165,8 @@ image with a `latest` tag, the pod would continously bootstrap, exit,
160165
and restart with the current latest image. While appealingly simple,
161166
this approach doesn't directly support:
162167

163-
- a mechanism for resuming a long-running bootstrap. Given the
168+
- A mechanism for resuming a long-running bootstrap. Given the
164169
expected duration of a bootstrap test, and the fact that a workload on
165170
Kubernetes is not guaranteed to run without interruption, a separate
166171
init process is suggested to enable resumption of an interrupted test.
167-
- a mechanism for reporting disk usage and duration of execution
172+
- A mechanism for reporting disk usage and duration of execution

0 commit comments

Comments
 (0)