Create the first Platform Administrator

Where this runbook applies

This runbook applies to any installation with the Identity Service enabled, which means both identity.enabled and identity.clientIntegration.enabled are true in the istari-platform chart values. The Helm values that enable the Identity Service set both.

When the Identity Service is first enabled, nobody holds the Platform Administrator role, and the platform chart does not grant it. Until someone holds the role, nobody can open the Platform Admin Console to create tenants or appoint administrators. An operator grants the first one from the command line with ensure-platform-admins.

The same command restores the role when no Platform Administrator remains. It skips a suspended person, so reinstate them first.

Prerequisites

• kubectl access to the cluster.
• The Identity Service image tag you deployed, 2.0.0 or later. Earlier images do not include ensure-platform-admins.
• The istari-identity secret and the docker-pull-secret image pull secret, in the namespace where the Identity Service runs. The command below uses them; if yours have other names, change them in the command.
• The tenant the person will sign in through. From istari-platform chart 6.2.0, the chart's Zitadel import creates a tenant for each Zitadel organization its key's machine user is a member of. Otherwise, create the tenant from the command line as in Tenants.
• The person's Zitadel account in that tenant's organization, with a verified email address. The command writes nothing to Zitadel.
• The organization's ID, found as in Finding your Zitadel organization ID, or the tenant's slug.

Steps

1. Run ensure-platform-admins as a one-off pod in the namespace where the Identity Service runs. Add -n <namespace> if that is not your current namespace. In the command, replace:

   • <tag> with the Identity Service image tag;
   • <organization id> with the organization's ID, or replace the -organization pair with "-tenant","<slug>";
   • <email> with the person's email address.

   kubectl run ensure-platform-admins --rm -i --restart=Never \
     --image=istaridigital.jfrog.io/customer-docker/identity-service:<tag> \
     --overrides='{
       "spec":{
         "imagePullSecrets":[{"name":"docker-pull-secret"}],
         "containers":[{
           "name":"ensure-platform-admins",
           "image":"istaridigital.jfrog.io/customer-docker/identity-service:<tag>",
           "command":["/ensure-platform-admins"],
           "args":["-database-url-env","ISTARI_DIGITAL_IDENTITY_SERVICE_DATABASE_URL",
                   "-organization","<organization id>",
                   "-email","<email>"],
           "envFrom":[{"secretRef":{"name":"istari-identity"}}]
         }]}
     }'

   Flag	Meaning
   -email	A person who should hold the Platform Administrator role. Repeat "-email","<email>" for each person.
   -organization	The Zitadel organization whose tenant the person signs in through. The command pre-registers anyone it does not know yet in that tenant. Give this flag or -tenant. With neither, the command falls back to ISTARI_DIGITAL_IDENTITY_SERVICE_ZITADEL_ORG_ID; the Zitadel Configurator does not set it, and without it the command pre-registers nobody.
   -tenant	The tenant, by its slug, in place of -organization.

   The pod loads the istari-identity secret, which supplies the database connection string for -database-url-env and any AUDIT_* settings. Running the command again changes nothing that is already in place, and it never revokes the role from anyone.

2. Read the line the command prints for each address.

   Output	Meaning
   <email>: pre-registered and granted the platform administrator role, principal <id>	Nobody had this address. The command created the person's record in advance; their first sign-in through the organization takes it over.
   <email>: granted the platform administrator role, principal <id>	The person had signed in with a verified email, or an earlier run created their record, and now holds the role.
   <email>: principal <id> already holds the platform administrator role	Nothing to do.
   WARNING: <email> skipped: <reason>	The command granted nothing to this address; the reason says why.

   A person who belongs to a different tenant from the one you gave is skipped. To grant them the role, either:

   • run the command again with their tenant's organization ID or slug; or
   • run grant-platform-role as a one-off pod like the command above, with "command":["/grant-platform-role"] and the same -database-url-env and -email arguments.

   A final WARNING: no platform administrator exists means nobody holds the role after this run. Fix the skipped addresses and run the command again.

3. Verify. The person signs in at https://<customer_istari_fqdn> with their Zitadel account and can open the Platform Admin Console. From there they appoint other administrators.