Playbook

JUICE module playbook guide.

JUICE module provides juice.yml playbook to deploy and remove JuiceFS instances.


juice.yml

Task structure in juice.yml:

juice_id        : validate config, check port conflicts
juice_install   : install juicefs package
juice_cache     : create shared cache dir
juice_clean     : remove instance (state=absent)
juice_instance  : create instance (state=create)
  - juice_init  : format filesystem (--no-update)
  - juice_dir   : create mount dir
  - juice_config: render env file and systemd unit
  - juice_launch: start service and wait for metrics port
juice_register  : register to VictoriaMetrics targets

Scope

ScopeLimitDescription
Node-l <host>Deploy all instances on the node
Instance-l <host> -e fsname=<name>Only handle specified instance

Examples:

./juice.yml -l 10.10.10.10                 # deploy all instances on the node
./juice.yml -l 10.10.10.10 -e fsname=jfs   # only deploy jfs instance

Common Tags

TagDescription
juice_idValidate juice_instances and port conflicts
juice_installInstall juicefs package
juice_cacheCreate shared cache dir
juice_cleanRemove instance (state=absent)
juice_instanceCreate instance (umbrella tag)
juice_initFormat filesystem
juice_dirCreate mount dir
juice_configRender config files
juice_launchStart service
juice_registerWrite VictoriaMetrics target file

Config Updates

Render config only (no restart):

./juice.yml -l <host> -t juice_config

Update config and restart service:

./juice.yml -l <host> -t juice_config,juice_launch

Remove Instance

Removal flow:

  1. Set instance state to absent
  2. Run juice_clean
juice_instances:
  jfs:
    path: /fs
    meta: postgres://...
    state: absent
./juice.yml -l <host> -t juice_clean
./juice.yml -l <host> -e fsname=jfs -t juice_clean

Removal includes: stop service, lazy unmount, remove systemd unit/env files, reload systemd. PostgreSQL metadata and object storage data are not deleted.


Monitoring Registration

juice_register writes target file on infra node:

/infra/targets/juice/<hostname>.yml

To re-register manually:

./juice.yml -l <host> -t juice_register

Last Modified 2026-02-08: translate to en (1cfc740)