Repository navigation
feat(defkit): experimental addon to install DefKit definition modules #799
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
Merged
anoop2811
merged 13 commits into
kubevela:master
from
briankane:feat/experimental-defkit
Oct 15, 2026
Merged
Changes from 1 commit
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
91cd7d8
feat(defkit): experimental addon to install DefKit definition modules
briankane c006120
fix(defkit): write empty definitions and errors as lists
briankane f625ab3
fix(defkit): keep git credentials out of a render's output
briankane f67c1c4
fix(defkit): leave the git URL out of the render step's message
briankane 818371e
fix(defkit): fail apply when the render cannot be read
briankane 18adac5
fix(defkit): fail apply on a render with errors
briankane 4809522
fix(defkit): prune only ConfigMaps labelled as renders
briankane 29779d5
fix(defkit): scope a module's renders to its namespace
briankane d2266c9
fix(defkit): keep the account's token away from module code
briankane 6112f6d
fix(defkit): require git or ref on a repository
briankane fca7831
docs(defkit): push the multi-platform render image
briankane 55022db
docs(defkit): say when dropped definitions are kept
briankane e244fa9
chore(defkit): ignore the locally built render binary
briankane 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| import ( | ||
| "encoding/json" | ||
| "list" | ||
| "strings" | ||
| "vela/builtin" | ||
| "vela/kube" | ||
| ) | ||
|
|
||
| "defkit-apply": { | ||
| type: "workflow-step" | ||
| annotations: category: "DefKit" | ||
| labels: "defkit.oam.dev/step": "apply" | ||
| description: "Apply the definitions a defkit-render step produced, as this Application's resources (experimental)" | ||
| } | ||
| template: { | ||
| rendered: kube.#Read & { | ||
| $params: value: { | ||
| apiVersion: "v1" | ||
| kind: "ConfigMap" | ||
| metadata: {name: parameter.configMap, namespace: "vela-defkit"} | ||
| } | ||
| } | ||
| _data: *{} | {...} | ||
| if rendered.$returns.value.data != _|_ { | ||
| _data: rendered.$returns.value.data | ||
| } | ||
| _defs: *[] | [...{...}] | ||
| if _data["definitions.json"] != _|_ { | ||
| _defs: json.Unmarshal(_data["definitions.json"]) | ||
|
briankane marked this conversation as resolved.
Resolved
|
||
| } | ||
|
|
||
| // Each rendered definition as the cluster has it, if it does. | ||
| existing: { | ||
| for d in _defs { | ||
| "\(d.kind)-\(d.metadata.name)": kube.#Read & { | ||
| $params: value: { | ||
| apiVersion: d.apiVersion | ||
| kind: d.kind | ||
| metadata: {name: d.metadata.name, namespace: context.namespace} | ||
| } | ||
| } | ||
| } | ||
| } | ||
| _me: "\(context.namespace)/\(context.name)" | ||
|
|
||
| // writable are the definitions this module may write: those not there yet | ||
| // and those it already owns. Anything else, owned by another or by nobody, | ||
| // is never applied. Membership is tested positively, and the clauses are | ||
| // chained so each is read only where the one before holds: a read that | ||
| // does not evaluate fails the step rather than reading as writable. | ||
| _new: [ | ||
| for d in _defs | ||
| let r = existing["\(d.kind)-\(d.metadata.name)"].$returns | ||
| if r.err != _|_ | ||
| if strings.Contains(r.err, "not found") {"\(d.kind)/\(d.metadata.name)"}, | ||
| ] | ||
| _owned: [ | ||
| for d in _defs | ||
| let r = existing["\(d.kind)-\(d.metadata.name)"].$returns | ||
| if r.err == _|_ | ||
| let labels = *r.value.metadata.labels | {} | ||
| if (*labels["app.oam.dev/namespace"] | "") + "/" + (*labels["app.oam.dev/name"] | "") == _me {"\(d.kind)/\(d.metadata.name)"}, | ||
| ] | ||
| _writable: list.Concat([_new, _owned]) | ||
| readFailed: { | ||
| for d in _defs | ||
| let r = existing["\(d.kind)-\(d.metadata.name)"].$returns | ||
| if r.err != _|_ | ||
| if !strings.Contains(r.err, "not found") { | ||
| "\(d.kind)-\(d.metadata.name)": builtin.#Fail & { | ||
| $params: message: "read \(d.kind) \(d.metadata.name): \(r.err)" | ||
| } | ||
| } | ||
| } | ||
|
|
||
| apply: { | ||
| for d in _defs | ||
| let id = "\(d.kind)/\(d.metadata.name)" | ||
| if list.Contains(_writable, id) | ||
| if !list.Contains(parameter.skip, id) { | ||
| "\(strings.Replace(id, "/", "-", -1))": kube.#Apply & { | ||
| $params: value: d & {metadata: namespace: context.namespace} | ||
| } | ||
| } | ||
| } | ||
|
|
||
| parameter: { | ||
| // +usage=The ConfigMap in vela-defkit the render step wrote | ||
| configMap: string | ||
| // +usage=Definitions to leave alone, as Kind/name | ||
| skip: *[] | [...string] | ||
| } | ||
| } | ||
105 changes: 105 additions & 0 deletions
105
experimental/addons/defkit/definitions/defkit-render.cue
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,105 @@ | ||
| import ( | ||
| "strings" | ||
| "vela/builtin" | ||
| "vela/kube" | ||
| ) | ||
|
|
||
| "defkit-render": { | ||
| type: "workflow-step" | ||
| annotations: category: "DefKit" | ||
| labels: "defkit.oam.dev/step": "render" | ||
| description: "Render a DefKit module in a Job into a ConfigMap of definitions (experimental)" | ||
| } | ||
| template: { | ||
| // One render per run: the step's session is new each time the workflow | ||
| // runs, so a moving branch is fetched again, and steady within a run. | ||
| _name: "\(context.name)-\(strings.ToLower(context.stepSessionID))" | ||
|
|
||
| settings: kube.#Read & { | ||
| $params: value: { | ||
| apiVersion: "v1" | ||
| kind: "ConfigMap" | ||
| metadata: {name: "defkit-settings", namespace: "vela-defkit"} | ||
| } | ||
| } | ||
|
|
||
| job: kube.#Apply & { | ||
| $params: value: { | ||
| apiVersion: "batch/v1" | ||
| kind: "Job" | ||
| metadata: { | ||
| name: _name | ||
| namespace: "vela-defkit" | ||
| labels: "defkit.oam.dev/module": context.name | ||
| } | ||
| spec: { | ||
| backoffLimit: 1 | ||
| // The module re-renders on its interval, so a Job outlasting one | ||
| // is stale: it is stopped, then deleted shortly after it ends. | ||
| activeDeadlineSeconds: 600 | ||
| ttlSecondsAfterFinished: 300 | ||
| template: spec: { | ||
| serviceAccountName: "defkit-render" | ||
| restartPolicy: "Never" | ||
| securityContext: {runAsNonRoot: true, runAsUser: 65532} | ||
| containers: [{ | ||
| name: "render" | ||
| image: settings.$returns.value.data.image | ||
| imagePullPolicy: "IfNotPresent" | ||
| args: [ | ||
| if parameter.git != "" {"--git=\(parameter.git)"}, | ||
| if parameter.git == "" {"--ref=\(parameter.ref)"}, | ||
| "--version=\(parameter.version)", | ||
| "--prefix=\(parameter.prefix)", | ||
| "--types=\(strings.Join(parameter.types, ","))", | ||
| "--configmap=vela-defkit/\(_name)", | ||
| "--module=\(context.name)", | ||
|
briankane marked this conversation as resolved.
Resolved
|
||
| ] | ||
| // Without requests the limits are requested too, and a render | ||
| // waits for two free CPUs. | ||
| resources: { | ||
| requests: {cpu: "100m", memory: "256Mi"} | ||
| limits: {cpu: "2", memory: "2Gi"} | ||
| } | ||
| }] | ||
| } | ||
| } | ||
| } | ||
| } | ||
|
|
||
| _status: *{} | {...} | ||
| if job.$returns.value.status != _|_ { | ||
| _status: job.$returns.value.status | ||
| } | ||
| _succeeded: (_status.succeeded & >0) != _|_ | ||
| // Failed covers retries exhausted and the deadline passed alike. | ||
| _failed: len([for c in *_status.conditions | [] if c.type == "Failed" && c.status == "True" {c}]) > 0 | ||
|
|
||
| wait: builtin.#ConditionalWait & { | ||
| $params: { | ||
| continue: _succeeded || _failed | ||
| message: "rendering \(parameter.ref)\(parameter.git) \(parameter.version)" | ||
|
briankane marked this conversation as resolved.
Resolved
|
||
| } | ||
| } | ||
| if _failed { | ||
| fail: builtin.#Fail & { | ||
| $params: message: "render Job vela-defkit/\(_name) failed; see its logs" | ||
| } | ||
| } | ||
|
|
||
| // The ConfigMap the apply step and VelaUX's preview read. | ||
| configMap: _name | ||
|
|
||
| parameter: { | ||
| // +usage=Go module path of the module; or set git | ||
| ref: *"" | string | ||
| // +usage=Git repository of the module, in place of ref | ||
| git: *"" | string | ||
| // +usage=Module version; with git, a branch, tag or commit | ||
| version: *"" | string | ||
| // +usage=Prefix for every definition name | ||
| prefix: *"" | string | ||
| // +usage=Definition types to render; all when empty | ||
| types: *[] | [...("component" | "trait" | "policy" | "workflow-step")] | ||
| } | ||
| } | ||
34 changes: 34 additions & 0 deletions
34
experimental/addons/defkit/examples/vela-definitions-traits.yaml
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,34 @@ | ||
| # A DefKit module installed as an Application: render, wait for review, apply. | ||
| apiVersion: core.oam.dev/v1beta1 | ||
| kind: Application | ||
| metadata: | ||
| name: defkit-vela-definitions | ||
| namespace: vela-system | ||
| labels: | ||
| defkit.oam.dev/module: vela-definitions | ||
| spec: | ||
| components: [] | ||
| policies: | ||
| - name: keep-removed-definitions | ||
| type: garbage-collect | ||
| properties: | ||
| keepLegacyResource: true | ||
|
briankane marked this conversation as resolved.
Resolved
|
||
| workflow: | ||
| steps: | ||
| - name: render | ||
| type: defkit-render | ||
| properties: | ||
| git: https://github.com/kubevela/vela-go-definitions | ||
| version: main | ||
| prefix: dk- | ||
| types: [trait] | ||
| outputs: | ||
| - name: rendered | ||
| valueFrom: configMap | ||
| - name: review | ||
| type: suspend | ||
| - name: apply | ||
| type: defkit-apply | ||
| inputs: | ||
| - from: rendered | ||
| parameterKey: configMap | ||
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,11 @@ | ||
| name: defkit | ||
| version: 0.1.0 | ||
| description: "Experimental: install DefKit definition modules as Applications. Each module renders in a Job and its definitions are applied, tracked and garbage collected by its Application." | ||
| url: https://github.com/kubevela/kubevela/tree/master/pkg/definition/defkit | ||
| tags: | ||
| - experimental | ||
| - definitions | ||
| deployTo: | ||
| runtimeCluster: false | ||
| dependencies: [] | ||
| invisible: false |
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,17 @@ | ||
| parameter: { | ||
| // +usage=Image of the render Job: Go plus defkit-render | ||
| image: *"oamdev/defkit-render:v0.1.0" | string | ||
| // +usage=Repositories VelaUX offers when adding a module; a module can still come from anywhere | ||
| repositories: *[{ | ||
| name: "KubeVela definitions" | ||
| git: "https://github.com/kubevela/vela-go-definitions" | ||
| version: "main" | ||
| description: "KubeVela's built-in definitions, written with DefKit" | ||
| }] | [...{ | ||
| name: string | ||
| git?: string | ||
|
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
|
||
| ref?: string | ||
| version?: string | ||
| description?: string | ||
| }] | ||
| } | ||
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,61 @@ | ||
| # DefKit | ||
|
|
||
| Installs [DefKit](https://github.com/kubevela/kubevela/tree/master/pkg/definition/defkit) definition modules as Applications. A module is a Go module of X-Definitions written with DefKit, such as [vela-go-definitions](https://github.com/kubevela/vela-go-definitions). | ||
|
|
||
| Each module is an Application whose workflow: | ||
|
|
||
| 1. **renders** the module in a Job (`defkit-render`), the way `vela def apply-module` loads it, into a ConfigMap; | ||
| 2. waits for **review** (optional, a `suspend` step); | ||
| 3. **applies** the rendered definitions (`defkit-apply`), so the Application tracks them and garbage collects the ones a new version drops. | ||
|
|
||
| The render Job runs in the `vela-defkit` namespace, under an account that may only write ConfigMaps there. | ||
|
|
||
| ## Install a module | ||
|
|
||
| ```yaml | ||
| apiVersion: core.oam.dev/v1beta1 | ||
| kind: Application | ||
| metadata: | ||
| name: defkit-vela-definitions | ||
| namespace: vela-system | ||
| labels: | ||
| defkit.oam.dev/module: vela-definitions | ||
| spec: | ||
| components: [] | ||
| workflow: | ||
| steps: | ||
| - name: render | ||
| type: defkit-render | ||
| properties: | ||
| git: https://github.com/kubevela/vela-go-definitions | ||
| version: main | ||
| prefix: dk- # optional: a prefix for every definition's name | ||
| types: [trait] # optional: only these kinds | ||
| outputs: | ||
| - name: rendered | ||
| valueFrom: configMap | ||
| - name: review | ||
| type: suspend | ||
| - name: apply | ||
| type: defkit-apply | ||
| inputs: | ||
| - from: rendered | ||
| parameterKey: configMap | ||
| ``` | ||
|
|
||
| `vela workflow resume -n vela-system defkit-vela-definitions` applies what was rendered. The full example is in `examples/`. | ||
|
|
||
| ## Parameters | ||
|
|
||
| | Name | Default | Description | | ||
| | --- | --- | --- | | ||
| | `image` | `oamdev/defkit-render:v0.1.0` | Image of the render Job: Go plus `defkit-render` | | ||
| | `repositories` | vela-go-definitions | Repositories a UI offers when adding a module; a module can still come from anywhere | | ||
|
|
||
| ## The render image | ||
|
|
||
| `render/` holds `defkit-render` and its Dockerfile. The image needs Go, since loading a module runs `go mod download` and `go run`. | ||
|
|
||
| ```shell | ||
| docker buildx build --platform linux/amd64,linux/arm64 -t oamdev/defkit-render:v0.1.0 render/ | ||
|
briankane marked this conversation as resolved.
Resolved
|
||
| ``` | ||
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,16 @@ | ||
| # The render Job's image: defkit-render plus Go, since loading a DefKit module | ||
| # runs `go mod download` and `go run` in the Job. | ||
| FROM golang:1.23.8-alpine AS build | ||
| WORKDIR /src | ||
| COPY go.mod go.sum ./ | ||
| RUN go mod download | ||
| COPY main.go ./ | ||
| ARG TARGETOS TARGETARCH | ||
| RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags "-s -w" -o /defkit-render . | ||
|
|
||
| FROM golang:1.23.8-alpine | ||
| RUN apk add --no-cache git ca-certificates | ||
| ENV GOTOOLCHAIN=auto GOFLAGS=-mod=mod HOME=/tmp GOPATH=/tmp/go GOCACHE=/tmp/go-cache | ||
| COPY --from=build /defkit-render /usr/local/bin/defkit-render | ||
| USER 65532:65532 | ||
| ENTRYPOINT ["/usr/local/bin/defkit-render"] |
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.