fix: clarify instances in steps and config (#4003)

* fix: clarify instances in steps and config

* docs: update setup step

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
Co-authored-by: Livio Amstutz <livio.a@gmail.com>

cmd/setup/03.go

@@ -16,9 +16,8 @@ import (
 	"github.com/zitadel/zitadel/internal/eventstore"
 )
 
-type DefaultInstance struct {
+type FirstInstance struct {
 	InstanceName    string
-	CustomDomain    string
 	DefaultLanguage language.Tag
 	Org             command.OrgSetup
 
@@ -33,9 +32,10 @@ type DefaultInstance struct {
 	externalDomain    string
 	externalSecure    bool
 	externalPort      uint16
+	domain            string
 }
 
-func (mig *DefaultInstance) Execute(ctx context.Context) error {
+func (mig *FirstInstance) Execute(ctx context.Context) error {
 	keyStorage, err := crypto_db.NewKeyStorage(mig.db, mig.masterKey)
 	if err != nil {
 		return fmt.Errorf("cannot start key storage: %w", err)
@@ -77,7 +77,7 @@ func (mig *DefaultInstance) Execute(ctx context.Context) error {
 	}
 
 	mig.instanceSetup.InstanceName = mig.InstanceName
-	mig.instanceSetup.CustomDomain = mig.CustomDomain
+	mig.instanceSetup.CustomDomain = mig.externalDomain
 	mig.instanceSetup.DefaultLanguage = mig.DefaultLanguage
 	mig.instanceSetup.Org = mig.Org
 	mig.instanceSetup.Org.Human.Email.Address = strings.TrimSpace(mig.instanceSetup.Org.Human.Email.Address)
@@ -89,7 +89,7 @@ func (mig *DefaultInstance) Execute(ctx context.Context) error {
 	return err
 }
 
-func (mig *DefaultInstance) String() string {
+func (mig *FirstInstance) String() string {
 	return "03_default_instance"
 }
 

cmd/setup/config.go

@@ -49,7 +49,7 @@ func MustNewConfig(v *viper.Viper) *Config {
 type Steps struct {
 	s1ProjectionTable *ProjectionTable
 	s2AssetsTable     *AssetTable
-	S3DefaultInstance *DefaultInstance
+	FirstInstance     *FirstInstance
 }
 
 type encryptionKeyConfig struct {

cmd/setup/setup.go

@@ -66,17 +66,17 @@ func Setup(config *Config, steps *Steps, masterKey string) {
 	steps.s1ProjectionTable = &ProjectionTable{dbClient: dbClient}
 	steps.s2AssetsTable = &AssetTable{dbClient: dbClient}
 
-	steps.S3DefaultInstance.instanceSetup = config.DefaultInstance
-	steps.S3DefaultInstance.userEncryptionKey = config.EncryptionKeys.User
-	steps.S3DefaultInstance.smtpEncryptionKey = config.EncryptionKeys.SMTP
-	steps.S3DefaultInstance.masterKey = masterKey
-	steps.S3DefaultInstance.db = dbClient
-	steps.S3DefaultInstance.es = eventstoreClient
-	steps.S3DefaultInstance.defaults = config.SystemDefaults
-	steps.S3DefaultInstance.zitadelRoles = config.InternalAuthZ.RolePermissionMappings
-	steps.S3DefaultInstance.externalDomain = config.ExternalDomain
-	steps.S3DefaultInstance.externalSecure = config.ExternalSecure
-	steps.S3DefaultInstance.externalPort = config.ExternalPort
+	steps.FirstInstance.instanceSetup = config.DefaultInstance
+	steps.FirstInstance.userEncryptionKey = config.EncryptionKeys.User
+	steps.FirstInstance.smtpEncryptionKey = config.EncryptionKeys.SMTP
+	steps.FirstInstance.masterKey = masterKey
+	steps.FirstInstance.db = dbClient
+	steps.FirstInstance.es = eventstoreClient
+	steps.FirstInstance.defaults = config.SystemDefaults
+	steps.FirstInstance.zitadelRoles = config.InternalAuthZ.RolePermissionMappings
+	steps.FirstInstance.externalDomain = config.ExternalDomain
+	steps.FirstInstance.externalSecure = config.ExternalSecure
+	steps.FirstInstance.externalPort = config.ExternalPort
 
 	repeatableSteps := []migration.RepeatableMigration{
 		&externalConfigChange{
@@ -92,7 +92,7 @@ func Setup(config *Config, steps *Steps, masterKey string) {
 	logging.OnError(err).Fatal("unable to migrate step 1")
 	err = migration.Migrate(ctx, eventstoreClient, steps.s2AssetsTable)
 	logging.OnError(err).Fatal("unable to migrate step 2")
-	err = migration.Migrate(ctx, eventstoreClient, steps.S3DefaultInstance)
+	err = migration.Migrate(ctx, eventstoreClient, steps.FirstInstance)
 	logging.OnError(err).Fatal("unable to migrate step 3")
 
 	for _, repeatableStep := range repeatableSteps {

cmd/setup/steps.yaml

@@ -1,6 +1,5 @@
-S3DefaultInstance:
-  InstanceName: Localhost
-  CustomDomain: localhost
+FirstInstance:
+  InstanceName: ZITADEL
   DefaultLanguage: en
   Org:
     Name: ZITADEL

deploy/knative/zitadel-knative-service.yaml

@@ -28,8 +28,6 @@ spec:
           value: 80
         - name: ZITADEL_EXTERNALDOMAIN
           value: zitadel.default.127.0.0.1.sslip.io
-        - name: ZITADEL_S3DEFAULTINSTANCE_CUSTOMDOMAIN
-          value: zitadel.default.127.0.0.1.sslip.io
         image: ghcr.io/zitadel/zitadel:v2.0.0-v2-alpha.39-amd64
         name: user-container
         ports:

docs/docs/guides/installation/configure/_linuxunix.mdx

@@ -47,8 +47,8 @@ zitadel start-from-init \
 export ZITADEL_DATABASE_HOST="my.database"
 export ZITADEL_DATABASE_USER_USERNAME="my_zitadel_db_user"
 export ZITADEL_DATABASE_USER_PASSWORD="Secret_DB_User_Password"
-export ZITADEL_S3DEFAULTINSTANCE_ORG_HUMAN_USERNAME="root"
-export ZITADEL_S3DEFAULTINSTANCE_ORG_HUMAN_PASSWORD="RootPassword1!"
+export ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME="root"
+export ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD="RootPassword1!"
 
 # A single ZITADEL instance always needs the same 32 characters long masterkey
 # If you haven't done so already, you can generate a new one

docs/docs/guides/installation/configure/configure.mdx

@@ -32,7 +32,7 @@ Other configration that contains information like your databases admin username
 
 All configuration properties are also configurable via environemnt variables.
 Prefix the key with *ZITADEL\_*, uppercase the propery and join sections by an underscore _.
-For example, if you want to configure the default ZITADEL IAM admin username and password, make sure the ZITADEL binary runtime has the variables *ZITADEL_S3DEFAULTINSTANCE_ORG_HUMAN_USERNAME* and *ZITADEL_S3DEFAULTINSTANCE_ORG_HUMAN_PASSWORD* set.
+For example, if you want to configure the default ZITADEL IAM admin username and password, make sure the ZITADEL binary runtime has the variables *ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME* and *ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD* set.
 
 ## Masterkey
 

docs/docs/guides/installation/configure/example-zitadel-init-steps.yaml

@@ -1,5 +1,5 @@
 # All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/adminn/setup/steps.yaml
-S3DefaultInstance:
+FirstInstance:
   Org:
     Human:
       # use the loginname root@zitadel.localhost

docs/docs/guides/installation/configure/example-zitadel-values.yaml

@@ -9,7 +9,7 @@ zitadel:
     ExternalDomain: localhost
 
     # the configmap is also passed to the zitadel binary via the --steps flag
-    S3DefaultInstance:
+    FirstInstance:
       Org:
         Human:
           # use the loginname root@zitadel.localhost

docs/docs/guides/installation/custom-domain.md

@@ -22,13 +22,8 @@ ExternalPort: 443
 ## Database Initialization Steps Config
 
 ZITADEL creates random subdomains for each instance created.
-However, for the default instance, this is most probably not the desired behavior.
-You can give the default instance a fixed custom domain here.
-
-```yaml
-S3DefaultInstance:
-  CustomDomain: 'zitadel.my.domain'
-```
+However, for the first instance, this is most probably not the desired behavior.
+In this case the `ExternalDomain`-field of the configuration is used.
 
 ## Example
 

docs/docs/guides/installation/loadbalancing-example/example-zitadel-init-steps.yaml

@@ -1,6 +1,5 @@
 # All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/adminn/setup/steps.yaml
-S3DefaultInstance:
-  CustomDomain: my.domain
+FirstInstance:
   Org:
     Name: 'My Org'
     Human:

docs/docs/guides/installation/run/_knative.mdx

@@ -42,7 +42,6 @@ kn service create zitadel \
 --env ZITADEL_EXTERNALPORT=80 \
 --env ZITADEL_TLS_ENABLED=false \
 --env ZITADEL_EXTERNALDOMAIN=zitadel.default.127.0.0.1.sslip.io \
---env ZITADEL_S3DEFAULTINSTANCE_CUSTOMDOMAIN=zitadel.default.127.0.0.1.sslip.io \
 --arg "start-from-init" --arg "--masterkey" --arg "MasterkeyNeedsToHave32Characters" 
 ```