diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index d182eb6f..fb1f6229 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -11,6 +11,7 @@ - [Building images](building/guidance.md) - [Users, groups, SSH keys](building/users-and-groups.md) - [Secrets](building/secrets.md) +- [Management Services](building/management-services.md) # Using bootc diff --git a/docs/src/building/management-services.md b/docs/src/building/management-services.md new file mode 100644 index 00000000..1740c8bc --- /dev/null +++ b/docs/src/building/management-services.md @@ -0,0 +1,51 @@ +# Management services + +When running a fleet of systems, it is common to use a central management service. Commonly, these services provide a client to be installed on each system which connects to the central service. Often, the management service requires the client to perform a one time registration. + +The following example shows how to install the client into a bootc image and run it at startup to register the system. This example assumes the management-client handles future connections to the server, e.g. via a cron job or a separate systemd service. This example could be modified to create a persistent systemd service if that is required. The Containerfile is not optimized in order to more clarly explain each step, e.g. it's generally better to invoke RUN a single time to avoid creating multiple layers in the image. + +```Dockerfile +FROM + +# Typically when using a management service, it will determine when to upgrade the system. +# So, disable bootc-fetch-apply-updates.timer if it is included in the base image. +RUN systemctl disable bootc-fetch-apply-updates.timer + +# Install the client from dnf, or some other method that applies for your client +RUN dnf install management-client -y && dnf clean all + +# Bake the credentials for the management service into the image +ARG activation_key= + +# The existence of .run_next_boot acts as a flag to determine if the +# registration is required to run when booting +RUN touch /etc/management-client/.run_next_boot + +COPY <<"EOT" /usr/lib/systemd/system/management-client.service +[Unit] +Description=Run management client at boot +After=network-online.target +ConditionPathExists=/etc/management-client/.run_client_next_boot + +[Service] +Type=oneshot +EnvironmentFile=/etc/management-client/.credentials +ExecStart=/usr/bin/management-client register --activation-key ${CLIENT_ACTIVATION_KEY} +ExecStartPre=/bin/rm -f /etc/management-client/.run_next_boot +ExecStop=/bin/rm -f /etc/management-client/.credentials + +[Install] +WantedBy=multi-user.target +EOT + +# Link the service to run at startup +RUN ln -s /usr/lib/systemd/system/management-client.service /usr/lib/systemd/system/multi-user.target.wants/management-client.service + +# Store the credentials in a file to be used by the systemd service +RUN echo -e "CLIENT_ACTIVATION_KEY=${activation_key}" > /etc/management-client/.credentials + +# Set the flag to enable the service to run one time +# The systemd service will remove this file after the registration completes the first time +RUN touch /etc/management-client/.run_next_boot +``` +