Skip to main content
Version: Developer

Manage networks with kziti

Overview​

A network in kziti is a logical grouping of services that usually maps to one customer, team, or environment. This guide creates, renames, and removes those networks, then provisions the private routers that host their services. Each network gets one or more private routers, which connect outbound to the public routers in the existing kziti deployment. As a result, you isolate services per tenant while reusing the same OpenZiti control plane.

Prerequisites​

Before you begin, confirm the following:

  • Access to the kziti controller host and permission to run kziti commands.
  • A working kziti-managed OpenZiti deployment with at least one public router.
  • A separate host that will run each private router, reachable over SSH.
  • The kziti binary installed where commands run. To install it, follow step 1 of the quickstart.

Solution approach​

This guide progresses through the following phases:

  1. List the existing networks.
  2. Create a new network.
  3. Provision a private router for the network.
  4. Rename a network.
  5. Delete a network.

Detailed steps​

List the existing networks​

  1. On the controller host, list the networks that are already defined:

    kziti network list

Create a new network​

Creating a network is a control-plane record only. The infrastructure comes from the private router that you provision in the next phase.

  1. Create the network with a network ID and a display name:

    kziti network create net-corp-a "Corp A"

    The first argument is the network ID. The net- prefix is the convention used in role attributes and access grants. For example, the network net-corp-a is granted with kziti access grant alice@example.com net-corp-a. The short form without the prefix (corp-a) also works and is normalised automatically. Keep the name short and lowercase. The second argument is a human-readable display name.

Provision a private router for the network​

A network needs at least one private router to host its services. Complete the following three steps in order.

  1. On the controller host, create the router record:

    kziti router private provision net-corp-a corp-a-router-1 --output-dir /tmp

    This command creates an OpenZiti router identity tagged for the network. It writes a router enrollment JWT to /tmp/corp-a-router-1.jwt. The --tunneler flag is enabled by default, so the router hosts services. Use --no-tunneler only when you run a separate hosting identity.

  2. Transfer the JWT to the host that will run the router:

    scp /tmp/corp-a-router-1.jwt user@router-host.corp-a.example.com:/tmp/

  3. On the router host, install kziti as in step 1 of the quickstart, then start it as a router:

    kziti deploy install --profile router \
      --router-host router-host.corp-a.example.com \
      --enrollment-token "$(cat /tmp/corp-a-router-1.jwt)"

    The router enrolls with the controller using the JWT and starts hosting traffic for the network.

  4. On the controller host, verify that the router is online:

    kziti router list

    The new router appears with status online and the network attribute set.

Rename a network​

  1. Change the display name of a network:

    kziti network rename net-corp-a "Corp A (renamed)"

    The network ID does not change. Only the display name changes.

Delete a network​

Deleting a network removes its services, role attributes, and policies from the controller. Identities lose access to anything previously scoped to the network.

  1. Confirm that no Kasm sessions depend on the services in the network.

  2. Delete the network:

    kziti network delete net-corp-a

  3. Tear down any private routers that were specific to the network. Follow Tear down a deployment.

caution

Deletion is destructive. Identities lose access to every service that was scoped to the network. Verify that no active sessions depend on those services before you run the delete command.

Common troubleshooting steps​

  • The new router does not appear in kziti router list. Confirm that the JWT transferred intact and that the router host can reach the controller. Re-run the install command on the router host with the correct --router-host value.
  • The router appears but its status is not online. Confirm that the enrollment token is current and that outbound connectivity to the public routers is open. A stale or reused JWT prevents enrollment.
  • The router hosts no services. Confirm that you did not pass --no-tunneler. The --tunneler flag must be enabled for the router to host services.
  • kziti network delete leaves identities with stale access. Deletion removes the network's policies, but you must also tear down the network's private routers separately. Follow Tear down a deployment.