Skip to content

Commit 486d377

Browse files
ParaphraserParaphraser
committed
20211002 MariaDB health check - master branch - PR 1 of 3
Follows on from suggestion in [Issue 415](#415) to add health-check to more containers. See also [PR 406](dbb6217). Changes: * Adds `iotstack_healthcheck.sh` script to template. * Adds commands to Dockerfile to copy that script into the local image and activate health-checking on launch. * Describes health-check functionality in the MariaDB documentation. * References MariaDB health-check documentation in NextCloud documentation.
1 parent 651a30b commit 486d377

File tree

4 files changed

+148
-0
lines changed

4 files changed

+148
-0
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: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
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+
RESPONSE=$(mysqladmin -p${MYSQL_ROOT_PASSWORD} ping -h localhost)
12+
13+
# did the mysqladmin command succeed?
14+
if [ $? -eq 0 ] ; then
15+
16+
# yes! is the response as expected?
17+
if [ "$RESPONSE" = "$EXPECTED" ] ; then
18+
19+
# yes! this could still be a false positive so probe the port
20+
if nc -w 1 localhost $HEALTHCHECK_PORT >/dev/null 2>&1; then
21+
22+
# port responding - that defines healthy
23+
exit 0
24+
25+
fi
26+
27+
fi
28+
29+
fi
30+
31+
# otherwise the check fails
32+
exit 1

‎docs/Containers/MariaDB.md

Lines changed: 98 additions & 0 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

@@ -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
@@ -262,6 +262,12 @@ You can silence the warning by editing the Nextcloud service definition in `dock
262262

263263
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.
264264

265+
## <a name="healthCheck"> Container health check </a>
266+
267+
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.
268+
269+
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.
270+
265271
## <a name="updatingNextcloud"> Keeping Nextcloud up-to-date </a>
266272

267273
To update the `nextcloud` container:

0 commit comments

Comments
 (0)