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

Scope	Limit	Description
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

Tag	Description
`juice_id`	Validate `juice_instances` and port conflicts
`juice_install`	Install `juicefs` package
`juice_cache`	Create shared cache dir
`juice_clean`	Remove instance (state=absent)
`juice_instance`	Create instance (umbrella tag)
`juice_init`	Format filesystem
`juice_dir`	Create mount dir
`juice_config`	Render config files
`juice_launch`	Start service
`juice_register`	Write VictoriaMetrics target file

Config Updates

Render config only (no restart):

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

Update config and ensure service is online (without force restart):

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

If you need new mount options to take effect immediately, manually restart the instance service:

systemctl restart juicefs-<name>

Remove Instance

Removal flow:

Set instance state to absent
Run juice_clean

juice_instances:
  jfs:
    path: /fs
    meta: postgres://...
    state: absent

./juice.yml -l <host> -t juice_clean,juice_register
./juice.yml -l <host> -e fsname=jfs -t juice_clean,juice_register

Removal includes stopping the service, lazy unmounting, removing systemd unit and environment files, and reloading systemd. juice_register then rewrites the node’s target file and removes stale scrape endpoints. Running only juice_clean does not update monitoring targets. PostgreSQL metadata, PostgreSQL jfs_blob data tables, 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