cdktf watch command

[ansgarm]

The watch command is supposed to watch source files and to automatically do a cdktf deploy (--auto-approve) when they change to support quickly iterating on infrastructure (especially useful for serverless use-cases).

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Description

Add a watch command to the cdktf-cli package. When executed, this command is
long-running and keeps watching the source directory for changes to files. When
a change is detected, it will run the app script of the cdktf.json and to
build and synthesize the application.
After running the synth it will compare the cdk.tf.json output with a
previous version (probably using hashes kept
in-memory)
and determine whether changes need to be deployed. If there are any, it will
automatically deploy them (auto-approving), ideally also skipping the
diff/plan phase to save time.
To make sure the user knows that the initial iteration of the watch command
deploys automatically, the --auto-approve flag is required on the watch
command until it supports a manual approval step before deploying. So, in the
first iteration only cdktf watch --auto-approve will work but cdktf watch
will fail with a short note about this behaviour.
By using supplying -refresh=false to Terraform on subsequent deploys, we can
possibly further speed up things.

Determining the source directory

For a first iteration the command could watch any file in the same directory as
the cdktf.json file, except for the build / synth output of the CDKTF and
except for files specified in the .gitignore file.

If this might impose problems, the source directory could also be inferred for
the target language, however it might be useful to expose an option (on the CLI
command and/or in the cdktf.json config) as the code structure used by users
could differ quite substantially.

Handling subsequent changes

If new file updates are detected while a deploy is currently running a second
deploy should be queued so that changes can always be expected to get applied
(even if they take longer this way). In future iterations this could be made
smarter (e.g. just redoing the synth step if the deploy itself wasn't running
yet).

Handling errors

If an error happens, the watch should continue running but display a message
to the user that informs him that something failed. Possible errors include:

• resources can't be applied properly for some reason
• state is locked and stuck
• cloud credentials are expired

Todos for the first iteration

• Add new CLI command that achieves cdktf watch --auto-approve
• watch command takes a stack as argument or uses the only one available if there's just one
• Watches files not in .gitignore for synth
• Compiles application and runs synth when source files changed
• (if appropriate) Decouple synth and deploy part in a way that allows to later switch the synth watching part to be supported by language native build watchers (e.g. gomon). A possible way could be to have the "deploy watcher" listen on the specific cdk.tf.json output file from the prior synth step.
• Hashes the cdk.tf.json for a stack and keeps the hash in memory
• Deploys using a locally running Terraform CLI
• Supports deploying via Terraform Cloud Remote execution (ignored for now)
• Skips the plan phase when deploying with --auto-approve to speed up things
• Supports subsequent code changes while a deploy is running
• Handle error case: apply failed (e.g. HTTP 400 / invalid resource configuration)
• Handle error case: Terraform state is locked and stuck
• Handle error case: Cloud credentials are expired (of a Terraform provider)
• Exits gracefully if e.g. passed --stack was not found (currently the server just exits and we get an connection error - that should be changed)
• Add telemetry for usage of watch command
• Add tests for watch command
• Add e2e test for watch command happy path
• Add docs for using the watch command (including importance of .gitignore file for synth, include that it does not support nested .gitignore files yet)
• … probably more …
• Add follow-up issue for supporting nested .gitignore files for synth
• Add follow-up issues for improvements listed below
• Does not hash the stacktrace part of the cdk.tf.json which does not affect the deploy or follow-up issue created for this improvement -> No issue created as the stacktrace does not change when a resource is moved around in the codebase.
• Follow-up issue created for supporting remote execution in Terraform Cloud?
• Follow-up issue created for adding support for printing outputs
• Follow-up issue created for refactoring GraphQL subscription handling
• Issue for: Watches cdk.tf.json and asset files (for that stack) in outDir (e.g. cdktf.out) for deploy (not just all, as a local file resource could write a new file there)

Improvements for future iterations

The following sections contain improvements for the aforementioned first minimal
viable implementation. They will probably be converted into follow-up issues after the first iteration of this feature is finished (depending on whether they are still relevant then).

Manual Approval

When invoking cdktf watch without the --auto-approve flag the user has to
confirm applying the changes by pressing the enter key.

Detecting which resources changed

When checking the new cdk.tf.json against the previous version, we could check
which resources were changed and supply them as a
-target
to the Terraform CLI. As we don't expect outside changes to our resources while
using watch we could save the time Terraform would take to refresh all the
other resources. This would further speed up the deployment of the actual
changes and improve the user experience.
This might possibly not be worth the effort if supplying -refresh=false to
subsequent runs already speeds up things enough. However we might still want to
test this.

Make use of target language tooling for recompiling

Most of the target languages of the CDKTF have tooling for watching the source
files and incrementally compiling the resulting binary (e.g. tsc --watch,
gradle --watch-fs [Maven does not seem to support watching], gomon). We
could make use of this to speed up the build and synth part of the cdktf watch
command. We could e.g. add a watch option to the cdktf.json config which
contains a command that is spawned by the cdktf watch command.
How exactly the watch command would then do the synth has still to be
explored.

References

[github-actions]

I'm going to lock this issue because it has been closed for 30 days. This helps our maintainers find and focus on the active issues. If you've found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.