Moving from the previous CLI

The previous CLI generated Helm values from general, participant or participants configuration. The new CLI accepts TsgDeployment documents and renders Kubernetes resources directly. Conversion is manual. tsg migrate only upgrades versioned TsgDeployment documents; it cannot convert the previous format or take over a Helm release.

Map the configuration

Start with participant.yaml or ecosystem.yaml. Keep the old file for comparison and rollback.

Previous setting	New location or action
general.namespace	spec.namespace
general.username	spec.admin.username
general.password	Create a Secret and reference it from spec.admin.passwordSecret
general.authorityDomain	spec.dataspace.authority.domain; also supply the authority's actual DID explicitly
general.credentialType	spec.dataspace.authority.credentialType
participant or each entry in participants	A spec.stacks[] runtime and its participantSeeds[] entry
Participant id, name, host	Stack id, name, host; identity id and name also belong in the seed
hasControlPlane	components.controlPlane.enabled
hasTestService / an HTTP dataset	Enable components.dataPlanes.http-data-plane and components.useCaseApps.dataspace-starter; publish through Starter or the SDK
Participant issuer	participantSeeds[].issuer
Pre-authorized membership code	Store the authority's code in a Secret referenced by participantSeeds[].preAuthorizedCodeSecret
Helm values overrides	Move application settings under the component's config; use workload settings or patches for Kubernetes fields
tsg bootstrap participant	tsg render participant.yaml -o out
tsg deploy participant -f ...	tsg deploy participant.yaml

For example, this old input:

general:
  namespace: tsg-participant
  username: tsg
  authorityDomain: authority.example.com
  credentialType: ExampleCredential
participant:
  id: zulu
  name: Zulu
  host: zulu.example.com
  hasControlPlane: true
  hasTestService: true

becomes this starting configuration for a new deployment:

apiVersion: tsg.dataspac.es/v1alpha1
kind: TsgDeployment
metadata:
  name: zulu
spec:
  namespace: tsg-zulu-new
  dataspace:
    name: example-dataspace
    authority:
      did: did:web:authority.example.com:tenants:authority
      domain: authority.example.com
      credentialType: ExampleCredential
  admin:
    username: tsg
    passwordSecret:
      name: tsg-admin
      key: password
  stacks:
    - id: zulu
      name: Zulu
      host: zulu.example.com
      routing: path
      participantSeeds:
        - id: zulu
          name: Zulu
          preAuthorizedCodeSecret:
            name: zulu-preauth
            key: code
      components:
        controlPlane:
          enabled: true
        dataPlanes:
          http-data-plane: {}
        useCaseApps:
          dataspace-starter: {}

Replace the namespace, host and authority details before applying. This example creates new databases and identities; it is not an in-place upgrade recipe. Use separate test hostnames during validation. Do not serve the same participant identity concurrently from the old and new deployments.

Preserve state deliberately

1. Record the Kubernetes context, namespace, Helm releases, image versions, database names, owning roles, PVCs, Secrets, participant DIDs and tenant slugs. Back up the databases and wallet key material, and verify that the backup can be restored. Finish or terminate old transfer-protocol operations before switching runtimes.
2. Decide whether this is a fresh installation or an upgrade retaining identity and data. For an in-place application upgrade, continuing to use the Helm charts avoids changing infrastructure ownership at the same time. Supply the new application configuration and tenant-scoped endpoints through Helm values.
3. If moving to CLI-managed infrastructure, restore copies into an isolated test deployment first. The CLI creates its own database names and owning roles; restore each component's data with the corresponding ownership. Changing database.mode or a stack id does not move data. Inspect the rendered manifests before deciding how to map the old databases, volumes and Secrets.
4. Preserve the existing tenant slug. Control-plane data migrated from before multi-tenancy belongs to default; a new seed named zulu will not move that data. Using default preserves the scope, but does not by itself preserve an old root DID. New CLI identities use did:web:<host>:tenants:<slug>. Compare the actual wallet DID, keys and issued credentials before cutover. If the DID changes, arrange membership reissuance and update counterparties' references.
5. Remove obsolete application fields, including HTTP dataset, registration catalogSynchronization, control-plane runtime.dataplaneSignaling, and data-plane controlPlane.walletEndpoint. Review remaining overrides against the current component configuration references. Inspect existing datasets and their private integration state before deciding which need republication.
6. Render and review the new configuration offline. Then test login, DID resolution, membership issuance, existing dataset access, and a transfer with another participant. Test metadata edits and a new transfer after explicitly replacing backend credentials.
7. Plan the ownership and traffic cutover. The CLI refuses to adopt colliding Helm-owned resources. Do not fix that by blindly relabeling objects or uninstalling releases containing databases or PVCs. Keep one owner for each live resource. Retain the old deployment and verified backups until the new deployment passes the checks and rollback is no longer needed.

tsg render participant.yaml -o out
# After preparing the target environment and Secrets:
tsg diff participant.yaml
tsg deploy participant.yaml

A successful render validates the deployment structure, not application startup, database compatibility, external credentials or data access. The final cutover must be based on the live checks above.