From fa645e7c81659b4be5463eadfcf5768d2df678b8 Mon Sep 17 00:00:00 2001 From: Yashodhan Pise Date: Wed, 2 Oct 2024 23:39:15 +0530 Subject: [PATCH] Documentation for general installation in containerized environments --- ...tallation-community-containerized.markdown | 236 ++++++++++++++++++ .../installation-community.markdown | 2 +- .../installation-coreos.markdown | 2 +- 3 files changed, 238 insertions(+), 2 deletions(-) create mode 100644 getting-started/installation/general-installation/installation-community-containerized.markdown diff --git a/getting-started/installation/general-installation/installation-community-containerized.markdown b/getting-started/installation/general-installation/installation-community-containerized.markdown new file mode 100644 index 000000000..bfa666223 --- /dev/null +++ b/getting-started/installation/general-installation/installation-community-containerized.markdown @@ -0,0 +1,236 @@ +--- +layout: default +title: Installing Community +published: true +sorting: 80 +--- + +These instructions describe how to download and install the latest version of CFEngine Community in a docker containerized environment using pre-compiled rpm packages for ubi9 images. + +It also provides instructions for the following: + +* **Install CFEngine on a policy server (hub) and on a Host (client).** +A Policy Server (hub) is a CFEngine instance that contains promises (business policy) that get deployed to Hosts. +Hosts are clients that retrieve and execute promises. +* **Bootstrap the policy server to itself and then bootstrap the Host(s) to the Policy Server.** +Bootstrapping establishes a trust relationship between the Policy Server +and all Hosts. Thus, business policy that you create in the Policy Server can be deployed to Hosts throughout your company. +Bootstrapping completes the installation process. + +
+This guide describes how to set up a client-server model with CFEngine and, through policy, manage both containers. +Docker contaiers will be created, one container to be the Policy Server (server), and another container that will be the Host Agent (client). +Both will will run ubi9 images and communicate on a container network. +Upon completion, you are ready to start working with CFEngine. + +## Requirements +* 1G+ disk space +* 1G+ memory +* Working [Docker Engine](https://docs.docker.com/engine/) or [Podman](https://podman.io/) setups on a supported [x86_64](https://en.wikipedia.org/wiki/X86-64) platform. + +**Note**: This document considers [Docker Engine](https://docs.docker.com/engine/) for all examples. +Use of [Podman](https://podman.io/) shall be similar with adequate adaptations +(_Ref_: [Emulating Docker CLI with Podman](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman)). + +## Overview +1. Installing container engine +2. Preparing CFEngine hub in container +3. Preparing CFEngine host in container +4. Using docker compose + 4.1. Preparing container image for CFEngine + 4.2. Using docker compose service +5. Supporting notes and references + 5.1. Enabling systemd for WSL + 5.2. References + +## Installing container engine +_Ref_: [Install Docker Engine](https://docs.docker.com/engine/install/) +OR +_Ref_: [Podman Installation Instructions](https://podman.io/docs/installation) +_Optionally_: [Emulating Docker CLI with Podman](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman) + +## Preparing CFEngine hub in container +1. Run the container with systemd + ``` + $ docker run --privileged -dit --name=cfengine-hub registry.access.redhat.com/ubi9-init /usr/sbin/init + ``` +2. Prepare the container for cfengine + ``` + $ docker exec cfengine-hub bash -c "dnf -y update; dnf -y install procps-ng iproute" + ``` +3. Install cfengine-community package + ``` + $ docker exec cfengine-hub bash -c "dnf -y install https://cfengine-package-repos.s3.amazonaws.com/community_binaries/Community-3.24.0/agent_rhel9_x86_64/cfengine-community-3.24.0-1.el9.x86_64.rpm" + ``` +4. Bootstrap cf-agent + ``` + $ docker exec cfengine-hub bash -c "/usr/local/sbin/cf-agent --bootstrap \$(ip -4 -o addr show eth0 | awk '{print \$4}' | cut -d'/' -f1)" + ``` + +## Preparing CFEngine host in container +1. Run the container with systemd + ``` + $ docker run --privileged -dit --name=cfengine-host registry.access.redhat.com/ubi9-init /usr/sbin/init + ``` +2. Prepare the container for cfengine + ``` + $ docker exec cfengine-host bash -c "dnf -y update; dnf -y install procps-ng iproute" + ``` +3. Install cfengine-community package + ``` + $ docker exec cfengine-host bash -c "dnf install -y https://cfengine-package-repos.s3.amazonaws.com/community_binaries/Community-3.24.0/agent_rhel9_x86_64/cfengine-community-3.24.0-1.el9.x86_64.rpm" + ``` +4. Bootstrap cf-agent to the policy server container + 4.1. Find ip of cfengine hub + ``` + $ CFENGINE_HUB_IP=$(docker exec cfengine-hub bash -c "ip -4 -o addr show eth0 | awk '{print \$4}' | cut -d'/' -f1") + ``` + 4.2. Bootstrap cfengine host to cfengine hub + ``` + $ docker exec cfengine-host bash -c "/usr/local/sbin/cf-agent --bootstrap ${CFENGINE_HUB_IP}" + ``` + +## Using docker compose +### Preparing container image for CFEngine +1. Create a `Dockerfile` with following contents: + ``` + FROM registry.access.redhat.com/ubi9-init:latest + LABEL container ubi9-init_cfengine-community-3.24.0.1 + + RUN dnf -y update \ + && dnf -y install bind-utils iproute procps-ng \ + && dnf -y install https://cfengine-package-repos.s3.amazonaws.com/community_binaries/Community-3.24.0/agent_rhel9_x86_64/cfengine-community-3.24.0-1.el9.x86_64.rpm + + HEALTHCHECK --interval=5s --timeout=15s --retries=3 \ + CMD /usr/local/sbin/cf-agent --self-diagnostics || exit 1 + + ENTRYPOINT ["/usr/sbin/init"] + ``` +2. Build the docker image based on above Dockerfile: + ``` + $ docker build -t cfengine:3.24.0-1 -f Dockerfile . + ``` +3. Verify created image + ``` + $ docker image ls cfengine + REPOSITORY TAG IMAGE ID CREATED SIZE + cfengine 3.24.0-1 About an hour ago 302MB + ``` +**Note**: One can optionally skip step 2 and 3 above, if planning to use `docker compose`. + +### Using docker compose service +1. Create a `compose.yml` file with following contents: + ``` + name: cfengine-demo + + services: + cfengine-hub: + container_name: cfengine-hub + image: cfengine:3.24.0-1 + build: + context: . + dockerfile: Dockerfile + privileged: true + command: + - /bin/sh + - -c + - | + /usr/local/sbin/cf-agent --bootstrap \$(ip -4 -o addr show eth0 | awk '{print \$4}' | cut -d'/' -f1) + networks: + - control-plane + + cfengine-host: + image: cfengine:3.24.0-1 + build: + context: . + dockerfile: Dockerfile + privileged: true + command: + - /bin/sh + - -c + - | + /usr/local/sbin/cf-agent --bootstrap \$(dig +short cfengine-hub|tr -d [:space:]) + networks: + - control-plane + depends_on: + cfengine-hub: + condition: service_healthy + required: true + + networks: + control-plane: + ``` +2. Start service cfengine-demo + ``` + $ docker compose -f compose.yaml --verbose up -d + ``` +3. Bootstrap hub and hosts + ``` + $ docker exec -it cfengine-hub bash -c "/usr/local/sbin/cf-agent --bootstrap \$(ip -4 -o addr show eth0 | awk '{print \$4}' | cut -d'/' -f1)" + R: Bootstrapping from host '192.168.16.2' via built-in policy '/var/cfengine/inputs/failsafe.cf' + R: This host assumes the role of policy server + R: Updated local policy from policy server + R: Triggered an initial run of the policy + R: Restarted systemd unit cfengine3 + notice: Bootstrap to '192.168.16.2' completed successfully! + ``` + ``` + $ docker exec -it cfengine-demo-cfengine-host-1 bash -c "/usr/local/sbin/cf-agent --bootstrap \$(dig +short cfengine-hub|tr -d [:space:])" + notice: Bootstrap mode: implicitly trusting server, use --trust-server=no if server trust is already established + notice: Trusting new key: MD5=2f406e11cfd3e08d810d77a186e204e2 + R: Bootstrapping from host '192.168.16.2' via built-in policy '/var/cfengine/inputs/failsafe.cf' + R: This autonomous node assumes the role of voluntary client + R: Updated local policy from policy server + R: Triggered an initial run of the policy + R: Restarted systemd unit cfengine3 + notice: Bootstrap to '192.168.16.2' completed successfully! + ``` +4. Health-check for hub and host + ``` + $ docker exec -it cfengine-hub bash -c "/usr/local/sbin/cf-agent --self-diagnostics" + self-diagnostics for agent using workdir '/var/cfengine' + self-diagnostics for agent using inputdir '/var/cfengine/inputs' + self-diagnostics for agent using logdir '/var/cfengine' + self-diagnostics for agent using statedir '/var/cfengine/state' + [ YES ] Check that agent is bootstrapped: 192.168.16.2 + [ YES ] Check if agent is acting as a policy server: Acting as a policy server + [ YES ] Check private key: OK at '/var/cfengine/ppkeys/localhost.priv' + [ YES ] Check public key: OK at '/var/cfengine/ppkeys/localhost.pub' + [ NO ] Check persistent classes DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/cf_state.lmdb' + [ NO ] Check checksums DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/checksum_digests.lmdb' + [ NO ] Check observations DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/cf_observations.lmdb' + [ NO ] Check file stats DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/stats.lmdb' + [ NO ] Check locks DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/cf_lock.lmdb' + [ NO ] Check performance DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/performance.lmdb' + [ NO ] Check lastseen DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/cf_lastseen.lmdb' + ``` + ``` + $ docker exec -it cfengine-demo-cfengine-host-1 bash -c "/usr/local/sbin/cf-agent --self-diagnostics" + self-diagnostics for agent using workdir '/var/cfengine' + self-diagnostics for agent using inputdir '/var/cfengine/inputs' + self-diagnostics for agent using logdir '/var/cfengine' + self-diagnostics for agent using statedir '/var/cfengine/state' + [ YES ] Check that agent is bootstrapped: 192.168.16.2 + [ NO ] Check if agent is acting as a policy server: Not acting as a policy server + [ YES ] Check private key: OK at '/var/cfengine/ppkeys/localhost.priv' + [ YES ] Check public key: OK at '/var/cfengine/ppkeys/localhost.pub' + [ NO ] Check persistent classes DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/cf_state.lmdb' + [ NO ] Check checksums DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/checksum_digests.lmdb' + [ NO ] Check observations DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/cf_observations.lmdb' + [ NO ] Check file stats DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/stats.lmdb' + [ NO ] Check locks DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/cf_lock.lmdb' + [ NO ] Check performance DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/performance.lmdb' + [ NO ] Check lastseen DB: Unable to diagnose LMDB file (not implemented) for '/var/cfengine/state/cf_lastseen.lmdb' + ``` +5. Stop services and cleanup + ``` + $ docker compose -f compose.yaml down --remove-orphans --rmi "local" -v + ``` + +## Supporting notes and references +### Enabling systemd for WSL +Follow the instructions provided here: [Use systemd to manage Linux services with WSL](https://learn.microsoft.com/en-us/windows/wsl/systemd) + +### References +- [Dockerfile reference](https://docs.docker.com/reference/dockerfile/) +- [Compose file reference](https://docs.docker.com/reference/compose-file/) diff --git a/getting-started/installation/general-installation/installation-community.markdown b/getting-started/installation/general-installation/installation-community.markdown index 265628e38..1c037c25a 100644 --- a/getting-started/installation/general-installation/installation-community.markdown +++ b/getting-started/installation/general-installation/installation-community.markdown @@ -2,7 +2,7 @@ layout: default title: Installing Community published: true -sorting: 50 +sorting: 70 --- These instructions describe how to download and install the latest version of CFEngine Community using pre-compiled rpm and diff --git a/getting-started/installation/general-installation/installation-coreos.markdown b/getting-started/installation/general-installation/installation-coreos.markdown index 1b7e575c5..b0dc9ea54 100644 --- a/getting-started/installation/general-installation/installation-coreos.markdown +++ b/getting-started/installation/general-installation/installation-coreos.markdown @@ -2,7 +2,7 @@ layout: default title: Installing Enterprise on CoreOS published: true -sorting: 40 +sorting: 60 --- These instructions describe how to install the latest version of CFEngine