What belongs in an environment definition
A repository can describe an application environment while the deployed system has moved away from it. Separate the parts that should match from the differences the environment actually needs.
Keep the parts identifiable
An application artifact is the built object the runtime executes. Configuration supplies settings such as endpoint names and worker limits. A secret reference locates a protected value without putting that value in the application source. A managed resource is a dependency such as a database, queue or object store.
Those parts can change on different schedules. Deploying an unchanged application image against a different configuration or database can still change its behavior. A useful environment definition identifies the relevant versions and references as well as the image.
Identify the built object
Promoting the identified artifact preserves the built object that was tested. The target environment still needs its own checks.
Test environment
Example build AProduction environment
The same example build AImmutable artifact identity
| Part | Test environment | Production environment | What to compare |
|---|---|---|---|
| Application artifact | Example build A | The same example build A | Immutable artifact identity |
| Configuration | Smaller worker pool | Larger worker pool | Intentional values; consistent setting names |
| Secret reference | Test-only reference | Production-only reference | Correct reference and runtime access, never the secret value |
| Managed resource | Separate test database | Production database | Required features, schema and network destination |
Promote the same artifact when the pipeline permits it
Use an immutable artifact identifier to connect the build under test to the build deployed. A mutable label can later point to another object. Recording only that label makes it harder to determine what was running when a problem occurred.
Rebuilding from the same source revision can produce a different artifact if dependencies, base images or build inputs have changed. Record the build inputs needed to identify that release. The target environment still needs its own checks.
Treat a deliberate difference as part of the definition
Test and production may legitimately use different capacity, hostnames and secret references. Keep the setting names and the reason for each difference explicit. A smaller test resource should still support the application features and schema needed for the test.
A setting that exists only in a production console is harder to reproduce than one represented in the maintained definition. Decide whether a change belongs in the shared definition, an environment-specific value or a protected secret system. Copying the entire production configuration into test can expose credentials and connect tests to real services.
Compare intended and observed state before applying changes
Read the deployed resources and compare them with the maintained definition. A manually increased limit may have kept a service running during an incident. Reapplying an older definition without understanding that change can restore the original problem.
Investigate the difference with the application team. The outcome may be to update the definition, revert an unintended change or preserve an exception while a separate fix is prepared. Inspect the proposed changes for resource replacement, deletion and service interruption before applying them.
Reproduction includes the connections
Creating a new runtime is not enough if it cannot resolve a dependency, obtain an approved secret or reach the required network destination. Validate those connections with the access intended for the environment. A test performed using an administrator’s credentials may conceal a missing runtime permission.
Keep secret values out of repository files and routine diagnostic output. Record the reference and the access arrangement needed by the service. Recovery instructions should explain how an authorized operator restores that arrangement without publishing a credential in the instructions.
Keep stateful recovery separate
A definition can recreate a database service without recreating its contents. Data restoration needs its own backups, retention choices and tested recovery procedure. The acceptable recovery point and service interruption depend on the application and belong in the actual assignment.
When a change involves application and database versions, check their compatibility through the transition. An infrastructure definition does not by itself establish that an older application can use the resulting data.
Database compatibility through a release