Migrating from 7.x to 8.0

This guide covers the portable configuration format change introduced in EUDIPLO v8.0. Existing database records are not changed by this format migration, but exported configuration files and tenant configuration folders must use the canonical v1 schema envelope before they are imported into v8.

Back up before upgrading

Always back up your database and your assets/config directory before performing a major version upgrade.

Summary of Breaking Changes

Area	Change	Impact
Portable configuration identity	apiVersion and kind legacy envelopes are no longer accepted as the exported file format. Use the canonical $schema URL instead.	High
Resource identifiers	Resource IDs move into spec.id (spec.clientId for clients). metadata.id is rejected. Singleton resources do not require an ID.	High
Envelope validation	Configuration envelopes and metadata now reject unknown properties.	Medium

1. Convert Legacy Configuration Files

Before (7.x legacy envelope)

Legacy files may identify a resource with apiVersion, kind, and metadata.id:

{
    "apiVersion": "eudiplo.dev/v1",
    "kind": "Client",
    "metadata": {
        "id": "wallet-client"
    },
    "spec": {
        "secret": "${CLIENT_SECRET}"
    }
}

After (8.0 canonical envelope)

The schema URL identifies the resource type and format version. The client identifier belongs in spec.clientId:

{
    "$schema": "https://eudiplo.dev/schemas/v1/ClientConfigFile.schema.json",
    "spec": {
        "clientId": "wallet-client",
        "secret": "${CLIENT_SECRET}"
    }
}

For resources other than clients, use spec.id. Tenant, KMS, registrar, and issuance settings are singleton resources and do not require an ID.

2. Run the Offline Upgrade

Use the CLI to convert a resource, folder, or exported bundle without connecting to an EUDIPLO instance:

# Inspect changes without writing output
eudiplo config upgrade ./config --check --diff

# Write converted files to a separate directory
eudiplo config upgrade ./config --output ./config-v8

# Validate the converted tenant configuration
eudiplo config validate tenants ./config-v8

For a JSON or ZIP export:

eudiplo config upgrade production-config.zip --dry-run
eudiplo config upgrade production-config.zip --output production-config-v8.zip

The upgrade command preserves supported metadata, moves legacy identifiers into the appropriate spec field, and validates the source and converted document. It does not invent missing security-sensitive values. Review required-input issues before importing.

Use a separate output path

Do not use the input directory as the output directory. The folder upgrade stages the complete result and publishes it only after every selected document validates successfully.

3. Check for Manual Cleanup

After conversion, search the output for legacy envelope fields:

rg '"apiVersion"|"kind"|"metadata"[[:space:]]*:[[:space:]]*\{[^}]*"id"' ./config-v8

Remove any unsupported envelope or metadata properties reported by validation. The canonical portable envelope contains only $schema, optional metadata.generation / metadata.ownership, and spec.

4. Verify Imports

Before applying the converted configuration to a target instance:

eudiplo config validate tenants ./config-v8
eudiplo config plan production-config-v8.zip \
    --instance staging \
    --mode upsert \
    --diff \
    --output plan.json
eudiplo config import production-config-v8.zip \
    --instance staging \
    --mode upsert \
    --plan plan.json

Review the plan for resource identity, required inputs, and replacements before importing. Existing v1 configuration schema versions are independent of the application release version; a v8 application still uses resource schema URLs such as .../schemas/v1/ClientConfigFile.schema.json.