Configure kziti profiles for OpenZiti controllers

Overview

Every kziti operational command authenticates against one OpenZiti controller before it can manage networks, services, or access. This guide connects kziti to a controller and manages named profiles, so that a single operator can target staging, production, and disaster-recovery controllers from one host. The result is a reliable configuration where each command runs against a known controller without mixing credentials.

Prerequisites

Before you begin, confirm the following:

• A reachable OpenZiti controller, with its management API URL and administrator credentials.
• Either administrator credentials for the controller, or an enrolled identity JSON file for an existing identity.
• Access to a host where kziti is installed, with permission to write to ~/.config/kziti/.

Solution approach

This guide progresses through the following phases:

1. Understand the profile model.
2. Connect kziti to a controller.
3. Manage multiple profiles.
4. Inspect the active configuration.

Detailed steps

Understand the profile model

A profile is a named set of credentials that kziti uses to authenticate against one OpenZiti controller. Every profile contains one of the following:

• A path to an enrolled identity JSON file, which is the standard approach.
• A raw management API URL plus a cert/key pair, for environments where a pre-existing PKI manages the controller credential.

All operational commands (network, service, access, router, …) read from the active profile. Switching profiles switches the target controller entirely. There is no mixing of credentials within a single command.

One profile exists by default and is named default. Most operators running a single controller never need more than one.

Connect kziti to a controller

1. For first-time setup, run the interactive wizard. The wizard creates a new admin identity, enrolls it against the controller, and stores the resulting JSON file automatically.

kziti config init

The wizard prompts for the controller URL, admin credentials, and an identity name. It then writes a config file at ~/.config/kziti/config.toml.

2. For scripted or CI environments, use config set-ziti directly. This runs the same enrollment flow non-interactively and updates the active profile.

kziti config set-ziti \
  --host https://ziti.example.com:1280 \
  --user admin \
  --password '<admin-password>'

3. To point a profile at an existing identity file instead of enrolling a new one, pass --identity.

kziti config set-ziti --identity /path/to/existing-identity.json

4. Verify the connection.

kziti status

Manage multiple profiles

Use separate profiles when you have more than one controller, such as staging and production, multiple customer deployments, or a primary and DR controller.

1. Create a blank profile for a second controller, then enroll an identity against that controller into the profile.

# Create a blank profile
kziti config profiles create staging

# Enroll a new identity against the staging controller into that profile
kziti config set-ziti \
  --profile staging \
  --host https://ziti-staging.example.com:1280 \
  --user admin \
  --password '<staging-password>'

2. Switch the active profile. All commands run against whichever profile is currently active.

kziti config profiles use staging
kziti network list   # now talks to the staging controller

kziti config profiles use default
kziti network list   # back to production

3. Use a profile for a single command. The global --profile flag overrides the active profile for one invocation without changing the persisted setting. This is useful in scripts where the caller controls which environment a command targets.

kziti --profile staging service list
kziti --profile staging access grant alice@example.com net-demo

4. Clone a profile to create a staging profile that starts from the same settings as production.

kziti config profiles create staging --from default
# Then update just the Ziti credentials
kziti config set-ziti --profile staging --host https://ziti-staging.example.com:1280 ...

Inspect the active configuration

1. Show all profiles, which one is active, and the connection settings for each. Secrets are redacted.

kziti config show

2. Show the settings for a single profile.

kziti config profiles show staging

The following table lists the profile commands and what each one does.

Command	What it does
kziti config init	Interactive wizard — prompts for controller URL, credentials, and identity name
kziti config set-ziti --host … --user … --password …	Non-interactive enrollment — creates and enrolls a new admin identity
kziti config set-ziti --identity /path/to/file.json	Point a profile at an existing identity JSON file
kziti config show	Show all profiles and their settings
kziti config path	Print the config file path
kziti config profiles list	List profile names and indicate which is active
kziti config profiles create <name>	Create a new empty profile
kziti config profiles create <name> --from <other>	Clone an existing profile
kziti config profiles use <name>	Set the persistent active profile
kziti config profiles show <name>	Show settings for one profile
kziti config profiles delete <name>	Delete a profile (cannot delete the last one)

The config file lives at ~/.config/kziti/config.toml by default, respecting XDG_CONFIG_HOME when set. When running under sudo, kziti resolves the path against the invoking user's home so that deploy commands (which require root) and operational commands (which do not) see the same config. Enrolled identity JSON files are stored under ~/.config/kziti/identities/<profile-name>/.

Common troubleshooting steps

• kziti status reports it cannot reach the controller. Confirm the controller URL and port, and confirm that the host can reach the management API. Re-run kziti config show to verify the active profile holds the expected host.
• A command targets the wrong controller. A profile other than the one you expect is active. Run kziti config profiles use <name> to set the active profile, or pass --profile <name> for a single command.
• Enrollment fails with config set-ziti. Confirm the administrator credentials and that the account can create and enroll identities. For environments with a pre-existing PKI, point the profile at an existing identity file with --identity instead.
• A profile cannot be deleted. kziti cannot delete the last remaining profile. Create or activate another profile first, then delete the unwanted one.
• kziti reads a different config under sudo. The config path resolves against the invoking user's home. Run the command as the same user who created the profile, or set XDG_CONFIG_HOME consistently across both contexts.