mz_environmentd/deployment.rs
1// Copyright Materialize, Inc. and contributors. All rights reserved.
2//
3// Use of this software is governed by the Business Source License
4// included in the LICENSE file.
5//
6// As of the Change Date specified in that file, in accordance with
7// the Business Source License, use of this software will be governed
8// by the Apache License, Version 2.0.
9
10//! Environment deployments.
11//!
12//! A deployment is a graceful transition of an environment to a new version or
13//! configuration [^1]. This module provides the components that facilitate
14//! these deployments.
15//!
16//! Deployments are initiated and driven externally to `environmentd`. At a very
17//! high level, the process works like this:
18//!
19//! 1. The external orchestrator starts a new `environmentd` process with a
20//! deploy generation that is greater than the previous deploy generation
21//! (e.g., if the current deploy generation is 1, the new `environmentd`
22//! process should be started with `--deploy-generation=2`).
23//!
24//! 2. The new `environmentd` process initializes to the extent possible. At
25//! the moment the initialization process is quite weak and only validates
26//! that the catalog is loadable. We plan to strengthen the initialization
27//! process over time to include starting all `clusterd` processes in the
28//! new deployment and ensuring that they rehydrate successfully.
29//!
30//! 3. The new deployment announces that it is ready to take over from the
31//! previous generation (`ReadyToPromote`) via the internal HTTP server.
32//!
33//! 4. The external orchestrator promotes the new deployment via the HTTP
34//! server.
35//!
36//! 5. The new deployment completes any remaining initialization tasks and
37//! prepares to serve queries.
38//!
39//! 6. Simultaneously, the external orchestrator tears down the old
40//! deployment.
41//!
42//! [^1] "Configuration" here means "command-line flags". Most settings in an
43//! environment are changeable at runtime via LaunchDarkly feature flags, but
44//! occasionally we have settings that are only changeable via command-line
45//! flags to `environmentd`. Changing these flags requires a process restart,
46//! and performing that process restart without incurring unavailability
47//! requires this deployment infrastructure.
48
49pub mod preflight;
50pub mod state;