DefaultInstance vs FirstInstance

[unique-dominik]

Preflight Checklist

• I could not find a solution in the existing issues, docs, nor discussions
• I have joined the ZITADEL chat

Describe the docs your are missing or that are wrong

As a administrator I want to be informed what the difference and impact of the DefaultInstance vs FirstInstance is.

---

I did now approx 1h of research and another 1h of trying and non-succeeding. What is the difference between DefaultInstance vs FirstInstance? 😭

Start of the problem is this section of the values or here respectively: https://zitadel.com/docs/self-hosting/manage/configure#whats-next.

DefaultInstance:
  InstanceName:
  DefaultLanguage: en
  Org:
    Name:
    Human:
     ...
      UserName: zitadel-admin-1
    ...

What does that do? I could not make the login on a fresh installation work. I expect that the DefaultInstance is also used for the systems own first instance if no FirstInstance is given.

FirstInstance:
  InstanceName:
  DefaultLanguage: en
  Org:
    Name:
    Human:
     ...
      UserName: zitadel-adm1n
    ...

What is now done? Who wins? What is the impact?

Another thing that I observe is that e.g. DefaultInstance.InstanceName does not even work 😢

I see I am not the only one:

• A
• B
  • here @eliobischof wrote the correct title but did not explain the difference

Could you either point me to the right docs (and I order the glasses) or provide them here or as docs? ❤️

Thank you 🏰

Additional Context

Discord username: m4mbax

The question could also be asked in the official zitadel repo, please feel free to suggest a move or move it.

FirstInstance Reference Link

For reference my current chart looks like this (I removed all user customisations for now as it was so confusing).

       zitadel:
          # The chart: https://github.com/zitadel/zitadel-charts/blob/main/charts/zitadel/values.yaml
          masterkey: {{ .Values.zitadel.mainKey | fetchSecretValue | quote }}
          configmapConfig:
            # All values: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
            ExternalDomain: {{ .Values.zitadel.hostName }} # ! Changing this breaks the system
            ExternalPort: 443 # ! Changing this breaks the system
            ExternalSecure: true # ! Changing this breaks the system
            LogStore:
              Access:
                Stdout:
                  Enabled: true
            TLS:
              Enabled: false # Application Gateway from Azure does this
            DefaultInstance:
              InstanceName: {{ .Values.zitadel.defaultInstanceName }}
          secretConfig:
            Database:
              cockroach:
                User:
                  Password: {{ .Values.zitadel.password | fetchSecretValue | quote }}

[hifabienne]

@eliobischof Can you give a feedback here?

[nejtr0n]

I have same issue.
For example.
My domain is example.com
I would like to deploy zitadel under subdomain
zitadel.example.com
So I configure zitadel with

ExternalDomain: example.com
FirstInstance:
  Org:
    Name: zitadel
    Human:
      Username: 'admin'

My organization domain is correct - zitadel.example.com
Admin user too - [email protected]

But im facing issue zitadel/zitadel#4452 Message=Instance not found

If I set ExternalDomain: zitadel.example.com
Everything working, but org domain becomes wrong - zitadel.zitadel.example.com
And admin user too - [email protected]

[fforootd]

I have same issue. For example. My domain is example.com I would like to deploy zitadel under subdomain zitadel.example.com So I configure zitadel with

ExternalDomain: example.com
FirstInstance:
  Org:
    Name: zitadel
    Human:
      Username: 'admin'

My organization domain is correct - zitadel.example.com Admin user too - [email protected]

But im facing issue zitadel/zitadel#4452 Message=Instance not found

If I set ExternalDomain: zitadel.example.com Everything working, but org domain becomes wrong - zitadel.zitadel.example.com And admin user too - [email protected]

The domain topic is a little confusing, sorry about that.

Zitadel knows two concepts.

1. The domain(s) that zitadel accepts to serve traffic, these are configured on a zitadel instance and not on a specific org.
2. The "verified" domain(s), these act as discovery feature to route for example users that have a specific mail address suffix to a disting org. I.e if the mail ends with @zitadel.com always use org zitadel

The admin user is a relict and is still created with the notation of {username}@{org}.{externaldomain}. This although you can use any domain name in Zitadel as long as it is unique inside one instance.

A screenshot below on how Zitadel uses the suffix in a org.

Hope this helps 😁