Skip to main content
Version: Developer

Publish services with kziti

Overview​

A service in kziti defines a specific destination that Kasm sessions and external clients reach through OpenZiti. This guide creates services, groups them into reusable service sets, and lists, searches, updates, and deletes them. As a result, you grant access to named services rather than to broad network ranges, which keeps connectivity aligned with zero-trust principles. Service sets let you add or remove services without touching individual user grants.

Prerequisites​

Before you begin, confirm the following:

  • A working kziti deployment is already in place.
  • A configured kziti profile that connects to the controller. See Configure kziti profiles.
  • At least one network that hosts the services. See Manage networks.
  • The destination DNS name or IP, ports, and intended intercept address for each service you publish.

Solution approach​

This guide progresses through the following phases:

  1. Create a service.
  2. Group services into service sets.
  3. List and search services.
  4. Inspect and rename services.
  5. Delete services.

Detailed steps​

Create a service​

Create a service to expose a single destination through OpenZiti. The command takes the network, service name, destination, and ports, followed by a required alias.

kziti service create net-corp-a gitlab gitlab.corp-a.internal 443 \
  --alias gitlab.corp-a.zt

The arguments, in order, are:

  • Network ID — the network this service belongs to (net-corp-a). The short form without the prefix (corp-a) also works.
  • Service name — the short name (gitlab).
  • Destination — the real DNS name or IP the private router reaches (gitlab.corp-a.internal).
  • Ports — single port (443), comma-separated list (80,443), or range (8000-8100).

--alias is required and sets the intercept address, which is the hostname clients dial inside the Ziti tunnel. The alias must differ from the destination. The alias does not need a real DNS entry, because the Ziti tunnel resolves it locally.

Group services into service sets​

A service set groups related services. Grant access to the set once, then add or remove services without touching user grants. Service sets are global, so they can span multiple networks.

Create a service set​

The set must exist before you can assign services to it:

kziti service-set create devops "DevOps Services"

The command creates and registers the role attribute svcset-devops. Pass --service-set when creating services. The flag is repeatable, so a service can belong to multiple sets:

kziti service create net-corp-a gitlab gitlab.corp-a.internal 443 \
  --alias gitlab.corp-a.zt --service-set devops

kziti service create net-corp-a jira jira.corp-a.internal 443 \
  --alias jira.corp-a.zt --service-set devops

kziti service create net-corp-b wiki wiki.corp-b.internal 443 \
  --alias wiki.corp-b.zt --service-set devops --service-set infra

The three services share the svcset-devops role attribute. A single access grant against svcset-devops gives an identity Dial access to all three services, regardless of which network hosts them.

List service sets​

List every service set that exists:

kziti service-set list

Show a service set and its members​

Show the metadata for a set and every service it currently contains:

kziti service-set show devops

The output lists the set's metadata and every service currently in the set, with network and destination details. The ID column shows the svc-<short_id> reference you pass to add and remove.

Add an existing service to a set​

Add a service that already exists to a set:

kziti service-set add devops svc-corp-a-gitlab

The argument is either the svc-<short_id> shown by service-set show and service list, or the full service UUID. The short ID is svc-<network>-<service-name>. For a service named gitlab in network corp-a, the short ID is svc-corp-a-gitlab.

The command updates both the service's role attributes and its dial policy atomically. A service can belong to any number of sets.

Remove a service from a set​

Remove a service from a set without deleting the service:

kziti service-set remove devops svc-corp-a-gitlab

The command strips svcset-devops from the service's role attributes and from its dial policy. Membership in other sets, the network role, and any individually granted access are not affected.

Delete a service set​

Delete a set after its services no longer carry the set's role attribute:

kziti service-set delete devops

Deletion is blocked if any services still carry the set's role attribute. Remove those services from the set first, or delete the services. Deleting the set does not affect the services themselves.

List and search services​

List services across all networks or within a single network:

# All services across all networks
kziti service list

# Just the services in one network
kziti service list --network corp-a

Search services with a filter expression:

kziti service search 'name contains "gitlab"'
kziti service search 'name = "corp-a-web"'

The search returns the same columns as service list, which are ID, name, network, destination, and available-at. Use filter expressions supported by the OpenZiti filter syntax, including contains, =, startswith, and boolean operators.

Inspect and rename services​

Show the full configuration for a service:

kziti service show <service-id>

The output includes the intercept config, host config, and any service-set membership.

Rename a service with update:

kziti service update <service-id> --name new-name

update only supports renaming. To change the destination, ports, or alias, delete and recreate the service. To change service-set membership, use service-set add and service-set remove.

Delete services​

Delete a service when it is no longer needed:

kziti service delete <service-id>

Deletion removes the service and its intercept and host configs. Identities that had access via the service ID lose that access. Identities scoped via the network or service set retain access to the remaining services.

Common troubleshooting steps​

  • The alias is rejected when you create a service. The intercept address set by --alias must differ from the destination. Choose an alias that does not match the destination DNS name or IP.
  • Clients cannot resolve the alias. The alias does not need a real DNS entry, because the Ziti tunnel resolves it locally. Confirm that the client runs inside the Ziti tunnel and dials the alias rather than the destination.
  • A service set cannot be deleted. Deletion is blocked while any service still carries the set's role attribute. Remove the services from the set first, or delete the services.
  • service update does not change the destination or ports. update only supports renaming. Delete and recreate the service to change the destination, ports, or alias.
  • An identity loses access after a service is deleted. Identities scoped to the service ID lose access when the service is removed. Scope access via the network or service set so that access survives individual service deletion.