andwati/zitadel
1
0
Fork 0
mirror of https://github.com/andwati/zitadel.git synced 2026-10-18 05:52:51 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
zitadel/cmd/setup/steps.yaml
T
SilvanGitHubCursor AgentSilvan
 3ff4fbc7e4 fix(eventstore): add owners to unique constraints (#12740) 
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
# Which Problems Are Solved

Bulk unique-constraint deletes (org, IDP with many links, user, project)
reconstruct every uniqueness key in Go and emit N `DELETE`s. That can
OOM on large tenants.

A one-shot owner backfill is also not enough: during a rolling deploy,
older binaries still insert `owners = '{}'`, so a later owner-only
delete would miss those rows.

Owner-only org/user/grant delete only matches rows whose `owners` bag
contains that tag. Several grant and member types stamped the aggregate
resource owner, which is not always the user’s home org or the granted
org. Username-scope rewrites also dropped `user:` tags, so owner-only
user delete could miss rewritten username rows.

Command must not switch to owner-only delete on the first 79 of a
version, because leftover `'{}'` rows from rolling-update overlap are
only backfilled on a later 79. A failed 79 must not turn owner-delete
on, and backfill joins must not stamp the wrong org (unverified domains,
org-scoped usernames colliding with instance-scoped ones).

# How the Problems Are Solved

Uniqueness stays the existing primary key `(instance_id, unique_type,
unique_field)`. `owners` is only a lifecycle bag of tags (`org:<id>`,
`user:<id>`, `idp:<id>`, `project:<id>`, `grant:<id>`).

- Add `owners TEXT[] NOT NULL DEFAULT '{}'` on
`eventstore.unique_constraints` (init SQL for greenfield, setup 78 for
existing clusters).
- Create `unique_constraints_owners_gin` with `CREATE INDEX
CONCURRENTLY` **outside a transaction** (same pattern as step 76).
Built-in `GIN (owners)` only; no `btree_gin`.
- Stamp `WithOwners` on **add** events. Field-level removes ignore
owners. `RemoveByOwner` stores the tag in `Owners` and both v1/v3 and v2
pushers run `DELETE … WHERE instance_id = $1 AND owners @>
ARRAY[$tag]::text[]`.
- Setup 79 backfills `owners` from projections via numbered
`cmd/setup/79/*.sql` files. Table names are interpolated from
`internal/query/projection` constants. Matches use `unique_field IN (x,
lower(x))` so the primary key can be used. Missing projection tables
(`42P01`) are skipped.
- Org domains are tagged only when `is_verified`. Instance-scoped
usernames join only users that are not org-scoped (organization settings
or domain policy `user_login_must_be_domain`). Every username row still
gets `org:` + `user:` of that user.
- 79 is a **repeatable** migration. `Check` re-runs when
`lastRun["version"]` changed or when setup-only `ForceFinalize` is set
and `lastRun["finalized"]` is still false. `Finalized` is written only
after Execute succeeds.
- Failed setup events keep the last successful `lastRun`. Command reads
`finalized` only from `system.migration.repeatable.done`.
- Org / user / project remove skip N-key event replay **when that
`finalized` bit is true**. Otherwise they keep today’s N-key lists
**and** still emit `RemoveByOwner`. The “ready” result is cached in
memory once true.

Setup writes `finalized` on the 79 repeatable.done payload:

- First 79 of a version: backfill only, `finalized=false` (unless
`ForceFinalize` is already set).
- Later 79: version change or
`BackfillUniqueConstraintOwners.ForceFinalize` /
`ZITADEL_BACKFILLUNIQUECONSTRAINTOWNERS_FORCEFINALIZE` after the rolling
update is done. That run backfills leftovers and writes
`finalized=true`.

Member and grant owner bags now include every org that should delete the
row:

- Instance, org, and project members also stamp
`org:<user_resource_owner>`.
- User grants stamp grant, user, project, and granted orgs.
- Project grant members stamp the project org, user org, and granted
org.
- Project grants stamp both orgs plus `grant:<id>`. Grant remove emits
`RemoveByOwner(grant)`.
- Username-scope rewrites keep `user:<id>` as well as `org:`.
- User/grant orgs are carried as unexported add-event fields (not
persisted JSON). `WithOwners` skips empty and duplicate tags.

# Additional Changes

- Table-driven owner-tag tests, including project grant (two `org:` tags
plus `grant:`), cross-org members, user grants, and username-scope
rewrite `user:` tags.
- Table-driven 79 `Check` + `finalizeAfterSuccess` tests for version
change, sequential version bumps, ForceFinalize restart, and
already-finalized skip.
- Command tests: a failed 79 event with `finalized=true` does not enable
owner-delete.
- Integration fixtures (verified vs unverified org domain;
instance-scoped `bob` vs org-scoped `bob`).
- Instance-only and global unique types stay untagged (`'{}'`). Instance
wipe still uses `UniqueConstraintInstanceRemove`.
- Pusher owner cases live in `eventstore_pusher_owners_test.go` so
`eventstore_pusher_test.go` stays under 1k lines.

# Additional Context

A later cleanup can delete the N-key replay helpers once a release that
ran 79 a second time (or an operator who set `ForceFinalize`) is in
production. That is not required for correctness.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-44f9bc9b-9a93-4cd9-8dd1-663a7b9aad2a?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-44f9bc9b-9a93-4cd9-8dd1-663a7b9aad2a&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Silvan <[email protected]>
2026-09-18 15:08:42 +02:00

193 lines
11 KiB
YAML
Raw Permalink Blame History

Instrumentation:
ServiceName: "zitadel-setup" # ZITADEL_INSTRUMENTATION_SERVICENAME
Trace:
Fraction: 1.0 # ZITADEL_INSTRUMENTATION_TRACE_FRACTION
# Trust incoming trace context from remote services for distributed tracing.
# Enable only in controlled environments; defaults to false for security.
TrustRemoteSpans: false # ZITADEL_INSTRUMENTATION_TRACE_TRUSTREMOTESPANS
Exporter:
# The following exporter types are supported:
# "none": Disables trace exporting
# "stdOut": Exports traces to standard output
# "stdErr": Exports traces to standard error
# "grpc": Exports traces using the OTEL gRPC exporter (recommended)
# "http": Exports traces using the OTEL HTTP exporter
# "google": Exports traces to Google Cloud. Need to configure GoogleProjectID below!
Type: "none" # ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_TYPE
# Endpoint of the OTEL collector for grpc and http exporters
Endpoint: "" # ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_ENDPOINT
# Disable TLS for grpc and http exporters
Insecure: false # ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_INSECURE
# Interval for batching traces before export
BatchDuration: 1s # ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_BATCHDURATION
# Project ID for Google Cloud Trace exporter
GoogleProjectID: "" # ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_GOOGLEPROJECTID
Metric:
Exporter:
# The following exporter types are supported:
# "none": Disables metric exporting
# "stdOut": Exports metrics to standard output
# "stdErr": Exports metrics to standard error
# "grpc": Exports metrics using the OTEL gRPC exporter (recommended)
# "http": Exports metrics using the OTEL HTTP exporter
# "google": Exports metrics to Google Cloud. Need to configure GoogleProjectID below!
# "prometheus": Exposes metrics via an HTTP endpoint for Prometheus to scrape
Type: "none" # ZITADEL_INSTRUMENTATION_METRIC_EXPORTER_TYPE
# Endpoint of the OTEL collector for grpc and http exporters
Endpoint: "" # ZITADEL_INSTRUMENTATION_METRIC_EXPORTER_ENDPOINT
# Disable TLS for grpc and http exporters
Insecure: false # ZITADEL_INSTRUMENTATION_METRIC_EXPORTER_INSECURE
# Interval at which metrics are exported
BatchDuration: 1m # ZITADEL_INSTRUMENTATION_METRIC_EXPORTER_BATCHDURATION
# Project ID for Google Cloud Trace exporter
GoogleProjectID: "" # ZITADEL_INSTRUMENTATION_METRIC_EXPORTER_GOOGLEPROJECTID
# Structured logging can print logs on standard error and/or export them using OTEL.
Log:
# Log lines lower than this level are not emitted.
Level: "INFO" # ZITADEL_INSTRUMENTATION_LOG_LEVEL
# Streams enable logging for specific parts of the application.
Streams: # ZITADEL_INSTRUMENTATION_LOG_STREAMS (comma separated list)
- runtime # General runtime logs, such as startup and shutdown messages.
- ready # Logs related to readiness and health checks. (zitadel ready command)
- request # Logs for incoming API and HTTP requests.
- event_handler # Logs for event handling in projections.
- queue # Logs for the job queue processing.
# - event_pusher # Logs for event pushing to the database. Warning: contains sensitive information.
# Mask replaces sensitive information with Value in logs matched by Key
Mask:
# Keys are the attribute keys to be masked in logs.
# Keys are unqualified attribute names and apply to all attributes with the specified name,
# regardless of their position in the attribute hierarchy.
# Eg. "some_key" matches "some_key" and "parent.some_key" etc.
# When the key matches a group of attributes (e.g. slog.Group), all attribute values in the
# group are masked and the structure of the group is preserved.
# When the key matches a non-group attribute whose value is a nested object/array
# (e.g. added via slog.Any), the entire value is replaced with Value and its structure is not preserved.
Keys: # ZITADEL_INSTRUMENTATION_LOG_MASK_KEYS (comma separated list)
# - "first_name"
# - "last_name"
# Value is the string that replaces the original value of masked attributes.
Value: "****" # ZITADEL_INSTRUMENTATION_LOG_MASK_VALUE
# Enable printing structured logs to standard error in the specified format.
# When disabled, the legacy Log configuration is used.
# Important: when legacy Log is customized, please add a format and customize before upgrading to v5
# The following formats are supported:
# - "disabled": Disables logging (or fallback to legacy Log config)
# - "text": Logs are printed on StdErr as human-readable text
# - "json": Logs are printed on StdErr as JSON objects
# - "gcp": JSON formatted logs compatible with Google Cloud Platform logging.
# - "gcp_error_reporting": JSON formatted logs compatible with Google Cloud Platform Error Reporting.
Format: "disabled" # ZITADEL_INSTRUMENTATION_LOG_STDERR
# Adds the source file and line number where the log line was emitted.
# Not to be confused with the source of an error.
AddSource: true # ZITADEL_INSTRUMENTATION_LOG_ADDSOURCE
# Configure how errors are logged.
Errors:
# Adds the source file, line number and function where the error was created.
ReportLocation: true # ZITADEL_INSTRUMENTATION_LOG_ERRORS_REPORTLOCATION
# Adds stack traces to logged errors.
StackTrace: false # ZITADEL_INSTRUMENTATION_LOG_ERRORS_STACKTRACE
Exporter:
# The following exporter types are supported:
# - "none": Disables OTEL log exporter
# - "stdOut": Exports OTEL logs to standard output
# - "stdErr": Exports OTEL logs to standard error
# - "grpc": Exports OTEL logs using the OTEL gRPC exporter (recommended)
# - "http": Exports OTEL logs using the OTEL HTTP exporter
Type: "none" # ZITADEL_INSTRUMENTATION_LOG_EXPORTER_TYPE
# Endpoint of the OTEL collector for grpc and http exporters
Endpoint: "" # ZITADEL_INSTRUMENTATION_LOG_EXPORTER_ENDPOINT
# Disable TLS for grpc and http exporters
Insecure: false # ZITADEL_INSTRUMENTATION_LOG_EXPORTER_INSECURE
# Interval at which metrics are exported
BatchDuration: 1s # ZITADEL_INSTRUMENTATION_LOG_EXPORTER_BATCHDURATION
Profile:
Exporter:
# The following profiler types are supported:
# "none": Disables profiling
# "google": Exports profiling data to Google Cloud Profiler
Type: "none" # ZITADEL_INSTRUMENTATION_PROFILE_TYPE
# Project ID for Google Cloud Profiler
GoogleProjectID: "" # ZITADEL_INSTRUMENTATION_PROFILE_GOOGLEPROJECTID
# By using the FirstInstance section, you can overwrite the DefaultInstance configuration for the first instance created by zitadel setup.
FirstInstance:
# If set to true zitadel is setup without initial data
Skip: false
# The machine key from the section FirstInstance.Org.Machine.MachineKey is written to the MachineKeyPath.
MachineKeyPath: # ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH
# The personal access token from the section FirstInstance.Org.Machine.Pat is written to the PatPath.
PatPath: # ZITADEL_FIRSTINSTANCE_PATPATH
LoginClientPatPath: # ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH
InstanceName: ZITADEL # ZITADEL_FIRSTINSTANCE_INSTANCENAME
# A list of trusted domains, which are allowed to be used for public responses like email links or when running
# ZITADEL or the login UI behind a reverse proxy. If no trusted domain is set, the instance domain is used.
TrustedDomains: # ZITADEL_FIRSTINSTANCE_TRUSTEDDOMAINS
# - login.example.com
# - api.example.com
DefaultLanguage: en # ZITADEL_FIRSTINSTANCE_DEFAULTLANGUAGE
Org:
Name: ZITADEL # ZITADEL_FIRSTINSTANCE_ORG_NAME
# In the FirstInstance.Org.Human section, the initial organization's admin user with the role IAM_OWNER is defined.
# If FirstInstance.Org.Machine.Machine is defined, a service account is created with the IAM_OWNER role.
Human:
# In case UserLoginMustBeDomain is false (default) and you don't overwrite the username with an email,
# it will be suffixed by the Organization Domain (org-name + domain from config).
# for example zitadel-admin in org ZITADEL on domain.tld -> [email protected]
UserName: zitadel-admin # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME
FirstName: ZITADEL # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_FIRSTNAME
LastName: Admin # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_LASTNAME
NickName: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_NICKNAME
DisplayName: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_DISPLAYNAME
Email:
# uses the username if empty
Address: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS
Verified: true # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_VERIFIED
PreferredLanguage: en # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PREFERREDLANGUAGE
Gender: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_GENDER
Phone:
Number: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PHONE_NUMBER
Verified: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PHONE_VERIFIED
Password: Password1! # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD
PasswordChangeRequired: true # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED
# In the FirstInstance.Org.Machine section, the initial organization's admin user with the role IAM_OWNER is defined.
# If FirstInstance.Org.Machine.Machine is defined, a service account is created with the IAM_OWNER role.
Machine:
Machine:
Username: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME
Name: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME
MachineKey:
# date format: 2023-01-01T00:00:00Z
ExpirationDate: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_EXPIRATIONDATE
# Currently, the only supported value is 1 for JSON
Type: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE
Pat:
# date format: 2023-01-01T00:00:00Z
ExpirationDate: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_PAT_EXPIRATIONDATE
LoginClient:
Machine:
Username: # ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_USERNAME
Name: # ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME
Pat:
# date format: 2023-01-01T00:00:00Z
ExpirationDate: # ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_EXPIRATIONDATE
CorrectCreationDate:
FailAfter: 5m # ZITADEL_CORRECTCREATIONDATE_FAILAFTER
AddEventCreatedAt:
BulkAmount: 100 # ZITADEL_ADDEVENTCREATEDAT_BULKAMOUNT
FillFields:
BatchSize: 1000 # ZITADEL_EVENTSTORE_FILLFIELDS_BULKLIMIT
RelationalTables:
# This is used for development DO NOT USE IN PRODUCTION
ShouldRecreateSchema: false # ZITADEL_RELATIONALTABLES_SHOULDRECREATESCHEMA
BackfillUniqueConstraintOwners:
# After a rolling update on this same version, set true and re-run setup to
# backfill leftover empty owners and enable owner-only unique-constraint delete.
# Default false: owner-delete waits until the next release runs 79 again.
ForceFinalize: false # ZITADEL_BACKFILLUNIQUECONSTRAINTOWNERS_FORCEFINALIZE
Reference in New Issue View Git Blame Copy Permalink