Application hooks are written in Go using module-sdk. Deckhouse Platform (DP) runs them at certain stages of the application lifecycle, on changes of Kubernetes objects, and on schedule. Hooks prepare values for templates, create and change objects in the application namespace, and validate settings.
Hooks binary
All hooks of a package are compiled into a single Go binary. In the package skeleton, the sources are located in hooks/batch/, and d8 package build builds the binary according to hooks/hooks.yaml and puts it into the package bundle.
Each hook is registered with registry.RegisterFunc, and the main function calls app.Run:
// hooks/batch/main.go
package main
import (
"github.com/deckhouse/module-sdk/pkg/app"
"hooks/settings"
_ "hooks/triggers"
)
func main() {
app.Run(app.WithSettingsCheck(settings.Check))
}
Requirements for the binary:
- The hook source files must be located under a directory named
hooks: module-sdk builds the hook name from the file path. - The binary must register at least one hook. DP ignores a binary without hooks, even if it contains a settings validation hook.
- Build a static binary for Linux (
CGO_ENABLED=0), as the skeleton does.
DP finds hooks by running each executable file without an extension from the hooks/ directory of the bundle with the hook list argument. A binary that fails at this stage, for example, because of an invalid hook configuration, is skipped without an error in the Application status. To make sure that the hooks are registered, check the output of the following commands in CI:
cd hooks/batch
CGO_ENABLED=0 go build -o /tmp/hooks .
/tmp/hooks hook list
/tmp/hooks hook config
Hook example
package state
import (
"context"
corev1 "k8s.io/api/core/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"github.com/deckhouse/module-sdk/pkg"
objectpatch "github.com/deckhouse/module-sdk/pkg/object-patch"
"github.com/deckhouse/module-sdk/pkg/registry"
)
var _ = registry.RegisterFunc(&pkg.ApplicationHookConfig{
OnBeforeHelm: &pkg.OrderedConfig{Order: 10},
Kubernetes: []pkg.ApplicationKubernetesConfig{
{
Name: "credentials",
APIVersion: "v1",
Kind: "Secret",
LabelSelector: &metav1.LabelSelector{
MatchLabels: map[string]string{"example.com/credentials": "true"},
},
JqFilter: `{"name": .metadata.name}`,
},
},
}, handle)
type secret struct {
Name string `json:"name"`
}
func handle(_ context.Context, input *pkg.ApplicationHookInput) error {
secrets, err := objectpatch.UnmarshalToStruct[secret](input.Snapshots, "credentials")
if err != nil {
return err
}
// The path must be declared in openapi/values.yaml.
input.Values.Set("internal.credentialsCount", len(secrets))
// The ConfigMap is created as d8a-<INSTANCE_NAME>-state in the application namespace.
input.PatchCollector.CreateOrUpdate(&corev1.ConfigMap{
TypeMeta: metav1.TypeMeta{APIVersion: "v1", Kind: "ConfigMap"},
ObjectMeta: metav1.ObjectMeta{Name: "state"},
Data: map[string]string{"instance": input.Instance.Name()},
})
return nil
}
Bindings and execution order
The pkg.ApplicationHookConfig structure defines when the hook runs:
| Field | When the hook runs |
|---|---|
OnStartup |
Once after the package is loaded: on installation, after the package version changes, and after DP restarts. The hook doesn’t get snapshots |
OnBeforeHelm |
In every reconciliation run, before the templates are applied |
OnAfterHelm |
In every reconciliation run, after the templates are applied. If the hook changes values, DP applies the templates again |
OnBeforeDeleteHelm |
Before the Helm release is uninstalled: when the Application is deleted or when the package requirements stop being met. The hook doesn’t run when the package version changes |
OnAfterDeleteHelm |
After the Helm release is uninstalled, in the same cases as OnBeforeDeleteHelm |
Schedule |
On schedule in the crontab format |
Kubernetes |
When the watched objects in the application namespace change, and during the synchronization of the binding (see Kubernetes bindings) |
Other fields:
Queue— name of the queue for theScheduleandKubernetesbindings of the hook (default:main). These bindings run in a queue separate from the lifecycle stages, so they can run at the same time asOnBeforeHelmorOnAfterHelmhooks.AllowFailureandSettingsare not supported for applications.
Hooks with the same binding run in the ascending order of Order (the pkg.OrderedConfig field). The sequence of lifecycle stages is described in Lifecycle and debugging.
A hook can’t combine OnStartup with Kubernetes bindings: module-sdk panics when such a hook is registered, and DP skips the whole binary.
Error handling
- If a hook fails, the stage that ran it fails and is retried with an increasing delay, from 15 seconds up to 2 hours. The next tasks of the application wait. The error is reported in the Application conditions and summary.
- If an
OnBeforeDeleteHelmhook fails, DP doesn’t uninstall the Helm release and retries the hook. The Application is not deleted until the hook succeeds. - If an object operation of the hook fails, the hook run fails, and the values changes made by the run are discarded. The operations that have already been executed are not rolled back.
module-sdk recovers panics in hook handlers, and the run is considered successful but has no effect: neither values changes nor object operations are applied. Return errors instead of panicking.
ApplicationHookInput
The hook handler has the func(ctx context.Context, input *pkg.ApplicationHookInput) error signature. pkg.ApplicationHookInput contains the following fields:
| Field | Description |
|---|---|
Instance |
Instance parameters: Name() and Namespace() |
Snapshots |
Snapshots of the Kubernetes bindings of the hook |
Values |
Application values: reading (Get, GetOk, Exists, ArrayCount) and changing (Set, Remove) |
Settings |
Effective settings of the application, read-only |
PatchCollector |
Operations with objects in the application namespace (see Object operations) |
DC |
Dependencies: an HTTP client (GetHTTPClient), a container registry client (GetRegistryClient), and a clock (GetClock) |
Logger |
Logger. The output is written to the DP log |
MetricsCollector |
Not supported for applications: DP ignores the metrics |
Application hooks don’t get a Kubernetes client. To read objects, use Kubernetes bindings, and to change them, use PatchCollector.
The instance name and namespace are the only parameters of the instance available to hooks. The package name, version, and images are available only to templates.
Kubernetes bindings
The pkg.ApplicationKubernetesConfig structure describes the objects the hook watches:
| Field | Description |
|---|---|
Name |
Binding name, the key in Snapshots |
APIVersion, Kind |
API version and kind of the objects. Only namespaced kinds are supported |
NameSelector, LabelSelector, FieldSelector |
Selection of objects |
JqFilter |
jq expression applied to each object. The snapshot contains the results of the expression. Without the expression, the snapshot contains full objects |
ExecuteHookOnEvents |
false — update the snapshot without running the hook when the objects change. Default: true |
ExecuteHookOnSynchronization |
false — don’t run the hook during the synchronization. Default: true |
WaitForSynchronization |
false — don’t wait for the synchronization of the binding before the next stages. It takes effect only if the Queue field of the hook is set. Default: true |
AllowFailure |
Ignore errors of the hook during the synchronization |
Behavior:
- DP always restricts the bindings to the application namespace, so the structure has no namespace selector.
- On every run, the hook gets the snapshots of all its bindings: the current state of the objects, not the event that triggered the run.
OnBeforeHelm,OnAfterHelm,OnBeforeDeleteHelm, andOnAfterDeleteHelmhooks get the snapshots too.- DP synchronizes the bindings at the beginning of every reconciliation run: hooks with
ExecuteHookOnSynchronizationenabled run with the full list of objects. NameSelectormatches the actual object names, including thed8a-<INSTANCE_NAME>-prefix.
The hook configuration is the same for all instances of the package, so selectors can’t refer to the instance name. If several instances of the package can be installed into the same namespace, add the instance label to the snapshot and compare it with input.Instance.Name(). Objects rendered from the templates carry the packages.deckhouse.io/instance label:
JqFilter: `{"name": .metadata.name, "instance": .metadata.labels["packages.deckhouse.io/instance"]}`,
Object operations
input.PatchCollector collects the operations with objects. DP executes them after the hook completes:
| Method | Description |
|---|---|
Create |
Create an object. The operation fails if the object exists |
CreateIfNotExists |
Create an object if it doesn’t exist |
CreateOrUpdate |
Create an object or replace the existing one. The fields that the hook doesn’t set are removed from the object |
Delete, DeleteInBackground, DeleteNonCascading |
Delete an object with foreground, background, or orphan propagation of the deletion. A missing object is ignored |
PatchWithJSON, PatchWithMerge, PatchWithJQ |
Patch an object with a JSON Patch (RFC 6902), a JSON Merge Patch (RFC 7396), or a jq expression. To patch a subresource, pass the objectpatch.WithSubresource("status") option |
Behavior:
- module-sdk sets the application namespace in every operation, regardless of the namespace specified in the object.
- Typed objects must have
TypeMetawithapiVersionandkindset. Otherwise, the operation is not executed. - Patching a missing object fails the hook. Check that the object exists, for example, in a snapshot, before patching it.
- Objects created by hooks are not part of the Helm release, and DP doesn’t add platform labels to them, so uninstalling the release doesn’t delete them. To delete such objects together with the application, set the
packages.deckhouse.io/instancelabel to the instance name and list their kind inorphanResources. You can also set an owner reference to an object of the release, or delete the objects inOnBeforeDeleteHelmorOnAfterDeleteHelmhooks.
Object names
DP adds the d8a-<INSTANCE_NAME>- prefix to the object name in every operation, unless the name already starts with it. For example, for the myapp instance:
Createof thestateConfigMap createsd8a-myapp-state;PatchWithMergeof theserverDeployment changesd8a-myapp-server, that is, the Deployment namedd8a-<INSTANCE_NAME>-serverin the templates.
As a result, a hook can change only the objects of its own instance. Objects with the d8a- prefix are protected from changes by users (see Templates).
Values
input.Values contains the application values: the same document the templates get as .Values. The settings are located at the root of the document, without the package name key.
Set(path, value)andRemove(path)accept a path with dot-separated keys, for example,internal.credentialsCount. The parent object of the path must exist, so declare intermediate objects inopenapi/values.yamlwithdefault: {}.- After the hook completes, DP validates the values against
openapi/values.yaml. The schema must include the settings schema withx-extend(see Application settings): the settings are located at the root of the values, and undeclared fields fail the validation. - The values changes are kept in memory. After DP restarts or the package version changes, they are lost until the hooks run again.
What happens after the values change depends on the binding:
| Binding | Result |
|---|---|
Kubernetes, Schedule |
DP starts a new reconciliation run |
OnAfterHelm |
DP applies the templates again |
OnStartup, OnBeforeHelm, synchronization |
The values are used when the templates are applied in the same run |
input.Settings is read-only: hooks can’t change the application settings.
Settings validation hook
Applications can include a settings validation hook for checks that the OpenAPI schema can’t express, for example, business logic constraints across multiple settings fields.
The hook implements a Check function with the signature:
func Check(_ context.Context, input settingscheck.Input) settingscheck.Result
settingscheck.Input provides access to the settings (input.Settings) with the default values from openapi/settings.yaml applied, as well as to a logger (input.Logger).
settingscheck.Result is one of:
settingscheck.Allow(warnings...)— settings are valid; optionally attach warning messages.settingscheck.Reject(reason)— settings are invalid.
Example:
func Check(_ context.Context, input settingscheck.Input) settingscheck.Result {
replicas := input.Settings.Get("replicas").Int()
if replicas == 0 {
return settingscheck.Reject("replicas cannot be 0")
}
var warnings []string
if replicas == 2 {
warnings = append(warnings, "an even number of replicas may cause split-brain in some configurations")
}
if replicas > 3 {
return settingscheck.Reject("replicas cannot be greater than 3")
}
return settingscheck.Allow(warnings...)
}
To register the check, pass it to app.Run in the hooks binary: app.Run(app.WithSettingsCheck(Check)). A package can contain only one settings validation hook.
DP calls the check in the following cases:
- When the Application of an installed application is changed, the validating webhook runs the check of the installed version. A rejection denies the request with the specified reason. Warnings are returned to the client, for example,
d8 kprints them. - When DP applies changed settings. A rejection leaves the new settings unapplied, and the error is reported in the Application conditions. Warnings are ignored.
The check doesn’t run in the validating webhook when an Application is created: in this case, the request is checked against the settings schema only. When spec.packageVersion changes, the webhook runs the check of the installed version, not of the new one. Describe critical constraints in the schema, for example, with CEL rules, to reject invalid settings before installation.
Restrictions
- Kubernetes bindings and object operations are limited to the application namespace, and object operations are also limited to the objects with the
d8a-<INSTANCE_NAME>-name prefix. - Hooks can’t create or change cluster-wide objects.
- Readiness probes (
app.WithReadiness) are intended for modules. Don’t use them in applications: DP determines the application health from its workloads. - Metrics of hooks are not collected.