API Gateway

The API Gateway exposes Registry at /registry and Identity Service at /identity on the API hostname. It strips each prefix before forwarding requests. MCP uses the gateway but remains at its own hostname; there is no /mcp route.

Examples use Kubernetes Ingress. For Istio, use the corresponding virtualService.* settings.

Two chart values define the surface:

Value	Effect
apiGateway.enabled	Deploys the API Gateway itself: its Deployment, Service, and (per your values) Ingress or VirtualService.
common.mainFqdn	The platform's domain. From chart 6.0 the chart derives the API Gateway's public URL from it, https://api.<common.mainFqdn>, or uses the host in common.apiFqdnOverride, and gives that URL to the services when the API Gateway is enabled.

Identity Service has two independent settings:

Value	Effect
identity.enabled	Deploys the Identity Service itself.
identity.clientIntegration.enabled	Moves the registry service, the frontend, and MCP onto the Identity Service as their authentication authority.

Both identity settings default to true. To disable Identity Service, set both to false and disable the provisioner. Setting only identity.enabled: false breaks sign-in.

Verify routing before sign-in

Before enabling client integration, confirm that https://api.<customer_istari_fqdn>/registry/api/v2/health/readiness returns 200. On a new installation, check immediately after deployment.

Values in a service's own Secret override the chart's settings. Remove stale identity-enabled or API URL overrides when changing configurations.

Configuration 1: Neither Enabled

Set identity.enabled, identity.clientIntegration.enabled, provisioner.enabled, and apiGateway.enabled to false. Expose Registry directly and configure the frontend's VITE_FILE_AUTH_ENDPOINT, CLI/SDK Registry target, and Zitadel credentials for that endpoint.

For an existing installation, follow Turning Identity Service off before removing the gateway.

Verification: confirm frontend and CLI sign-in through the direct Registry endpoint.

Rollback: helm rollback <release> <previous-revision>.

Configuration 2: Gateway Only

Clients reach Registry through <api-host>/registry and authenticate directly with Zitadel. This is the configuration used when Identity Service is disabled.

Prerequisites

• An Ingress controller and its IngressClass.
• An API hostname pointing to the controller's load balancer.
• A TLS Secret for that hostname. TLS terminates at the Ingress; the gateway serves HTTP internally.

Values to set

istari-values.yaml (excerpt)

common:
  mainFqdn: "<customer_istari_fqdn>" # the gateway's host is api.<customer_istari_fqdn>
identity:
  enabled: false # from 7.0.0 both identity values default to true;
  clientIntegration:
    enabled: false # set both to false to keep Zitadel authentication
apiGateway:
  enabled: true
  ingress:
    enabled: true
    className: "nginx" # match your controller's IngressClass
    hosts:
      - host: api.<customer_istari_fqdn>
        paths:
          - path: /
            pathType: Prefix
    tls:
      - hosts:
          - api.<customer_istari_fqdn>
        secretName: api-<customer_istari_fqdn>-tls

Use api.<common.mainFqdn>, or common.apiFqdnOverride if set, in both the Ingress host and TLS entry.

Order of operations

1. Create the TLS Secret and DNS record for the API hostname.

2. Set the values above and run helm upgrade.

3. Wait for the registry service and frontend to roll. The upgrade changes their configuration, so Helm replaces their pods:

   kubectl rollout status deployment/istari-fileservice
   kubectl rollout status deployment/istari-frontend

   (If MCP is deployed, also run kubectl rollout status deployment/istari-mcp.)

Verification

curl -fsS https://api.<customer_istari_fqdn>/registry/api/v2/health/readiness

should return 200. Confirm the frontend still logs in exactly as before — this configuration changes only where registry traffic travels, not how anyone authenticates. https://api.<customer_istari_fqdn>/identity returns 502 until the Identity Service is deployed (Configuration 3) — the route always exists, but nothing backs it yet; that is expected, not an API Gateway misconfiguration.

Rollback

From chart 6.0, roll back with helm rollback <release> <previous-revision>. Setting apiGateway.enabled: false alone does not configure direct access. Update each client's Registry target and authentication settings before removing that route.

If you set VITE_ISTARI_DIGITAL_API_URL in the frontend Secret yourself — or ISTARI_DIGITAL_API_URL in the registry Secret — remove that key and re-apply the Secret as part of the rollback. A key you set in your Secret overrides the chart's value, so a stale value survives the rollback.

Reference: example_values/02-router-only.yaml.

Configuration 3: Gateway and Identity

This is the default configuration. Follow Set up with the provisioner for installation.

Prerequisites

• Configuration 2 already applied (or applied in the same release): the API Gateway deployed (apiGateway.enabled: true) and reachable at https://api.<customer_istari_fqdn>.
• Identity Service configured through the provisioner setup or manual setup.

Values to set

These are the default identity settings:

istari-values.yaml (excerpt)

apiGateway:
  enabled: true
  # Retain the Ingress settings from Configuration 2.
identity:
  enabled: true
  clientIntegration:
    enabled: true
  secretName: "istari-identity"

Identity Service needs no separate Ingress or DNS record; the gateway serves it at <api-host>/identity.

Order of operations

1. Complete Set up with the provisioner and verify the gateway readiness route. Keep the default Identity Service and client integration enabled for a standard installation.

2. If previously staged with identity.clientIntegration.enabled: false, set it to true explicitly and upgrade. Deleting the override does not reset a stored false.

3. Wait for the Deployments to roll:

   kubectl rollout status deployment/istari-fileservice
   kubectl rollout status deployment/istari-frontend
   kubectl rollout status deployment/istari-mcp   # only if MCP is deployed

Verification

Follow Verify a Registration and confirm frontend sign-in works.

Rollback

Two independent steps, matching the two toggles:

• Return clients to Zitadel: set identity.clientIntegration.enabled: false, upgrade, and wait for the Deployments to roll before testing sign-in. Preserve their Zitadel credentials. Identity Service and its database remain in place.
• Remove the Identity Service entirely: additionally set identity.enabled: false, as Scenario 10 describes.

Reference: example_values/03-router-and-identity.yaml.