Deployments

• 1: Docker
• 2: Kubernetes
• 3: Bare-Metal

1 - Docker

Image Download

Image repository: https://hub.docker.com/r/huatuo/huatuo-bamai/tags

Start a container with Docker

docker run --detach \
  --name huatuo-bamai \
  --restart unless-stopped \
  --privileged \
  --pid=host \
  --cgroupns=host \
  --network=host \
  --cpus=2 \
  --memory=2g \
  --volume /sys:/sys \
  --volume /proc:/proc \
  --volume /run:/run \
  huatuo/huatuo-bamai:latest

Note: The built-in default configuration does not connect to kubelet or Elasticsearch.

Limit CPU and memory in production to isolate abnormal collection workloads. Docker manages the container cgroup; Huatuo does not create its own cgroup by default, so do not pass --enable-cgroup in a Docker deployment.

Verify that the limits are active and observe actual usage:

docker inspect huatuo-bamai \
  --format 'NanoCPUs={{.HostConfig.NanoCpus}} Memory={{.HostConfig.Memory}}'
docker stats huatuo-bamai

These values are an initial baseline. Adjust them based on node capacity, collection jobs, and observed resource peaks.

Start containers with Docker

The docker compose command allows you to quickly set up a complete local environment where you manage the collector, Elasticsearch, Prometheus, Grafana, and other components yourself.

$ docker compose --project-directory ./build/docker up

For installation instructions, see https://docs.docker.com/compose/install/linux/.

2 - Kubernetes

This document describes how to deploy the Huatuo collector to a Kubernetes cluster using a DaemonSet.

1. Kubernetes Manifest Deployment

1.1 Download the configuration file

curl -L -o huatuo-bamai.conf https://github.com/ccfos/huatuo/raw/main/huatuo-bamai.conf

1.2 Modify the configuration file

Modify the configuration file for the deployment environment. For example, configure the storage backend and the method used to obtain Pod information. See the Configuration Guide for details.

1.3 Create the ConfigMap

kubectl create configmap huatuo-bamai-config \
  --namespace default \
  --from-file=./huatuo-bamai.conf \
  --dry-run=client -o yaml |
kubectl apply -f -

1.4 Deploy the collector

Download the DaemonSet manifest:

curl -L -o huatuo-daemonset.yaml \
  https://raw.githubusercontent.com/ccfos/huatuo/main/build/huatuo-daemonset.minimal.yaml

Before deploying to production, set the huatuo container resources to this initial baseline:

resources:
  limits:
    cpu: "2"
    memory: 2Gi
  requests:
    cpu: "2"
    memory: 2Gi

Apply the modified manifest:

kubectl apply -f ./huatuo-daemonset.yaml

requests provide scheduling guarantees, while limits are enforced by the Pod cgroup managed by kubelet. Huatuo does not create its own cgroup by default, so it remains under kubepods and can be reclaimed normally after containerd restart or Pod deletion.

These values are an initial baseline with matching requests and limits, so the Pod has Guaranteed QoS. [Runtime] applies only when --enable-cgroup is explicitly passed; do not pass that flag in Kubernetes.

1.5 Verify the deployment

kubectl rollout status daemonset/huatuo \
  --namespace default \
  --timeout=10m

kubectl get pods \
  --namespace default \
  --selector app=huatuo \
  --output wide

kubectl get daemonset huatuo \
  --namespace default \
  --output jsonpath='{.spec.template.spec.containers[?(@.name=="huatuo")].resources}'

After updating huatuo-bamai.conf, rerun section 1.3 to update the ConfigMap, then manually restart the DaemonSet:

kubectl rollout restart daemonset/huatuo --namespace default

2. Helm Deployment

The Helm Chart is located at build/charts/.

2.1 Check the deployment environment

Helm and kubectl must be installed on the management host, which must be able to access the target Kubernetes cluster.

(command -v helm || curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash) && helm version

TARGET_CONTEXT="$(kubectl config get-contexts -o name | sed -n '1p')"
kubectl --context "${TARGET_CONTEXT}" get nodes

Verify that the target Nodes are Ready.

2.2 Prepare the configuration file

Download and modify huatuo-bamai.conf as described in sections 1.1 and 1.2.

2.3 Configure deployment values

Create values-production.yaml:

image:
  repository: <registry-accessible-to-all-nodes>/huatuo-bamai
  tag: "<release-version>"
  pullPolicy: IfNotPresent

resources:
  limits:
    cpu: "2"
    memory: 2Gi
  requests:
    cpu: "2"
    memory: 2Gi

nodeSelector:
  kubernetes.io/os: linux

tolerations:
  - operator: Exists

hostPaths:
  proc: /proc
  sys: /sys
  run: /run
  var: /var
  etc: /etc
  data: /var/log/huatuo/huatuo-local

2.4 Validate the Helm Chart

helm lint ./build/charts \
  -f ./values-production.yaml \
  --set-file config.content=./huatuo-bamai.conf

helm template huatuo ./build/charts \
  --namespace huatuo \
  -f ./values-production.yaml \
  --set-file config.content=./huatuo-bamai.conf \
  >/dev/null

2.5 Deploy the collector

helm upgrade --install huatuo ./build/charts \
  --kube-context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  --create-namespace \
  -f ./values-production.yaml \
  --set-file config.content=./huatuo-bamai.conf \
  --atomic \
  --timeout 10m

2.6 Verify the deployment

helm status huatuo \
  --kube-context "${TARGET_CONTEXT}" \
  --namespace huatuo

kubectl --context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  get daemonset,configmap,pod --output wide

kubectl --context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  rollout status daemonset/huatuo \
  --timeout=10m

Inspect the collector logs:

kubectl --context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  logs \
  --selector app.kubernetes.io/name=huatuo \
  --prefix \
  --tail=100

2.7 Upgrade and roll back

After changing the image version or huatuo-bamai.conf, rerun the command in section 2.5.

List the release history and roll back to a selected revision:

helm history huatuo \
  --kube-context "${TARGET_CONTEXT}" \
  --namespace huatuo

helm rollback huatuo <revision> \
  --kube-context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  --wait \
  --timeout 10m

3 - Bare-Metal

Production resource limits

systemd owns resource limits and process lifecycle for huatuo-bamai.service. The service unit disables Huatuo self-managed cgroups and uses native controls:

[Service]
CPUAccounting=yes
CPUQuota=200%
MemoryAccounting=yes
MemoryMax=2G
TasksAccounting=yes
TasksMax=32768
KillMode=control-group

CPUQuota=200% allows up to 2 CPU cores and MemoryMax=2G caps service memory. Adjust these values for the host, collection jobs, and observed peaks. Do not pass --enable-cgroup in a systemd deployment; it would move the process out of the service cgroup.

After starting the service, check its status and cgroup:

systemctl status huatuo-bamai --no-pager
systemd-cgls --unit huatuo-bamai.service

Binary

The HUATUO release provides static Linux tar packages for amd64 and arm64. The tar package contains the huatuo-bamai and huatuo-apiserver binaries, configuration files, and BPF objects.

This section applies to releases that provide assets named huatuo-bamai-<version>-static-linux-<arch>.tar.gz. This naming starts with v2.2.0 in the current releases. The v2.0.0 and v2.1.0 tar packages use different names, so the commands below do not apply to them directly.

The commands below use HUATUO_VERSION for the target version. Change it to the release version you want to install, for example v2.2.0:

HUATUO_VERSION="<release-version>"

1. Download the tar package

For x86_64 hosts, download the amd64 package:

wget "https://github.com/ccfos/huatuo/releases/download/${HUATUO_VERSION}/huatuo-bamai-${HUATUO_VERSION}-static-linux-amd64.tar.gz"

For aarch64 hosts, download the arm64 package:

wget "https://github.com/ccfos/huatuo/releases/download/${HUATUO_VERSION}/huatuo-bamai-${HUATUO_VERSION}-static-linux-arm64.tar.gz"

2. Install the tar package

Create the installation, log, and data directories:

sudo install -d -m 0755 /opt/huatuo-bamai /var/log/huatuo-bamai /var/lib/huatuo-bamai

For amd64:

sudo tar -xzf "huatuo-bamai-${HUATUO_VERSION}-static-linux-amd64.tar.gz" --strip-components=1 --no-same-owner -C /opt/huatuo-bamai

For arm64:

sudo tar -xzf "huatuo-bamai-${HUATUO_VERSION}-static-linux-arm64.tar.gz" --strip-components=1 --no-same-owner -C /opt/huatuo-bamai

3. Install the service unit files

Download the service unit files from the matching source version:

sudo wget -O /etc/systemd/system/huatuo-bamai.service "https://raw.githubusercontent.com/ccfos/huatuo/${HUATUO_VERSION}/build/rpm/huatuo-bamai.service"
sudo wget -O /etc/systemd/system/huatuo-apiserver.service "https://raw.githubusercontent.com/ccfos/huatuo/${HUATUO_VERSION}/build/rpm/huatuo-apiserver.service"

4. Modify the configurations

Edit /opt/huatuo-bamai/conf/huatuo-bamai.conf and /opt/huatuo-bamai/conf/huatuo-apiserver.conf to match the deployment environment. For detailed configuration options, see the huatuo-bamai configuration and huatuo-apiserver configuration.

Set CPUQuota, MemoryMax, and TasksMax in the service unit. Configure [Runtime] only for direct execution with --enable-cgroup.

5. Register the HUATUO services

Reload the systemd configuration:

sudo systemctl daemon-reload

6. Start the HUATUO services

Start the services and enable them at system startup:

sudo systemctl enable --now huatuo-bamai huatuo-apiserver

RPM Package

The OpenCloudOS repository provides HUATUO v2.1.0 RPM packages for x86_64 and aarch64. The RPM package installs the HUATUO files and systemd service unit file.

1. Download the RPM package

Download the package for the host architecture:

For x86_64:

wget https://mirrors.opencloudos.tech/epol/9/Everything/x86_64/os/Packages/huatuo-bamai-2.1.0-2.oc9.x86_64.rpm

For aarch64:

wget https://mirrors.opencloudos.tech/epol/9/Everything/aarch64/os/Packages/huatuo-bamai-2.1.0-2.oc9.aarch64.rpm

2. Install the RPM package

For x86_64:

sudo dnf install ./huatuo-bamai-2.1.0-2.oc9.x86_64.rpm

For aarch64:

sudo dnf install ./huatuo-bamai-2.1.0-2.oc9.aarch64.rpm

3. Modify the configuration

Edit /etc/huatuo-bamai/huatuo-bamai.conf to match the deployment environment. For detailed configuration options, see the huatuo-bamai configuration.

Set CPUQuota, MemoryMax, and TasksMax in the service unit. Configure [Runtime] only for direct execution with --enable-cgroup.

4. Start the HUATUO service

The RPM package installs the huatuo-bamai.service service unit file. Start the service and enable it at system startup:

sudo systemctl enable --now huatuo-bamai

For complete RPM installation instructions, see https://mp.weixin.qq.com/s/Gmst4_FsbXUIhuJw1BXNnQ.