Configuration

JUICE module configuration, instance definition, storage backends, and mount options.

Concepts and Implementation

JuiceFS consists of a metadata engine and data storage. In Pigsty, metadata is always PostgreSQL (meta URL), while data storage is defined by data options passed to juicefs format.

JUICE module core commands:

# Format (only effective on first creation)
juicefs format --no-update <data> "<meta>" "<name>"

# Mount
juicefs mount <mount> --cache-dir <juice_cache> --metrics 0.0.0.0:<port> <meta> <path>

Notes:

  • --no-update ensures existing filesystems are not overwritten.
  • data is only used for initial format; it does not affect existing filesystems.
  • mount is only used during mount, you can pass cache and concurrency options.

Module Parameters

JUICE module has only two parameters:

ParameterTypeLevelDescription
juice_cachepathCJuiceFS shared cache directory
juice_instancesdictIJuiceFS instance dict (required)
  • juice_cache: shared local cache directory for all instances, default /data/juice
  • juice_instances: instance-level dict, key is filesystem name

Instance Configuration

Each entry in juice_instances represents a JuiceFS instance:

FieldRequiredDefaultDescription
pathYes-Mount point path, e.g. /fs
metaYes-Metadata engine URL (PostgreSQL)
dataNo''juicefs format options (storage backend)
unitNojuicefs-<name>systemd service name
mountNo''Extra juicefs mount options
portNo9567Metrics port (unique per node)
ownerNorootMount point owner
groupNorootMount point group
modeNo0755Mount point permissions
stateNocreatecreate / absent

Example:

juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:[email protected]:5432/meta
    data: --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta
    port: 9567

Storage Backends

data is appended to juicefs format, any supported backend works. Common examples:

PostgreSQL Large Objects

juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:[email protected]:5432/meta
    data: --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta

MinIO Object Storage

juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:[email protected]:5432/meta
    data: --storage minio --bucket http://10.10.10.10:9000/juice --access-key minioadmin --secret-key minioadmin

S3-Compatible Storage

juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:[email protected]:5432/meta
    data: --storage s3 --bucket https://s3.amazonaws.com/my-bucket --access-key AKIAXXXXXXXX --secret-key XXXXXXXXXX

Typical Configurations

Multi-Instance (Same Node)

juice_instances:
  pgfs:
    path: /pgfs
    meta: postgres://dbuser_meta:[email protected]:5432/meta
    data: --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta
    port: 9567
  shared:
    path: /shared
    meta: postgres://dbuser_meta:[email protected]:5432/shared
    data: --storage minio --bucket http://10.10.10.10:9000/shared
    port: 9568
    owner: postgres
    group: postgres

Shared Mount Across Nodes

Mount the same JuiceFS on multiple nodes:

app:
  hosts:
    10.10.10.11: { juice_instances: { shared: { path: /shared, meta: "postgres://...", port: 9567 } } }
    10.10.10.12: { juice_instances: { shared: { path: /shared, meta: "postgres://...", port: 9567 } } }

Only one node needs to format the filesystem; others will skip via --no-update.

Notes

  • port is exposed on 0.0.0.0. Use firewall or security group to restrict access.
  • Changing data will not update an existing filesystem; handle migration manually.

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