Skip to content

Commit

Permalink
Documentation for general installation in containerized environments
Browse files Browse the repository at this point in the history
  • Loading branch information
me-coder committed Oct 2, 2024
1 parent 980728e commit fa645e7
Show file tree
Hide file tree
Showing 3 changed files with 238 additions and 2 deletions.
Original file line number Diff line number Diff line change
@@ -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.

<hr>
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 <IMAGE_ID> 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/)
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit fa645e7

Please sign in to comment.