Skip to main content
Version: Next

Getting started with TSG

This guide deploys a managed TSG stack with SSO Bridge, Wallet, Control Plane and Tenant Management. It starts without organizations. Create or explicitly import an organization through Tenant Management after deployment.

For an executable local HTTP exchange, use the managed HTTP sample. The CLI stack below supplies organization management and browser access; worker integration is a separate explicit deployment step.

Prerequisites​

Tools​

Helm is not required.

Cluster​

  • Kubernetes 1.24+
  • CloudNativePG 1.30 or newer
  • An Ingress controller (or the Gateway API CRDs plus a controller)
  • cert-manager, to issue the TLS certificates

Important: public HTTPS endpoints with real domains are required for DID document resolution and for connectors to reach each other.

Install the CLI​

npm install -g @tsg-dsp/cli@latest
tsg --version

Step 1: Register your deployment details​

Choose the namespace, host and stable initial administrator UUID before the first deployment. Preserve that UUID afterward, because it identifies the operator's global login account. Register the dataspace authority's actual DID, domain and credential type. Do not derive a DID from a hostname.

Step 2: Write your configuration​

Create participant.yaml, replacing the example host, authority and operator identity values. The explicit managedTenancy block enables the coordinated manager, shared browser clients and consumer registrations.

apiVersion: tsg.dataspac.es/v1alpha2
kind: TsgDeployment
metadata:
  name: my-org
spec:
  namespace: tsg-my-org
  dataspace:
    name: example-dataspace
    authority:
      did: did:web:authority.example.com:tenants:authority
      domain: authority.example.com
      credentialType: ExampleCredential
  admin:
    username: platform-admin
    email: platform@my-org.example
    require2FA: true
    passwordSecret:
      name: tsg-admin
      key: password
  stacks:
    - id: my-org
      name: Hosted organizations
      host: dataspace.my-org.example
      routing: path
      managedTenancy:
        # Choose before first deployment and preserve it afterward.
        adminUserId: 11111111-1111-4111-8111-111111111111
      components:
        controlPlane:
          enabled: true
        tenantManagement: {}

Wallet and SSO Bridge are included by the stack. A managed CLI stack rejects participant seeds. Workers require existing canonical owners and registrations; Starter can be added as a shared browser client. The supported CLI example uses this same shape. Point DNS at the ingress before deployment so certificate issuance and DID resolution can reach the published host.

Step 3: Create the Secrets​

Rendered manifests reference Secrets rather than embedding credentials. Supply these through your existing Secret tooling, or generate the initial values:

kubectl create namespace tsg-my-org
tsg secrets generate participant.yaml --apply

Preserve the generated session and encryption secrets alongside database backups. Changing an encryption secret does not migrate stored ciphertext.

Step 4: Review, then deploy​

kubectl config current-context     # make sure this is the right cluster

tsg diff participant.yaml          # what would change
tsg deploy participant.yaml        # do it

deploy renders the manifests, shows the diff, applies in ordered waves, waits for each component to become ready, and prunes anything a previous deployment left behind. Nothing is applied if a referenced Secret or a cluster prerequisite is missing.

Step 5: Verify​

kubectl get pods -n tsg-my-org
tsg status participant.yaml

Your browser interfaces use the configured host and path routing:

  • SSO Bridge: https://dataspace.my-org.example/
  • Wallet: https://dataspace.my-org.example/wallet/
  • Control Plane: https://dataspace.my-org.example/control-plane/
  • Tenant Management: https://dataspace.my-org.example/tenant-management/

Confirm the actual paths in the rendered routes. Sign in with the administrator credentials and finish the configured second-factor setup.

Step 6: Create or import an organization​

Open Tenant Management and create an organization with an explicit human owner. Wait for its provisioning operation to report ready, then open its Wallet and Control Plane. Platform operator authority does not grant organization membership. The receiving services obtain separate audience-bound authorizations.

For existing participant data, follow the explicit import procedure. Old seeded configuration no longer starts. Preserve local IDs, URL slugs, DIDs, keys, datasets and service-specific grants; creating a new tenant does not adopt the existing participant's identity.

A data exchange additionally needs an authenticated worker with explicit canonical execution owners and a managed control-plane registration. Follow the local managed HTTP sample for that complete flow. Verify the returned backend data after negotiation and transfer. Ready pods alone do not verify the data path.

Next steps​

  • Publish your data. Dataset Configuration describes how what you offer becomes a DCAT catalog entry.
  • Explore the control plane. Browse catalogs, negotiate, and watch transfers from its web interface.
  • Deploy a whole dataspace. The Deployment Guide covers the ecosystem shape, with an authority and several participants in one cluster.
  • Harden it. The Configuration Reference covers private_key_jwt, 2FA, per-stack databases and digest pinning.

Troubleshooting​

A prerequisite is missing. tsg deploy names the CRD and prints the command that installs it. These are cluster-admin operations; TSG never performs them.

A Secret is missing. The preflight lists every Secret and key it could not find, before anything is applied. Create them, then re-run.

A component does not become ready. Nothing was pruned and the inventory still records both the previous and the desired objects, so fix the cause and re-run. kubectl logs -n tsg-my-org deploy/<name> usually says why.

Certificates stay pending. Check that DNS resolves your host to the ingress address, then kubectl describe certificate -n tsg-my-org.

More in the troubleshooting guide.