barycenter/book/src/deployment/k8s-user-sync.md

User Sync in Kubernetes

Barycenter supports provisioning users at startup through an init container that runs before the main application. This is useful for seeding an initial set of users in automated deployments where interactive user creation is not practical.

How It Works

When userSync.enabled is true, the Helm chart adds an init container to the Barycenter pod. This init container:

1. Reads a JSON array of user objects from a file.
2. Inserts or updates each user in the database.
3. Exits. The main Barycenter container then starts with the users already present.

The init container runs every time the pod starts, so it is safe to add new users to the list and redeploy. Existing users are updated to match the provided data.

Inline User Definitions

For small deployments or development environments, define users directly in values.yaml:

userSync:
  enabled: true
  users: |
    [
      {
        "username": "alice",
        "password": "correct-horse-battery-staple",
        "email": "alice@example.com"
      },
      {
        "username": "bob",
        "password": "another-strong-passphrase",
        "email": "bob@example.com"
      }
    ]

Warning: Passwords in values.yaml are stored as plaintext in the Kubernetes ConfigMap. For production deployments, use the existingSecret method described below.

Using an Existing Secret

For production, store user data in a Kubernetes Secret:

kubectl create secret generic barycenter-users \
  --from-file=users.json=./users.json \
  -n barycenter

Where users.json contains:

[
  {
    "username": "alice",
    "password": "correct-horse-battery-staple",
    "email": "alice@example.com"
  },
  {
    "username": "bob",
    "password": "another-strong-passphrase",
    "email": "bob@example.com"
  }
]

Reference the Secret in your values:

userSync:
  enabled: true
  existingSecret: barycenter-users

The chart mounts the Secret into the init container and reads the users.json key.

User Object Schema

Each user object in the JSON array supports the following fields:

Field	Required	Description
username	Yes	Unique username for login
password	Yes	Plaintext password (hashed with Argon2 on import)
email	No	User email address

Passwords are always hashed before being stored in the database. The plaintext password in the JSON is never persisted.

Updating Users

To add or modify users:

1. Update the JSON array (in values.yaml or in the Secret).
2. Redeploy with helm upgrade.

The init container runs again and applies the changes. Existing users whose data has not changed are left untouched.

Combining with Other User Sources

User sync is additive. Users created through other means -- such as the Admin GraphQL API, public registration, or direct database access -- are not affected by the sync process. The init container only manages the users present in the JSON array.

Disabling User Sync

To stop running the init container, set userSync.enabled to false and redeploy. Previously synced users remain in the database; they are not deleted.

userSync:
  enabled: false

Troubleshooting

If the pod is stuck in Init:0/1 status, check the init container logs:

kubectl logs <pod-name> -c user-sync -n barycenter

Common issues:

• Database not reachable -- If using PostgreSQL, verify that the database is accessible from the pod and that the connection string in config.database.url is correct.
• Invalid JSON -- Validate the JSON syntax before deploying. A missing comma or bracket will prevent the init container from completing.
• Secret not found -- Ensure the Secret referenced by existingSecret exists in the same namespace as the Barycenter release.

Further Reading

• Helm Chart Values -- full reference of userSync.* values
• User Sync from JSON -- the underlying user-sync mechanism
• Creating Users -- other methods for provisioning users