diff --git a/Dockerfile b/Dockerfile index 613636e3d..cc5e5ad96 100644 --- a/Dockerfile +++ b/Dockerfile @@ -6,7 +6,6 @@ FROM debian:12 AS build ENV OBS_REPO=knot-resolver-latest ENV DISTROTEST_REPO=Debian_12 - RUN apt-get update -qq && \ apt-get -qqq -y install \ apt-transport-https ca-certificates wget \ @@ -25,10 +24,19 @@ RUN cd /source && \ git submodule update --init --recursive && \ git config --global user.name "Docker Build" && \ git config --global user.email docker-build@knot-resolver && \ + \ + # Replace 'knot-resolver' user and group with 'root' + # in meson_options.tx and python/knot_resolver/constants.py. + # This is needed for the file/directory permissions validation + # and then for the proper functioning of the resolver. + sed s/knot-resolver/root/g -i meson_options.txt && \ + sed 's/USER.*/USER = "root"/g' -i python/knot_resolver/constants.py && \ + sed 's/GROUP.*/GROUP = "root"/g' -i python/knot_resolver/constants.py && \ + git commit -a -m TMP && \ + \ /root/.local/bin/apkg build-dep -y && \ /root/.local/bin/apkg build - # Real container FROM debian:12-slim AS runtime @@ -56,10 +64,9 @@ RUN apt-get install -y /pkg/*/*.deb && \ apt-get remove -y -qq curl gnupg2 && \ apt-get autoremove -y && \ apt-get clean && \ - rm -rf /var/lib/apt/lists/* && \ - mkdir /config + rm -rf /var/lib/apt/lists/* -COPY etc/config/config.example.docker.yaml /config/config.yaml +COPY etc/config/config.example.docker.yaml /etc/knot-resolver/config.yaml LABEL cz.knot-resolver.vendor="CZ.NIC" LABEL maintainer="knot-resolver-users@lists.nic.cz" @@ -67,5 +74,10 @@ LABEL maintainer="knot-resolver-users@lists.nic.cz" # Export plain DNS, DoT, DoH and management interface EXPOSE 53/UDP 53/TCP 443/TCP 853/TCP 5000/TCP +# Prepare shared config +VOLUME /etc/knot-resolver +# Prepare shared cache +VOLUME /var/cache/knot-resolver + ENTRYPOINT ["/usr/bin/knot-resolver"] -CMD ["-c", "/config/config.yaml"] +CMD ["-c", "/etc/knot-resolver/config.yaml"] diff --git a/NEWS b/NEWS index 8d19f9373..4339ce1c4 100644 --- a/NEWS +++ b/NEWS @@ -1,16 +1,12 @@ Knot Resolver 6.0.9 (2024-mm-dd) ================================ -Incompatible changes --------------------- -- -f/--forks is removed (#631, !1602) - Improvements ------------ - manager: secret for TLS session resumption via ticket (RFC5077) (!1567) - The manager creates and sets the secret for all running 'kresd' workers. + The manager creates and sets the secret for all running ``kresd`` workers. The secret is created automatically if the user does not configure their own secret in the configuration. This means that the workers will be able to resume each other's TLS sessions, regardless of whether the user has configured it to do so. @@ -20,6 +16,10 @@ Improvements - extended_errors: answer with EDE in more cases (!1585, !1588, !1590, !1592) - local-data: make DNAMEs work, i.e. generate CNAMEs (!1609) - daemon: use connected UDP sockets by default (#326, !1618) +- docker: multiplatform builds (#922, !1623) +- docker: shared VOLUMEs are prepared for configuration and cache (!1625, !1627) + + Configuration path was changed to standard ``/etc/knot-resolver/config.yaml``. Bugfixes -------- @@ -29,6 +29,7 @@ Bugfixes Incompatible changes -------------------- +- -f/--forks is removed (#631, !1602) - gnutls < 3.4 support is dropped, released over 9 years ago (!1601) - libuv < 1.27 support is dropped, released over 5 years ago (!1618) @@ -40,8 +41,8 @@ Security -------- - reduce buffering of transmitted data, especially TCP-based in userspace Also expose some of the new tweaks in lua: - (require 'ffi').C.the_worker.engine.net.tcp.user_timeout = 1000 - (require 'ffi').C.the_worker.engine.net.listen_{tcp,udp}_buflens.{snd,rcv} + - (require 'ffi').C.the_worker.engine.net.tcp.user_timeout = 1000 + - (require 'ffi').C.the_worker.engine.net.listen_{tcp,udp}_buflens.{snd,rcv} Packaging --------- @@ -69,12 +70,11 @@ Improvements ------------ - TLS (DoT, DoH): respect crypto policy overrides in OS (!1526) - manager: export metrics to JSON via management HTTP API (!1527) - * JSON is the new default metrics output format - * the ``prometheus-client`` Python package is now an optional dependency, - required only for Prometheus export to work + - JSON is the new default metrics output format + - the ``prometheus-client`` Python package is now an optional dependency, required only for Prometheus export to work - cache: prefetching records - * predict module: prefetching expiring records moved to prefetch module - * prefetch module: new module to prefetch expiring records + - predict module: prefetching expiring records moved to prefetch module + - prefetch module: new module to prefetch expiring records - stats: add separate metrics for IPv6 and IPv4 (!1545) - add the fresh DNSSEC root key "KSK-2024" already, Key ID 38696 (!1556) - manager: policy-loader: new component for separate loading of policy rules (!1540) diff --git a/doc/user/deployment-docker.rst b/doc/user/deployment-docker.rst index 462ab061d..42f5503b3 100644 --- a/doc/user/deployment-docker.rst +++ b/doc/user/deployment-docker.rst @@ -2,20 +2,67 @@ Docker ****** - .. note:: - Before version 6, our Docker images were not meant to be used in production. This is no longer the case and with the introduction of ``kres-manager``, Knot Resolver runs in containers without any issues. + Before version 6, our Docker images were not intended for production use due to the lack of ``systemd`` in Docker and + the inability to manage the multiple independent parts of the resolver. + This is no longer the case since the introduction of the Manager that automatically control other parts of the resolver. + +Knot Resolver official Docker image can be found at `Docker Hub `_. +First you can try running the container in interactive mode. + +.. code-block:: bash + + $ docker run --rm -ti --network host docker.io/cznic/knot-resolver:6 -An official Docker image can be found on `Docker Hub `_. The image contains Knot Resolver as if it was installed from our official distro packages. +For more robust deployments you will also probably need to configure network, for that see `Docker networking `_. + +Now you can try sending a query to the resolver using `kdig `_. .. code-block:: bash - docker run --rm -ti -P docker.io/cznic/knot-resolver + $ kdig example.com @127.0.0.1 + $ kdig nic.cz @127.0.0.1#443 +https -The configuration file is located at ``/etc/knot-resolver/config.yaml`` and the cache is at ``/var/cache/knot-resolver``. We recommend configuring a persistent cache across container restarts. +The image contains full Knot Resolver installation, so there shouldn't be much difference between running it natively and running it in a container. +The configuration file is located at ``/etc/knot-resolver/config.yaml`` and the cache is at ``/var/cache/knot-resolver``. +Please do not change these and other paths (rundir) as you may break things inside the container. .. warning:: - While the container image contains normal installation of Knot Resolver and there shouldn't be any differences between running it natively and in a container, we (the developers) do not have any experience using the Docker image in production. Especially, beware of running the DNS resolver with a software defined network (i.e. in Kubernetes). There will likely be some performance penalties for doing so. We haven't done any measurements comparing different types of installations so we don't know the performance differences. If you have done some measurements yourself, please reach out to us and we will share it here with everyone else. - \ No newline at end of file + Beware of running the container with a software defined network (i.e. in Kubernetes). + This will likely to result in some performance losses. + We haven't done any measurements comparing different types of installations so we don't know the performance differences. + If you have done your own measurements yourself, please contact us and we will share it with everyone else. + +------ +Config +------ + +We recommend persistent configuration across container restarts, +for more see `Docker persisting container data `_. + +.. code-block:: bash + + $ docker volume create config + $ docker run --rm -ti --network host -v config:/etc/knot-resolver docker.io/cznic/knot-resolver:6 + +After a configuration change there is no need to restart the entire container, just tell the resolver to reload the configuration. +Get ``CONTAINER_ID`` using the ``docker ps`` command or give your container name with the ``--name`` argument at container startup. + +.. code-block:: bash + + $ docker exec -it CONTANER_ID kresctl reload + +----- +Cache +----- + +You can also use persistent volume for the cache, but sharing it between more containers requires special option ``--pid=host``. +This is caused by the LMDB's reliance on unique PID numbers, see `issue #637 `_ for more information. +It is also good to mount the cache on ``tmpfs`` (semi-persistent), otherwise it will not work well under heavy load. + +.. code-block:: bash + + $ docker volume create --opt type=tmpfs --opt device=tmpfs cache + $ docker run --rm -ti --pid=host --network host -v cache:/var/cache/knot-resolver docker.io/cznic/knot-resolver:6 diff --git a/scripts/Makefile.docker b/scripts/Makefile.docker new file mode 100644 index 000000000..71908e058 --- /dev/null +++ b/scripts/Makefile.docker @@ -0,0 +1,48 @@ +# Based on https://netfuture.ch/2020/05/multi-arch-docker-image-easy/ +# +# Example: make -f Makefile.docker docker-multiarch + +REGISTRY = cznic +BASETAG = ${REGISTRY}/knot-resolver +PLATFORMS = linux/amd64,linux/arm/v7,linux/arm64/v8 + +RELEASE = $(shell git describe --abbrev=0 --exact-match) +RELTAG = $(shell [ -n "${RELEASE}" ] && echo "-t ${BASETAG}:${RELEASE}" || echo "") + +BUILDXDETECT = ${HOME}/.docker/cli-plugins/docker-buildx +QEMUDETECT = /proc/sys/fs/binfmt_misc/qemu-m68k + +# https://stackoverflow.com/a/324782 +ROOT_DIR:=$(dir $(realpath $(lastword $(MAKEFILE_LIST))))/.. + +docker-multiarch: qemu buildx docker-multiarch-builder + docker login + docker buildx build --no-cache --builder docker-multiarch --pull --push \ + --platform ${PLATFORMS} ${RELTAG} ${ROOT_DIR} + +qemu: ${QEMUDETECT} +${QEMUDETECT}: + docker pull multiarch/qemu-user-static + docker run --privileged multiarch/qemu-user-static --reset -p yes + docker ps -a | sed -n 's, *multiarch/qemu-user-static.*,,p' \ + | (xargs docker rm 2>&1 || \ + echo "Cannot remove docker container on ZFS; retry after next reboot") \ + | grep -v 'dataset is busy' + +buildx: ${BUILDXDETECT} +${BUILDXDETECT}: + @echo +# Output of `uname -m` is too different + @echo '*** `docker buildx` missing. Install binary for this machine architecture' + @echo '*** from `https://github.com/docker/buildx/releases/latest`' + @echo '*** to `~/.docker/cli-plugins/docker-buildx` and `chmod +x` it.' + @echo + @exit 1 + +docker-multiarch-builder: qemu buildx + if ! docker buildx ls | grep -w docker-multiarch > /dev/null; then \ + docker buildx create --name docker-multiarch && \ + docker buildx inspect --builder docker-multiarch --bootstrap; \ + fi + +.PHONY: qemu buildx docker-multiarch docker-multiarch-builder \ No newline at end of file