Initial (#1)

Signed-off-by: Pavel Okhlopkov <[email protected]>
Co-authored-by: Pavel Okhlopkov <[email protected]>
Co-authored-by: Yuriy Losev <[email protected]>

.gitignore

@@ -0,0 +1,63 @@
+# Binaries for programs and plugins
+*.exe
+*.dll
+*.so
+*.dylib
+
+# Test binary, build with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Project-local glide cache, RE: https://github.com/Masterminds/glide/issues/736
+.glide/
+
+# vim
+*.swp
+
+# IDE
+.project
+.settings
+.idea/
+.vscode
+__debug_bin*
+venv/
+out/
+
+# local development deckhouse binary
+/deckhouse/deckhouse
+
+# terraform and dhctl artifacts
+*-tfstate/
+.terraform/
+
+# e2e tests
+testing/cloud_layouts/**/tmp
+testing/cloud_layouts/**/bootstrap.log
+testing/cloud_layouts/**/configuration.yaml
+testing/cloud_layouts/**/sshkey*
+layouts-tests-tmp/
+
+# ignore generated files
+/modules/040-node-manager/images/bashible-apiserver/pkg/template/test_data/**/generated/**
+
+# macOS Finder files
+*.DS_Store
+._*
+
+# Dev environment
+bin/
+include/
+
+# Python dev environment
+__pycache__/
+*.py[cod]
+.pytest_cache/
+
+/shell-operator
+
+# Helm lib
+deckhouse_lib_helm-*.tgz
+
+tmp/

.golangci.yaml

@@ -0,0 +1,80 @@
+run:
+  timeout: 10m
+
+issues:
+  exclude:
+    - ST1005.*
+    - "should not use dot imports"
+    - "don't use an underscore in package name"
+    - "exported: .*"
+  exclude-dirs:
+    # this code has been copied from kubectl cli. No need to lint external code.
+    - go_lib/dependency/k8s/drain
+    # this code has been copied from kubernetes vertical-pod-autoscaler. No need to lint external code.
+    - modules/302-vertical-pod-autoscaler/hooks/internal/vertical-pod-autoscaler/v1
+
+linters-settings:
+  gci:
+    sections:
+      - standard
+      - default
+      - prefix(github.com/deckhouse/)
+  goimports:
+    local-prefixes: github.com/deckhouse/
+  staticcheck:
+     checks: ["all"]
+  errcheck:
+    # Is Depricateed, use exclude-functions: https://github.com/kisielk/errcheck#excluding-functions
+    exclude-functions:
+      - fmt:.*[rR]ead|[wW]rite|[cC]lose
+      - io:Copy
+  sloglint:
+      # Enforce not mixing key-value pairs and attributes.
+      no-mixed-args: true
+      # Enforce using key-value pairs only (overrides no-mixed-args, incompatible with attr-only).
+      kv-only: false
+      # Enforce using attributes only (overrides no-mixed-args, incompatible with kv-only).
+      attr-only: false
+      # Enforce not using global loggers.
+      no-global: ""
+      # Enforce using methods that accept a context.
+      context: ""
+      # Enforce using static values for log messages.
+      static-msg: false
+      # Enforce using constants instead of raw keys.
+      no-raw-keys: false
+      # Enforce a single key naming convention.
+      key-naming-case: ""
+      # Enforce not using specific keys.
+      forbidden-keys:
+        - level
+        - msg
+        - logger
+        - source
+        - stacktrace
+        - time
+      # Enforce putting arguments on separate lines.
+      args-on-sep-lines: false
+
+linters:
+  disable-all: true
+  enable:
+  - dogsled
+  - errcheck
+  - gci
+  - gocritic
+  - gofmt
+  - goimports
+  - gosimple
+  - govet
+  - ineffassign
+  - misspell
+  - revive
+  - sloglint
+  - staticcheck
+#  - structcheck
+  - typecheck
+  - unconvert
+  - unparam
+  - whitespace
+  - copyloopvar

README.md

@@ -1 +1,99 @@
-# Module SDK
+# Module SDK
+SDK to easy compile your hooks as a binary and integrate with addon operator
+
+## Usage
+
+### One file example
+This file must be in 'hooks/' folder to build binary (see examples for correct layout)
+
+```go
+package main
+
+import (
+  "context"
+  "log/slog"
+
+  "github.com/deckhouse/module-sdk/pkg"
+  "github.com/deckhouse/module-sdk/pkg/app"
+  objectpatch "github.com/deckhouse/module-sdk/pkg/object-patch"
+  "github.com/deckhouse/module-sdk/pkg/registry"
+  v1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+var _ = registry.RegisterFunc(config, handlerHook)
+
+var config = &pkg.HookConfig{
+  Kubernetes: []pkg.KubernetesConfig{
+    {
+      Name:       "apiservers",
+      APIVersion: "v1",
+      Kind:       "Pod",
+      NamespaceSelector: &pkg.NamespaceSelector{
+        NameSelector: &pkg.NameSelector{
+          MatchNames: []string{"kube-system"},
+        },
+      },
+      LabelSelector: &v1.LabelSelector{
+        MatchLabels: map[string]string{"component": "kube-apiserver"},
+      },
+      JqFilter: ".metadata.name",
+    },
+  },
+}
+
+func handlerHook(_ context.Context, input *pkg.HookInput) error {
+  podNames, err := objectpatch.UnmarshalToStruct[string](input.Snapshots, "apiservers")
+  if err != nil {
+    return err
+  }
+
+  input.Logger.Info("found apiserver pods", slog.Any("podNames", podNames))
+
+  input.Values.Set("test.internal.apiServers", podNames)
+
+  return nil
+}
+
+func main() {
+  app.Run()
+}
+```
+
+More examples you can find [here](./examples)
+
+## Testing
+
+If you want to test your JQ filter, you can use JQ helper like in example [here](./pkg/jq/jq_test.go)
+
+## For deckhouse developers
+
+### Environment variables
+
+| Parameter | Required | Default value | Description |
+| --- | --- | --- | --- |
+| BINDING_CONTEXT_PATH |  | in/binding_context.json | Path to binding context file |
+| VALUES_PATH |  | in/values_path.json | Path to values file |
+| CONFIG_VALUES_PATH |  | in/config_values_path.json | Path to config values file |
+| METRICS_PATH |  | out/metrics.json | Path to metrics file |
+| KUBERNETES_PATCH_PATH |  | out/kubernetes.json | Path to kubernetes patch file |
+| VALUES_JSON_PATCH_PATH |  | out/values.json | Path to values patch file |
+| CONFIG_VALUES_JSON_PATCH_PATH |  | out/config_values.json | Path to config values patch file |
+| HOOK_CONFIG_PATH |  | out/hook_config.json | Path to dump hook configurations in file |
+| CREATE_FILES |  | false | Allow hook to create files by himself (by default, waiting for addon operator to create) |
+| LOG_LEVEL |  | FATAL | Log level (suppressed by default) |
+
+### Work sequence
+
+#### Deckhouse register process
+1) To register your hooks, add them to import section in main package like in [examples](./examples)
+2) Compile your binary and deliver to "hooks" folder in Deckhouse
+3) Addon operator finds it automatically and register all your hooks in binary, corresponding with your HookConfigs
+4) When addon operator has a reason, it calls hook in your binary 
+5) After executing hook, addon operator process hook output
+
+#### Calling hook
+1) Addon operator create temporary files for input and output data (see ENV for examples)
+2) Addon operator execute hook with corresponding ID and ENV variables pointed to files
+3) Hook reads all files and pass incoming data in HookInput
+4) Hook executes and write all resulting data from collectors contained in HookInput
+5) Addon operator reads info from temporary output files

examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+[Module hook basic example](https://github.com/deckhouse/module-sdk/tree/main/examples/basic-example-module)
+
+[Module hook single file example](https://github.com/deckhouse/module-sdk/tree/main/examples/single-file-example)
+
+[Module hook example](https://github.com/deckhouse/module-sdk/tree/main/examples/example-module)
+
+[Module hook example with dependency container](https://github.com/deckhouse/module-sdk/tree/main/examples/dependency-example-module)
+
+[Dockerfile and Makefile for building](https://github.com/deckhouse/module-sdk/tree/main/examples/scripts)

examples/basic-example-module/README.md

@@ -0,0 +1,37 @@
+# Module Hooks Basic Example
+In this example you can build your basic hook binary and check how it works.
+
+It can be usefull to understand how to register hooks in different layouts.
+
+### Run
+
+To get list of your registered hooks
+```bash
+go run . hook list
+```
+
+To get configs of your registered hooks
+```bash
+go run . hook config
+```
+
+To dump configs of your registered hooks in file
+```bash
+go run . hook dump
+```
+
+To run registered hook with index '0' (you can see index of your hook in output of "hook list" command)
+```bash
+go run . hook run 0
+```
+
+By default, all logs in hooks are suppressed and he waiting for files in default folders. 
+To make them available, you must add env variable LOG_LEVEL and CREATE_FILES.
+```bash
+CREATE_FILES=true LOG_LEVEL=INFO go run . hook run 0
+```
+
+### Build
+```bash
+go build -o basic-example-module-hooks .
+```

examples/basic-example-module/hooks/go.mod

@@ -0,0 +1,89 @@
+module basic-example-module
+
+go 1.22.8
+
+require github.com/deckhouse/module-sdk v0.0.0
+
+require (
+	github.com/DataDog/gostackparse v0.7.0 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/caarlos0/env/v11 v11.2.2 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/containerd/stargz-snapshotter/estargz v0.14.3 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/deckhouse/deckhouse/pkg/log v0.0.0-20241106140903-258b93b3334e // indirect
+	github.com/docker/cli v27.1.1+incompatible // indirect
+	github.com/docker/distribution v2.8.3+incompatible // indirect
+	github.com/docker/docker-credential-helpers v0.7.0 // indirect
+	github.com/emicklei/go-restful/v3 v3.11.0 // indirect
+	github.com/evanphx/json-patch/v5 v5.9.0 // indirect
+	github.com/fsnotify/fsnotify v1.7.0 // indirect
+	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-openapi/jsonpointer v0.19.6 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/swag v0.22.5 // indirect
+	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/gojuno/minimock/v3 v3.4.1 // indirect
+	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/google/gnostic-models v0.6.8 // indirect
+	github.com/google/go-cmp v0.6.0 // indirect
+	github.com/google/go-containerregistry v0.17.0 // indirect
+	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/imdario/mergo v0.3.15 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jonboulle/clockwork v0.2.2 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/compress v1.17.9 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.0 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/prometheus/client_golang v1.20.5 // indirect
+	github.com/prometheus/client_model v0.6.1 // indirect
+	github.com/prometheus/common v0.55.0 // indirect
+	github.com/prometheus/procfs v0.15.1 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/spf13/cobra v1.8.1 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+	github.com/sylabs/oci-tools v0.7.0 // indirect
+	github.com/tidwall/gjson v1.14.4 // indirect
+	github.com/tidwall/match v1.1.1 // indirect
+	github.com/tidwall/pretty v1.2.0 // indirect
+	github.com/vbatts/tar-split v0.11.3 // indirect
+	golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 // indirect
+	golang.org/x/net v0.30.0 // indirect
+	golang.org/x/oauth2 v0.21.0 // indirect
+	golang.org/x/sync v0.8.0 // indirect
+	golang.org/x/sys v0.26.0 // indirect
+	golang.org/x/term v0.25.0 // indirect
+	golang.org/x/text v0.19.0 // indirect
+	golang.org/x/time v0.7.0 // indirect
+	gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect
+	google.golang.org/protobuf v1.35.1 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	k8s.io/api v0.29.8 // indirect
+	k8s.io/apiextensions-apiserver v0.29.0 // indirect
+	k8s.io/apimachinery v0.29.8 // indirect
+	k8s.io/client-go v0.29.8 // indirect
+	k8s.io/component-base v0.29.0 // indirect
+	k8s.io/klog/v2 v2.130.1 // indirect
+	k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 // indirect
+	k8s.io/utils v0.0.0-20240711033017-18e509b52bc8 // indirect
+	sigs.k8s.io/controller-runtime v0.17.0 // indirect
+	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
+	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
+	sigs.k8s.io/yaml v1.4.0 // indirect
+)
+
+replace github.com/deckhouse/module-sdk => ./../../../