-
Notifications
You must be signed in to change notification settings - Fork 245
Draft initial documentation on resource hooks #15463
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
lunaris
wants to merge
1
commit into
master
Choose a base branch
from
wjones/hooks-docs
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| --- | ||
| title_tag: "hooks | Resource Options" | ||
| meta_desc: The hooks resource option provides a set of resource hooks linked to a resource. | ||
| title: "hooks" | ||
| h1: "Resource option: hooks" | ||
| meta_image: /images/docs/meta-images/docs-meta.png | ||
| menu: | ||
| iac: | ||
| identifier: hooks | ||
| parent: options-concepts | ||
| weight: 7 | ||
| aliases: | ||
| - /docs/intro/concepts/resources/options/hooks/ | ||
| - /docs/concepts/options/hooks/ | ||
| --- | ||
|
|
||
| The `hooks` resource option provides a set of resource hooks linked to a resource. Hooks are used to execute custom logic at specific points in the resource lifecycle, such as before or after creation, update, or deletion. | ||
|
|
||
| Each hook is a callback that gets invoked by the Pulumi engine. Hooks that execute before an action are called **before hooks** and have names beginning with `before` or `Before` depending on the language. Hooks that execute after an action are called **after hooks** and have names beginning with `after` or `After` depending on the language. Pulumi currently supports the following hook types: | ||
|
|
||
| * *Create hooks* are called before or after a resource is created. This may occur during the initial creation of a resource or when a resource requires replacement due to e.g. a change in an immutable property. | ||
|
|
||
| * *Update hooks* are called before or after a resource is updated in-place. | ||
|
|
||
| * *Delete hooks* are called before or after a resource is deleted. This may occur during the deletion of a resource due to a `destroy` or that resource's removal from the program, or as part of a resource replacement due to e.g. a change in an immutable property. | ||
|
|
||
| When a hook is executed as part of a resource operation, it receives the resource's [URN](/docs/iac/concepts/resources/names/#urns) and ID, as well as any relevant input and output properties. Hooks may return errors. If a before hook returns an error, the action it precedes will *not* be executed and the Pulumi operation will fail with that error. If an after hook returns an error, Pulumi will log a warning diagnostic and the Pulumi operation will continue. The table below illustrates the combinations of inputs, outputs, and error behaviors for each hook type: | ||
|
|
||
| | Hook type | Old inputs | New inputs | Old outputs | New outputs | Error behavior | | ||
| |---------------|------------|------------|-------------|-------------|-----------------------------------| | ||
| | Before create | | ✓ | | | Prevent creation, fail deployment | | ||
| | After create | | ✓ | | ✓ | Log warning, continue deployment | | ||
| | Before update | ✓ | ✓ | ✓ | | Prevent update, fail deployment | | ||
| | After update | ✓ | ✓ | ✓ | ✓ | Log warning, continue deployment | | ||
| | Before delete | ✓ | | ✓ | | Prevent deletion, fail deployment | | ||
| | After delete | ✓ | | ✓ | | Log warning, continue deployment | | ||
|
|
||
| ## Health checking example | ||
|
|
||
| {{< chooser language "javascript,typescript,python,go,csharp,java,yaml" >}} | ||
|
|
||
| {{% choosable language javascript %}} | ||
|
|
||
| ```javascript | ||
| ``` | ||
|
|
||
| {{% /choosable %}} | ||
| {{% choosable language typescript %}} | ||
|
|
||
| ```typescript | ||
| ``` | ||
|
|
||
| {{% /choosable %}} | ||
| {{% choosable language python %}} | ||
|
|
||
| ```python | ||
| ``` | ||
|
|
||
| {{% /choosable %}} | ||
| {{% choosable language go %}} | ||
|
|
||
| ```go | ||
| ``` | ||
|
|
||
| {{% /choosable %}} | ||
| {{% choosable language csharp %}} | ||
|
|
||
| ```csharp | ||
| ``` | ||
|
|
||
| {{% /choosable %}} | ||
| {{% choosable language java %}} | ||
|
|
||
| ```java | ||
| // Pulumi Java support for hooks is coming soon | ||
| ``` | ||
|
|
||
| {{% /choosable %}} | ||
| {{% choosable language yaml %}} | ||
|
|
||
| ```yaml | ||
| # Pulumi YAML does not support resource hooks | ||
| ``` | ||
|
|
||
| {{% /choosable %}} | ||
|
|
||
| {{< /chooser >}} | ||
|
|
||
| ## Deletions and delete hooks | ||
|
|
||
| In order for delete hooks to run successfully, Pulumi must have access to any necessary hooks at the time of the deletion. You should take the following actions to ensure that delete hooks run as expected: | ||
|
|
||
| * When removing resources from your program, first remove *only* the resources you wish to delete, *leaving any delete hooks in place*. Upon running e.g. `pulumi up`, Pulumi will delete the resources and run any relevant delete hooks. Once this operation is complete, you can then remove the delete hooks from your program. | ||
|
|
||
| * When running `pulumi destroy`, you must pass the `--run-program` flag to instruct Pulumi to run your program and register any hooks that are to be executed. If Pulumi detects that you are trying to `destroy` a stack that contains hooks _without_ the `--run-program` flag, it will fail with an error. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Quick note before I forget: we should mention that hooks can return an error. For before hooks this causes the action to fail. After hooks don't cause a failure (the action already ran!), but do log a warning.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good shout. I've taken a stab at it, though the table extension isn't the prettiest. Thoughts?
