Document your first cloud deployment as a procedure
Document a first cloud deployment through its artifact, environment inputs, user-path verification and recovery procedure.
A first cloud deployment is easier to learn from when you document it as a procedure another person could follow. I want the notebook to explain the input artifact, configuration source, verification and recovery path. A page of copied commands can reproduce activity while leaving the actual deployment model unclear.
Use a hypothetical preview service that displays a small catalog from fictional data. The environment has no real customer traffic. That keeps the first exercise focused on how code becomes a running application and how you recognize when the result differs from the intended version.
Record the deployment inputs
Start with the source revision or build artifact. Write which version you intend to deploy and how the artifact is produced. If the platform builds from source, identify the build command and dependency lockfile. If it receives a prebuilt artifact, identify that artifact and the assumptions made during its build.
Configuration is a separate input. List the names and purpose of required settings without placing secret values in the notebook. Distinguish build-time values from runtime values. A public frontend value embedded during a build cannot be changed merely by editing a server’s runtime environment afterward.
The AWS Well-Architected Framework treats operational excellence, security and reliability as design concerns alongside performance and cost. Those prompts are useful for a first deployment even when another provider hosts it. The exercise should teach what operates the application, not just where the Deploy button is located.
Describe the environment boundary
Write which resources belong to the preview environment. Include the service, storage and any identity it uses. A preview deployment should not silently point to production data because a copied variable retained an old destination.
| Input | What the notebook records |
|---|---|
| Application version | Source revision or immutable artifact identity |
| Configuration | Setting names, purpose and where values are supplied |
| Data | Fictional fixture and intended storage destination |
| Identity | Service identity and required actions |
| Public endpoint | Expected route and a harmless verification request |
The table deliberately excludes credentials. A reader needs to know how authorized configuration is supplied, not receive secret material in a procedure. The IAM security guidance recommends approaches such as temporary credentials and least privilege in AWS; use the equivalent identity model supported by your chosen platform.
The recovery branch belongs in the notebook before the first failed release. It is much easier to decide what a working version means while the current environment is still healthy.
Verify a behavior, not only a platform status
A platform may report that a deployment succeeded when the application still uses the wrong data source or serves an unexpected route. For the catalog example, request the page and inspect a known fictional item and its detail route. This checks that route and dataset; two builds can return the same response.
Verify the immutable artifact identity separately through trusted platform deployment metadata or a build/version marker tied to that artifact. Compare it with the intended build identity recorded in the notebook. A successful behavioral check and a matching artifact identity answer different questions, so record both results.
Also inspect the application’s own startup or request evidence. Confirm that required configuration is present without printing its values. If storage is involved, check that the application uses the preview destination and that the service identity can perform the intended operation.
Record what each check establishes. A successful page load demonstrates that route in that environment. It does not establish every database operation, access rule or failure path. A precise notebook preserves those limits so a later reader does not treat “deployment verified” as an unlimited claim.
Rehearse one failed release
Introduce a controlled failure in the isolated preview environment, such as an invalid non-secret configuration value that prevents startup. Predict how the platform and application will expose the failure. Then use the documented recovery mechanism to return to the known working artifact and configuration.
This is a proposed rehearsal until you actually run it. Once executed, record the observed signals and the recovery result. If rollback changes code but leaves configuration unchanged, that distinction belongs in the procedure. A previous artifact may still fail when paired with the wrong settings.
Data changes make recovery harder. The first exercise can avoid schema migration so you can understand application deployment separately. When a later release changes data, expand the procedure to cover compatibility and recovery rather than assuming the old artifact can read every new state.
Keep the notebook useful after the first success
Remove accidental details that only made sense during setup, such as a temporary terminal path, and preserve assumptions that affect the next deployment. Note which steps are automated and which still require a decision. If a manual step is easy to forget, describe its consequence and consider automating it when the workflow is stable.
The tradeoff is maintenance: a procedure that never follows the deployed system becomes misleading. Revisit it when the build, identity or resource layout changes. The best final check is another person following the notebook in the preview environment and identifying where they had to guess.
Record a release as a combination of inputs
Give the exercise’s first working release three labels: artifact A, runtime configuration C1 and fixture dataset D1. These are illustrative identities, not real artifact digests. The notebook should connect their real equivalents to the verification result when you perform the rehearsal. A branch name alone may move; an immutable build identity lets the next reader locate what was actually deployed.
Now propose release B with configuration C2. Suppose C2 names an invalid catalog backend, so the service cannot load its data. Returning to artifact A while retaining C2 may preserve the failure. The recovery action must say which inputs return to the known working combination, not merely name the previous source revision.
| Rehearsal combination | Expected interpretation |
|---|---|
| A + C1 + D1 | Known working baseline once verified |
| B + C2 + D1 | Deliberately invalid backend configuration |
| A + C2 + D1 | Code rollback alone leaves the bad input |
| A + C1 + D1 after recovery | Baseline must be checked again |
The final row is a new observation, not proof inherited from an earlier success. The data destination, route and running identity might have changed during recovery. Keep the same harmless verification cases so the before-and-after comparison means something.
Separate embedded configuration from runtime configuration
The Vite environment guide explains that exposed constants are replaced at build time and that VITE_-prefixed values can be included in client code. It also documents precedence between mode-specific files and environment values already present when Vite runs. Those details explain why editing a convenient .env file may leave the served frontend unchanged.
For the catalog exercise, suppose the API base URL is embedded in the browser bundle. Changing a runtime setting on the backend does not rewrite that bundle. The procedure needs a frontend rebuild with the intended public value, followed by deployment of the resulting artifact. If the application instead loads configuration through a runtime endpoint, document that different contract and verify what the browser receives.
Record configuration names, their phase and their authoritative source. Do not copy a full environment dump into the notebook. Public build constants and server credentials have different exposure rules, and a variable’s name does not establish that its value is safe to publish.
Define the point where a release may proceed
The Google SRE Workbook chapter Canarying Releases describes canarying as a partial, time-limited deployment that is evaluated before proceeding. It requires a way to select the changed population, an evaluation process and integration with the release process. A preview environment with no representative traffic does not automatically provide those guarantees.
For this first notebook, use the simpler lesson: state the evidence required before considering the preview release successful and the action to take when it is missing. A catalog page that returns 200 but shows the wrong fictional dataset fails the chosen check. An error in the platform’s rollout state needs investigation even if one cached page still opens.
When the application later needs gradual production releases, extend the procedure with a representative comparison, observation window and stop conditions. Do not rename a successful preview request as a canary evaluation. The useful learning artifact is a procedure whose claims fit the environment and whose recovery instructions can be exercised with the same inputs.