chore: rename IAM to instance (#11351)

# Which Problems Are Solved

In many cases IAM was used where instance was meant. 

# How the Problems Are Solved

- Rename wrong usage of IAM to instance all over the code base.
- Add an agents.md which explains the terms used in Zitadel's
architecture.

# Additional Context

- closes #11280

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: muhlemmer <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Marco A. <[email protected]>
This commit is contained in:
Tim Möhlmann
2026-02-10 20:25:39 +01:00
committed by GitHub
co-authored by Copilot muhlemmer Copilot Marco A.
parent 67a02a6aeb
commit 5a2181bcec
110 changed files with 392 additions and 478 deletions
@@ -68,7 +68,7 @@ To use private information — such as a database admin credential — without s
All configuration properties are configurable using environment variables.
ZITADEL environment variable keys are prefixed with `ZITADEL_`.
For example, to configure the default ZITADEL IAM admin username and password set the `zitadel` binary runtime environment variables `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME` and `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD`.
For example, to configure the default ZITADEL instance admin username and password set the `zitadel` binary runtime environment variables `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME` and `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD`.
All supported environment variables are listed in the [runtime configuration file](#runtime-configuration-file) and the [database initialization file](#database-initialization-file).
### Proxy configuration
@@ -17,7 +17,7 @@ In the following URLs, replace the base URL and the user ID according to your en
1. Create a new machine user, for example at http://localhost:8080/ui/console/users/create-machine
2. Create a PAT, for example at http://localhost:8080/ui/console/users/332169800719532035?new=true&id=pat
3. Save the PAT to a file, for example `/path/on/your/host/login-client.pat`
4. Make sure the user has the `Iam Login Client` role (internally called `IAM_LOGIN_CLIENT`), for example at http://localhost:8080/ui/console/instance/members
4. Make sure the user has the `Instance Login Client` role (internally called `IAM_LOGIN_CLIENT`), for example at http://localhost:8080/ui/console/instance/members
# Configure the Login UI
@@ -32,9 +32,9 @@ docker run -p 3000:3000 -v /path/on/your/host/login-client.pat:/path/in/containe
# Enable the Login UI for all users
<Callout type="warn">
Before doing this, make sure you have a working PAT for an Iam Owner user.
Before doing this, make sure you have a working PAT for an instance Owner user.
In case something goes wrong and you lock yourself out from the login screen, you can revert the changes.
Create a machine user PAT like you created the [login client PAT above](#create-login-client), but give the user the Iam Owner role (internally called `IAM_OWNER`).
Create a machine user PAT like you created the [login client PAT above](#create-login-client), but give the user the instance Owner role (internally called `IAM_OWNER`).
</Callout>
Enable the `Login V2` feature flag, for example at the bottom of http://localhost:8080/ui/console/instance?id=features.
@@ -78,7 +78,7 @@ services:
# Set up a service account with IAM_LOGIN_CLIENT role and write the PAT to the file ./login-client.pat
ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH: /current-dir/login-client.pat
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_USERNAME: login-client
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME: Automatically Initialized IAM Login Client
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME: Automatically Initialized instance Login Client
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_EXPIRATIONDATE: '2029-01-01T00:00:00Z'
# The master key is used to
networks: