Skip to content

Commit 5ba4bb9

Browse files
SlykeSlyke
authored
Merge pull request #416 from Paraphraser/20211002-mariadb-healthcheck-master
20211002 MariaDB health check - master branch - PR 1 of 3
2 parents 3192719 + d52de72 commit 5ba4bb9

File tree

4 files changed

+156
-2
lines changed

4 files changed

+156
-2
lines changed

‎.templates/mariadb/Dockerfile

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,16 @@ RUN sed -i.bak \
1010
-e "s/^read_buffer_size/# read_buffer_size/" \
1111
/defaults/my.cnf
1212

13+
# copy the health-check script into place
14+
ENV HEALTHCHECK_SCRIPT "iotstack_healthcheck.sh"
15+
COPY ${HEALTHCHECK_SCRIPT} /usr/local/bin/${HEALTHCHECK_SCRIPT}
16+
17+
# define the health check
18+
HEALTHCHECK \
19+
--start-period=30s \
20+
--interval=30s \
21+
--timeout=10s \
22+
--retries=3 \
23+
CMD ${HEALTHCHECK_SCRIPT} || exit 1
24+
1325
# EOF

‎.templates/mariadb/iotstack_healthcheck.sh

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#!/usr/bin/env sh
2+
3+
# set a default for the port
4+
# (refer https://mariadb.com/kb/en/mariadb-environment-variables/ )
5+
HEALTHCHECK_PORT="${MYSQL_TCP_PORT:-3306}"
6+
7+
# the expected response is?
8+
EXPECTED="mysqld is alive"
9+
10+
# run the check
11+
if [ -z "$MYSQL_ROOT_PASSWORD" ] ; then
12+
RESPONSE=$(mysqladmin ping -h localhost)
13+
else
14+
# note - there is NO space between "-p" and the password. This is
15+
# intentional. It is part of the mysql and mysqladmin API.
16+
RESPONSE=$(mysqladmin -p${MYSQL_ROOT_PASSWORD} ping -h localhost)
17+
fi
18+
19+
# did the mysqladmin command succeed?
20+
if [ $? -eq 0 ] ; then
21+
22+
# yes! is the response as expected?
23+
if [ "$RESPONSE" = "$EXPECTED" ] ; then
24+
25+
# yes! this could still be a false positive so probe the port
26+
if nc -w 1 localhost $HEALTHCHECK_PORT >/dev/null 2>&1; then
27+
28+
# port responding - that defines healthy
29+
exit 0
30+
31+
fi
32+
33+
fi
34+
35+
fi
36+
37+
# otherwise the check fails
38+
exit 1

‎docs/Containers/MariaDB.md

Lines changed: 100 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
## Source
2+
23
* [Docker hub](https://hub.docker.com/r/linuxserver/mariadb/)
34
* [Webpage](https://mariadb.org/)
45

@@ -38,10 +39,10 @@ You only get the opportunity to change the `MQSL_` prefixed environment variable
3839
$ docker-compose rm --force --stop -v mariadb
3940
$ sudo rm -rf ./volumes/mariadb
4041
```
41-
42+
4243
* Edit `docker-compose.yml` and change the variables.
4344
* Bring up the container:
44-
45+
4546
```
4647
$ docker-compose up -d mariadb
4748
```
@@ -63,6 +64,103 @@ To close the terminal session, either:
6364
* type "exit" and press <kbd>return</kbd>; or
6465
* press <kbd>control</kbd>+<kbd>d</kbd>.
6566

67+
## <a name="healthCheck"> Container health check </a>
68+
69+
### <a name="healthCheckTheory"> theory of operation </a>
70+
71+
A script , or "agent", to assess the health of the MariaDB container has been added to the *local image* via the *Dockerfile*. In other words, the script is specific to IOTstack.
72+
73+
The agent is invoked 30 seconds after the container starts, and every 30 seconds thereafter. The agent:
74+
75+
1. Runs the command:
76+
77+
```
78+
mysqladmin ping -h localhost
79+
```
80+
81+
2. If that command succeeds, the agent compares the response returned by the command with the expected response:
82+
83+
```
84+
mysqld is alive
85+
```
86+
87+
3. If the command returned the expected response, the agent tests the responsiveness of the TCP port the `mysqld` daemon should be listening on (see [customising health-check](#healthCheckCustom)).
88+
89+
4. If all of those steps succeed, the agent concludes that MariaDB is functioning properly and returns "healthy".
90+
91+
### <a name="healthCheckMonitor"> monitoring health-check </a>
92+
93+
Portainer's *Containers* display contains a *Status* column which shows health-check results for all containers that support the feature.
94+
95+
You can also use the `docker ps` command to monitor health-check results. The following command narrows the focus to mariadb:
96+
97+
```bash
98+
$ docker ps --format "table {{.Names}}\t{{.Status}}" --filter name=mariadb
99+
```
100+
101+
Possible reply patterns are:
102+
103+
1. The container is starting and has not yet run the health-check agent:
104+
105+
```
106+
NAMES STATUS
107+
mariadb Up 5 seconds (health: starting)
108+
```
109+
110+
2. The container has been running for at least 30 seconds and the health-check agent has returned a positive result within the last 30 seconds:
111+
112+
```
113+
NAMES STATUS
114+
mariadb Up 33 seconds (healthy)
115+
```
116+
117+
3. The container has been running for more than 90 seconds but has failed the last three successive health-check tests:
118+
119+
```
120+
NAMES STATUS
121+
mariadb Up About a minute (unhealthy)
122+
```
123+
124+
### <a name="healthCheckCustom"> customising health-check </a>
125+
126+
You can customise the operation of the health-check agent by editing the `mariadb` service definition in your *Compose* file:
127+
128+
1. By default, the `mysqld` daemon listens to **internal** port 3306. If you need change that port, you also need to inform the health-check agent via an environment variable. For example, suppose you changed the **internal** port to 12345:
129+
130+
```yaml
131+
environment:
132+
- MYSQL_TCP_PORT=12345
133+
```
134+
135+
Notes:
136+
137+
* The `MYSQL_TCP_PORT` variable is [defined by MariaDB](https://mariadb.com/kb/en/mariadb-environment-variables/), not IOTstack, so changing this variable affects more than just the health-check agent.
138+
* If you are running "old menu", this change should be made in the file:
139+
140+
```
141+
~/IOTstack/services/mariadb/mariadb.env
142+
```
143+
144+
2. The `mysqladmin ping` command relies on the root password supplied via the `MYSQL_ROOT_PASSWORD` environment variable in the *Compose* file. The command will not succeed if the root password is not correct, and the agent will return "unhealthy".
145+
146+
3. If the health-check agent misbehaves in your environment, or if you simply don't want it to be active, you can disable all health-checking for the container by adding the following lines to its service definition:
147+
148+
```yaml
149+
healthcheck:
150+
disable: true
151+
```
152+
153+
Note:
154+
155+
* The mere presence of a `healthcheck:` clause in the `mariadb` service definition overrides the supplied agent. In other words, the following can't be used to re-enable the supplied agent:
156+
157+
```yaml
158+
healthcheck:
159+
disable: false
160+
```
161+
162+
You must remove the entire `healthcheck:` clause.
163+
66164
## Keeping MariaDB up-to-date
67165

68166
To update the `mariadb` container:

‎docs/Containers/NextCloud.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,12 @@ You can silence the warning by editing the Nextcloud service definition in `dock
263263

264264
Nextcloud traffic is not encrypted. Do **not** expose it to the web by opening a port on your home router. Instead, use a VPN like Wireguard to provide secure access to your home network, and let your remote clients access Nextcloud over the VPN tunnel.
265265

266+
## <a name="healthCheck"> Container health check </a>
267+
268+
A script , or "agent", to assess the health of the MariaDB container has been added to the *local image* via the *Dockerfile*. In other words, the script is specific to IOTstack.
269+
270+
Because it is an instance of MariaDB, Nextcloud_DB inherits the health-check agent. See the [IOTstack MariaDB](https://sensorsiot.github.io/IOTstack/Containers/MariaDB/) documentation for more information.
271+
266272
## <a name="updatingNextcloud"> Keeping Nextcloud up-to-date </a>
267273

268274
To update the `nextcloud` container:

0 commit comments

Comments
 (0)