Skip to content

Commit 60fb8e0

Browse files
me-coderme-coder
committed
Documentation for general installation in containerized environments
Adjusted instructions to use cf-remote and lts version/tag instead of 3.24.0-1
1 parent 3d15069 commit 60fb8e0

File tree

1 file changed

+286
-0
lines changed

1 file changed

+286
-0
lines changed

‎getting-started/installation/general-installation/installation-community-containerized.markdown

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
---
2+
layout: default
3+
title: Installing Community Using Containers
4+
published: true
5+
sorting: 80
6+
---
7+
8+
The instructions in this guide describe how to download and install the latest version of CFEngine Community in a Docker containerized environment using pre-compiled rpm packages and ubi9 images.
9+
10+
This guide describes how to set up a client-server model with CFEngine and, through policy, manage both containers.
11+
12+
Docker containers will be created, one container to be the Policy Server (server), and another container that will be the Host Agent (client).
13+
14+
Both the containers will run **_ubi9-init_** images and communicate on a container network.
15+
Upon completion, you are ready to start working with CFEngine.
16+
17+
18+
## Requirements
19+
* 1G+ disk space
20+
* 1G+ memory
21+
* 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.
22+
23+
**Note**: This document considers [Docker Engine](https://docs.docker.com/engine/) for all examples.
24+
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)).
25+
26+
## Overview
27+
1. Installing container engine
28+
2. Preparing CFEngine hub in container
29+
3. Preparing CFEngine host in container
30+
4. Using docker compose
31+
1. Preparing container image for CFEngine
32+
2. Using docker compose service
33+
5. Glossary
34+
6. References
35+
36+
## Installing container engine
37+
**Ref**: [Install Docker Engine](https://docs.docker.com/engine/install/)
38+
39+
OR
40+
41+
**Ref**: [Podman Installation Instructions](https://podman.io/docs/installation)
42+
(_Optionally_: [Emulating Docker CLI with Podman](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman))
43+
44+
## Preparing CFEngine hub in container
45+
Run the container with systemd
46+
47+
```command
48+
docker run --privileged -dit --name=cfengine-hub registry.access.redhat.com/ubi9-init /usr/sbin/init
49+
```
50+
51+
Prepare the container for **cfengine-hub**
52+
53+
```command
54+
docker exec cfengine-hub bash -c "dnf -y update; dnf -y install procps-ng iproute sudo pip; pip install cf-remote"
55+
```
56+
57+
Install cfengine-community package
58+
59+
```command
60+
docker exec cfengine-hub bash -c "cf-remote install --edition community --clients localhost"
61+
```
62+
63+
Bootstrap cf-agent
64+
65+
```command
66+
docker exec cfengine-hub bash -c "/usr/local/sbin/cf-agent --bootstrap \$(ip -4 -o addr show eth0 | awk '{print \$4}' | cut -d'/' -f1)"
67+
```
68+
69+
## Preparing CFEngine host in container
70+
The procedure to setup **cfengine-host** is similar to the **cfengine-hub** deployment. The changes are to name of the host container for better identification and bootstrap IP of the **cfengine-hub**.
71+
72+
```command
73+
docker run --privileged -dit --name=cfengine-host registry.access.redhat.com/ubi9-init /usr/sbin/init
74+
```
75+
76+
Prepare the container for **cfengine-host**
77+
78+
```command
79+
docker exec cfengine-host bash -c "dnf -y update; dnf -y install procps-ng iproute sudo pip; pip install cf-remote"
80+
```
81+
82+
Install cfengine-community package
83+
84+
```command
85+
docker exec cfengine-host bash -c "cf-remote install --edition community --clients localhost"
86+
```
87+
88+
### Bootstrap cfengine-host to the policy server container.
89+
Find IP address of **cfengine-hub**:
90+
91+
```command
92+
CFENGINE_HUB_IP=$(docker exec cfengine-hub bash -c "ip -4 -o addr show eth0 | awk '{print \$4}' | cut -d'/' -f1")
93+
```
94+
95+
Bootstrap cfengine-host to cfengine-hub:
96+
97+
```command
98+
docker exec cfengine-host bash -c "/usr/local/sbin/cf-agent --bootstrap ${CFENGINE_HUB_IP}"
99+
```
100+
101+
## Using docker compose
102+
### Preparing container image for CFEngine
103+
Create a `Dockerfile` with following contents:
104+
105+
```Dockerfile
106+
FROM registry.access.redhat.com/ubi9-init:latest
107+
LABEL description="This Dockerfile builds container image based on ubi9-init and latest LTS release of cfengine-community."
108+
109+
RUN dnf -y update \
110+
&& dnf -y install bind-utils iproute sudo pip procps-ng \
111+
&& pip install cf-remote \
112+
&& cf-remote install --edition community --clients localhost
113+
114+
HEALTHCHECK --interval=5s --timeout=15s --retries=3 \
115+
CMD /usr/local/sbin/cf-agent --self-diagnostics || exit 1
116+
117+
ENTRYPOINT ["/usr/sbin/init"]
118+
```
119+
120+
Validate the Dockerfile
121+
122+
```command
123+
docker build -t cfengine:lts -f Dockerfile . --check
124+
```
125+
```output
126+
[+] Building 0.1s (3/3) FINISHED docker:default
127+
=> [internal] load build definition from Dockerfile 0.0s
128+
=> => transferring dockerfile: 596B 0.0s
129+
=> [internal] load metadata for registry.access.redhat.com/ubi9-init:latest 0.0s
130+
=> [internal] load .dockerignore 0.0s
131+
=> => transferring context: 2B 0s
132+
Check complete, no warnings found.
133+
```
134+
135+
**Note**: You can skip to [_Using docker compose service_](#using-docker-compose-service), as the image would be built as per compose.yaml file, if not present.
136+
137+
Build the docker image based on above Dockerfile:
138+
139+
```command
140+
docker build -t cfengine:lts -f Dockerfile .
141+
```
142+
143+
Verify created image:
144+
145+
```command
146+
docker image ls cfengine
147+
```
148+
```output
149+
REPOSITORY TAG IMAGE ID CREATED SIZE
150+
cfengine lts <IMAGE_ID> About an hour ago 302MB
151+
```
152+
153+
### Using docker compose service
154+
Create a `compose.yaml` file with following contents:
155+
156+
```yaml
157+
[file=compose.yaml]
158+
name: cfengine-demo
159+
160+
services:
161+
cfengine-hub:
162+
container_name: cfengine-hub
163+
image: cfengine:lts
164+
build:
165+
context: .
166+
dockerfile: Dockerfile
167+
privileged: true
168+
command:
169+
- /bin/sh
170+
- -c
171+
- |
172+
"/usr/local/sbin/cf-agent --bootstrap $(ip -4 -o addr show eth0 | awk '{print $4}' | cut -d'/' -f1)"
173+
networks:
174+
- control-plane
175+
176+
cfengine-host:
177+
image: cfengine:lts
178+
build:
179+
context: .
180+
dockerfile: Dockerfile
181+
privileged: true
182+
command:
183+
- /bin/sh
184+
- -c
185+
- |
186+
"/usr/local/sbin/cf-agent --bootstrap $(dig +short cfengine-hub|tr -d [:space:])"
187+
networks:
188+
- control-plane
189+
depends_on:
190+
cfengine-hub:
191+
condition: service_healthy
192+
required: true
193+
194+
networks:
195+
control-plane:
196+
```
197+
198+
Validate the `compose.yaml` file
199+
200+
```command
201+
docker compose -f compose.yaml config 1>/dev/null
202+
```
203+
**Note**: No output means valid yaml file.
204+
205+
Start service cfengine-demo
206+
207+
```command
208+
docker compose -f compose.yaml up -d
209+
```
210+
211+
Bootstrap hub and hosts
212+
213+
```command
214+
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)"
215+
```
216+
```output
217+
R: Bootstrapping from host '192.168.16.2' via built-in policy '/var/cfengine/inputs/failsafe.cf'
218+
R: This host assumes the role of policy server
219+
R: Updated local policy from policy server
220+
R: Triggered an initial run of the policy
221+
R: Restarted systemd unit cfengine3
222+
notice: Bootstrap to '192.168.16.2' completed successfully!
223+
```
224+
225+
```command
226+
docker exec -it cfengine-demo-cfengine-host-1 bash -c "/usr/local/sbin/cf-agent --bootstrap \$(dig +short cfengine-hub|tr -d [:space:])"
227+
```
228+
```output
229+
notice: Bootstrap mode: implicitly trusting server, use --trust-server=no if server trust is already established
230+
notice: Trusting new key: MD5=2f406e11cfd3e08d810d77a186e204e2
231+
R: Bootstrapping from host '192.168.16.2' via built-in policy '/var/cfengine/inputs/failsafe.cf'
232+
R: This autonomous node assumes the role of voluntary client
233+
R: Updated local policy from policy server
234+
R: Triggered an initial run of the policy
235+
R: Restarted systemd unit cfengine3
236+
notice: Bootstrap to '192.168.16.2' completed successfully!
237+
```
238+
239+
Health-check for hub and host
240+
241+
```command
242+
docker exec -it cfengine-hub bash -c "/usr/local/sbin/cf-agent --self-diagnostics"
243+
```
244+
```output
245+
...
246+
[ YES ] Check that agent is bootstrapped: 192.168.16.2
247+
[ YES ] Check if agent is acting as a policy server: Acting as a policy server
248+
[ YES ] Check private key: OK at '/var/cfengine/ppkeys/localhost.priv'
249+
[ YES ] Check public key: OK at '/var/cfengine/ppkeys/localhost.pub'
250+
...
251+
```
252+
253+
```command
254+
docker exec -it cfengine-demo-cfengine-host-1 bash -c "/usr/local/sbin/cf-agent --self-diagnostics"
255+
```
256+
```output
257+
...
258+
[ YES ] Check that agent is bootstrapped: 192.168.16.2
259+
[ NO ] Check if agent is acting as a policy server: Not acting as a policy server
260+
[ YES ] Check private key: OK at '/var/cfengine/ppkeys/localhost.priv'
261+
[ YES ] Check public key: OK at '/var/cfengine/ppkeys/localhost.pub'
262+
...
263+
```
264+
265+
Stop services and cleanup
266+
267+
```command
268+
docker compose -f compose.yaml down
269+
```
270+
271+
## Glossary
272+
- [Hub](https://docs.cfengine.com/docs/3.24/overview-glossary.html#hub)
273+
- [Host](https://docs.cfengine.com/docs/3.24/overview-glossary.html#host)
274+
- [Client](https://docs.cfengine.com/docs/3.24/overview-glossary.html#client)
275+
- [CFEngine role](https://docs.cfengine.com/docs/3.24/overview-glossary.html#cfengine-role)
276+
- [Policy](https://docs.cfengine.com/docs/3.24/overview-glossary.html#policy)
277+
- [Promise](https://docs.cfengine.com/docs/3.24/overview-glossary.html#promise)
278+
- [Server](https://docs.cfengine.com/docs/3.24/overview-glossary.html#server)
279+
- [Policy server](https://docs.cfengine.com/docs/3.24/overview-glossary.html#policy-server)
280+
281+
## References
282+
- [Dockerfile](https://docs.docker.com/reference/dockerfile/)
283+
- [Docker compose file](https://docs.docker.com/reference/compose-file/)
284+
- [RedHat Universal Base Image (UBI)](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image)
285+
- [Using the UBI init images](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/building_running_and_managing_containers/index#using-the-ubi-init-images_assembly_adding-software-to-a-ubi-container)
286+
- [ubi9-init repository](https://catalog.redhat.com/software/containers/ubi9-init/6183297540a2d8e95c82e8bd)

0 commit comments

Comments
 (0)