luna-remote-sdk Configuration Migration

Overview

Configuration migration allows you to update the luna-remote-sdk service settings to the latest version using the specialized storages service. The migration process automatically applies necessary changes to the database and configuration files.

Prerequisites

Before running the migration, ensure that all luna-remote-sdk dependent services are running with their dependencies:

  • luna-configurator service must be accessible

  • luna-image-store service must be running and accessible

  • All required databases (PostgreSQL, etc.) must be running

  • All image store dependencies (storage backends, databases) must be operational

  • Network connectivity between services must be established

You can verify the configurator service is running:

curl http://${CONFIGURATOR_HOST}:${CONFIGURATOR_PORT}/healthcheck
Where:

  • ${CONFIGURATOR_HOST} — luna-configurator service host (e.g., luna-configurator)

  • ${CONFIGURATOR_PORT} — luna-configurator service port (default: 5070)

Basic Command

To perform the migration, use the following command:

docker run --rm --entrypoint='' --network host \
  ${DOCKER_REGISTRY}/storages:${STORAGES_TAG} \
  luna_prepare prepare remote_sdk
Where:

  • ${DOCKER_REGISTRY} — Docker registry address

  • ${STORAGES_TAG} — storages image version

  • remote_sdk — service name for migration

Additional Parameters

General Parameters

--help

Displays help information for all available commands and parameters.

docker run --rm --entrypoint='' ${DOCKER_REGISTRY}/storages:${STORAGES_TAG} \
  luna_prepare prepare --help
--config CONFIG

Path to the configuration file.

By default, uses config.conf from the working directory. If the working directory matches one of the available services, its config.conf is used; otherwise, the configuration from storages is used.

luna_prepare prepare remote_sdk --config /path/to/custom/config.conf

Database Connection Parameters

--db-user DB_USER

Database username. Overrides the default value from settings.

luna_prepare prepare remote_sdk --db-user luna_admin
--db-password DB_PASSWORD

Database user password. Overrides the default value from settings.

luna_prepare prepare remote_sdk --db-password secure_password

luna-configurator Integration

--luna-config LUNA_CONFIG

Address and API version of the luna-configurator service for pulling settings.

luna_prepare prepare remote_sdk --luna-config "http://${CONFIGURATOR_HOST}:${CONFIGURATOR_PORT}"

Version and Revision Management

--platform_version PLATFORM_VERSION

Platform version in the format v.1.2.3. If not specified, the latest available version is used.

luna_prepare prepare remote_sdk --platform_version v.5.100.0
--configs-revision CONFIGS_REVISION

Target configuration revision:

  • head — update to the latest version (default)

  • <hash> — specific revision (e.g., a1b2c3d4)

  • -1 — downgrade to the previous revision

# Update to latest version
luna_prepare prepare remote_sdk --configs-revision head

# Rollback to previous revision
luna_prepare prepare remote_sdk --configs-revision -1

# Apply specific revision
luna_prepare prepare remote_sdk --configs-revision a1b2c3d4e5

Entity Selection for Migration

--entity [{configs,lis_bucket,monitoring,all_entities}]

Specifies which entity to prepare:

  • configs — configuration files only

  • lis_bucket — Luna Image Store buckets only

  • monitoring — monitoring data only

  • all_entities — all entities (default)

# Migrate configs only
luna_prepare prepare remote_sdk --entity configs

# Migrate everything
luna_prepare prepare remote_sdk --entity all_entities

Monitoring Parameters

--monitoring-ttl MONITORING_TTL or -mttl MONITORING_TTL

Monitoring data retention policy in days for main tables and buckets.

luna_prepare prepare remote_sdk --monitoring-ttl 90

Usage Examples

Basic Migration

Update configuration to the latest version:

docker run --rm --entrypoint='' --network host \
  registry.example.com/storages:v.0.160.0 \
  luna_prepare prepare remote_sdk

Migration with Database Connection

docker run --rm --entrypoint='' --network host \
  registry.example.com/storages:v.0.160.0 \
  luna_prepare prepare remote_sdk \
  --db-user luna \
  --db-password luna_password

Migrate Configs Only to Specific Version

docker run --rm --entrypoint='' --network host \
  registry.example.com/storages:v.0.160.0 \
  luna_prepare prepare remote_sdk \
  --entity configs \
  --platform_version v.5.100.0 \
  --configs-revision head

Rollback Configuration to Previous Revision

docker run --rm --entrypoint='' --network host \
  registry.example.com/storages:v.0.160.0 \
  luna_prepare prepare remote_sdk \
  --entity configs \
  --configs-revision -1

Migration with luna-configurator Settings

docker run --rm --entrypoint='' --network host \
  registry.example.com/storages:v.0.160.0 \
  luna_prepare prepare remote_sdk \
  --luna-config "http://${CONFIGURATOR_HOST}:${CONFIGURATOR_PORT}"

Best Practices

  1. Backup: Before performing migration, it is recommended to create a backup of the database and configuration files.

  2. Testing: Test the migration in a staging environment before applying to production.

  3. Versioning: Always specify a concrete STORAGES_TAG version for migration reproducibility.

  4. Monitoring: After migration, check the remote_sdk service logs to confirm successful application of changes.

  5. Staged Migration: For major changes, it is recommended to migrate entities one by one using the --entity parameter.

Troubleshooting

Database Connection Errors

If database connection issues occur, ensure that:

  • Parameters --db-user and --db-password are specified correctly

  • --network host is used for localhost access

  • Database is accessible and running

luna-configurator Access Issues

Check service availability:

curl http://${CONFIGURATOR_HOST}:${CONFIGURATOR_PORT}/healthcheck

And ensure the --luna-config parameter points to the correct address.