diff --git a/docs/docs/self-hosting/manage/production.md b/docs/docs/self-hosting/manage/production.md index 27ab0c2fcd..50d09273d4 100644 --- a/docs/docs/self-hosting/manage/production.md +++ b/docs/docs/self-hosting/manage/production.md @@ -7,7 +7,12 @@ you are ready to configure ZITADEL for production usage. ## High Availability -We recommend running ZITADEL highly available using an orchestrator that schedules ZITADEL on multiple servers, like [Kubernetes]/docs/self-hosting/deploy/kubernetes). For keeping startup times fast when scaling ZITADEL, you should also consider using separate jobs with `zitadel init` and `zitadel setup`, so your workload containers just have to execute `zitadel start`. +We recommend running ZITADEL highly available using an orchestrator that schedules ZITADEL on multiple servers, +like [Kubernetes](/docs/self-hosting/deploy/kubernetes). +For keeping startup times fast when scaling ZITADEL, +you should also consider using separate jobs with `zitadel init` and `zitadel setup`, +so your workload containers just have to execute `zitadel start`. +Read more about separating the init and setup phases on the [Updating and Scaling page](/docs/self-hosting/manage/updating_scaling). ## Configuration diff --git a/docs/docs/self-hosting/manage/updating_scaling.md b/docs/docs/self-hosting/manage/updating_scaling.md new file mode 100644 index 0000000000..15e29cc674 --- /dev/null +++ b/docs/docs/self-hosting/manage/updating_scaling.md @@ -0,0 +1,83 @@ +--- +title: Updating and Scaling +--- + +## TL;DR + +For getting started easily, you can just combine the init, setup and runtime phases +by executing the `zitadel` binary with the argument `start-from-init`. +However, to improve day-two-operations, +we recommend you run the init phase and the setup phase +separately using `zitadel init` and `zitadel setup` respectively. +Both the init and the setup phases are idempotent, +meaning you can run them as many times as you want whithout unexpectedly changing any state. +Nevertheless, they just __need__ to be run at certain points in time, whereas further runs are obsolete. +The init phase has to run once over the full ZITADEL lifecycle, before the setup and runtime phases run first. +The setup phase has to run each time a new ZITADEL version is deployed. +After init and setup is done, you can start the runtime phase, that immediately accepts traffic, using `zitadel start`. + +## Scaling ZITADEL + +For production setups, we recommend that you [run ZITADEL in a highly available mode](/docs/self-hosting/manage/production). +As all shared state is managed in the database, +the ZITADEL binary itself is stateless. +You can easily run as many ZITADEL binaries in parallel as you want. +If you use [Knative](/docs/self-hosting/deploy/knative) +or [Google Cloud Run](https://cloud.google.com/run) (which uses Knative, too), +you can even scale to zero. +Especially if you use an autoscaler that scales to zero, +it is crucial that you minimize startup times. + +## Updating ZITADEL + +When want to deploy a new ZITADEL version, +the new versions setup phase takes care of database migrations. +You generally want to run the job in a controlled manner, +so multiple executions don’t interfere with each other. +Also, after the setup is done, +rolling out a new ZITADEL version is much faster +when the runtime processes are just executed with `zitadel start`. + +## Separating Init and Setup from the Runtime + +If you use the [official ZITADEL Helm chart](/docs/self-hosting/deploy/kubernetes), +then you can stop reading now. +The init and setup phases are already separated and executed in dedicated Kubernetes Jobs. +If you use another orchestrator and want to separate the phases yourself, +you should know what happens during these phases. + +### The Init Phase + +The command `zitadel init` ensures the database connection is ready to use for the subsequent phases. +It just needs to be executed once over ZITADELs full life cycle, +when you install ZITADEL from scratch. +During `zitadel init`, for connecting to your database, +ZITADEL uses the privileged and preexisting database user configured in `Database..Admin.Username`. +, `zitadel init` ensures the following: +- If it doesn’t exist already, it creates a database with the configured database name. +- If it doesn’t exist already, it creates the unprivileged user use configured in `Database..User.Username`. + Subsequent phases connect to the database with this user's credentials only. +- If not already done, it grants the necessary permissions ZITADEL needs to the non privileged user. +- If they don’t exist already, it creates all schemas and some basic tables. + +### The Setup Phase + +During `zitadel setup`, ZITADEL creates projection tables and migrates existing data. +Depending on the ZITADEL version and the runtime resources, +this step can take several minutes. +When deploying a new ZITADEL version, +make sure the setup phase runs before you roll out the new `zitadel start` processes. +The setup phase is executed in subsequent steps +whereas a new version's execution takes over where the last execution stopped. +Therefore, configuration changes relevant for the setup phase won’t take effect in regard to the setup execution. + +### The Runtime Phase + +The `zitadel start` command assumes the database is already initialized and set up. +It starts serving requests within fractions of a second. +Beware, in the background, out-of-date projections +[recompute their state by replaying all missed events](/docs/concepts/eventstore/implementation#projections). +If a new ZITADEL version is deployed, this can take quite a long time, +depending on the amount of events to catch up. +You probably should consider manually migrating these projections first. +Refer to the [release notes for v2.14.0](https://github.com/zitadel/zitadel/releases/tag/v2.14.0) as an example. diff --git a/docs/sidebars.js b/docs/sidebars.js index 54eee6fee7..6df184f858 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -275,6 +275,7 @@ module.exports = { "self-hosting/manage/http2", "self-hosting/manage/tls_modes", "self-hosting/manage/database/database", + "self-hosting/manage/updating_scaling", ], }, ],