Configure remote authentication with a preferred FQDN¶

Learn how to use the f5insight-set-fqdn command to replace default IP-based remote auth login URLs with a preferred Fully Qualified Domain Name (FQDN).

Overview¶

By default, remote authentication can use an IP address for login page links and external auth endpoints. Use f5insight-set-fqdn to set a stable hostname instead.

Using an FQDN is recommended for:

TLS certificate hostname validation.
Better user experience (friendly login URLs).
Stable identity across IP changes.

Important

Run set with root privileges (for example, sudo). The command updates Helm values and patches the running login deployment headers.

Before you start¶

Prerequisites:

f5insight-set-fqdn is available on the system.
helm and kubectl are installed and in PATH.
Kubeconfig access to the target cluster.
Existing Helm release (default: f5-insight in namespace f5-insight).

Defaults used by the command (unless overridden):

Namespace: f5-insight
Helm release: f5-insight
URL scheme: https
Default port: 443
Helm timeout: 10m
Safe mode: enabled

Show current remote auth values¶

Use show to inspect current FQDN-related values:

sudo f5insight-set-fqdn show

This displays key values such as:

zitadel.appBaseUrl
zitadel.config.externalDomain
zitadel.config.externalPort
zitadel.config.externalProtocol
zitadel.bootstrap.f5InsightsHostname

Set remote auth to your preferred FQDN¶

Choose your target name¶

Accepted target formats:

insight.example.com
insight.example.com:8443
https://insight.example.com
http://insight.example.com:8080

If no scheme is provided, the command uses https by default.

Apply the FQDN¶

Run set with your target:

sudo f5insight-set-fqdn set auth.example.com

For a custom port:

sudo f5insight-set-fqdn set https://auth.example.com:8443

The command:

Parses the target into scheme, host, and port.
Runs helm upgrade --reuse-values with remote auth overrides.
Patches CUSTOM_REQUEST_HEADERS on the login deployment.
Waits for rollout completion.

Confirm when prompted¶

The command prints the resolved values and asks for confirmation:

Apply these settings? [y/N]

To skip the prompt in automation, add --yes.

Optional modes¶

Dry run (preview only):

sudo f5insight-set-fqdn set auth.example.com --dry-run

Verify the configuration¶

Check values after apply:

sudo f5insight-set-fqdn show

You can also verify relevant Helm values directly:

NAMESPACE=f5-insight
HELM_RELEASE=f5-insight
export KUBECONFIG=/etc/rancher
sudo -E helm get values "${HELM_RELEASE}" -n "${NAMESPACE}" -o yaml \
  | grep -E "appBaseUrl|externalDomain|externalPort|externalSecure|externalProtocol|loginV2BaseUri|f5InsightsHostname|f5InsightsPort" -A1 || true

Troubleshooting¶

Issue	Cause	Solution
Command fails with permission error	`set` requires root privileges	Run with `sudo`.
Helm release not found	Wrong namespace or release name	Set `NAMESPACE` and `HELM_RELEASE` correctly, then retry.
Kubeconfig not found	Default kubeconfig path not valid	Export `KUBECONFIG` to a valid file. If using sudo, use `sudo -E`.
Login page still uses old host	Rollout pending or browser cache	Wait for rollout completion, then refresh browser cache and retest.
TLS warning in browser	Certificate does not match new FQDN	Install a certificate valid for the configured hostname.

Notes¶

The command preserves unrelated Helm settings by using --reuse-values.
Safe mode is enabled by default and disables DB/bootstrap init jobs plus hooks.
To check command usage at any time, run f5insight-set-fqdn --help.

Previous Next