Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 118 additions & 0 deletions experimental/addons/defkit/definitions/defkit-apply.cue
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
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"}
}
}
// A render that cannot be read, or has no definitions.json, fails the step.
if rendered.$returns.err != _|_ {
renderUnreadable: builtin.#Fail & {
$params: message: "read render vela-defkit/\(parameter.configMap): \(rendered.$returns.err)"
}
}
if rendered.$returns.err == _|_
if rendered.$returns.value != _|_
if rendered.$returns.value.data["definitions.json"] == _|_ {
renderIncomplete: builtin.#Fail & {
$params: message: "render vela-defkit/\(parameter.configMap) has no definitions.json"
}
}
_data: *{} | {...}
if rendered.$returns.err == _|_
if rendered.$returns.value.data != _|_ {
Comment thread
briankane marked this conversation as resolved.
Resolved
_data: rendered.$returns.value.data
}
// A render with errors fails the step and applies none of its definitions.
_errs: *[] | [...string]
if _data["errors.json"] != _|_ {
_errs: json.Unmarshal(_data["errors.json"])
}
if len(_errs) > 0 {
renderFailed: builtin.#Fail & {
$params: message: "render vela-defkit/\(parameter.configMap) failed for \(len(_errs)) definitions: \(strings.Join(list.Take(_errs, 3), "; "))"
}
}
_defs: *[] | [...{...}]
if len(_errs) == 0
if _data["definitions.json"] != _|_ {
_defs: json.Unmarshal(_data["definitions.json"])
Comment thread
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]
}
}
149 changes: 149 additions & 0 deletions experimental/addons/defkit/definitions/defkit-render.cue
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
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
"defkit.oam.dev/module-namespace": context.namespace
}
}
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"
// The module's code runs in the render container, which has no
// token; only the write container mounts the account's.
automountServiceAccountToken: false
restartPolicy: "Never"
securityContext: {runAsNonRoot: true, runAsUser: 65532}
volumes: [{
name: "work"
emptyDir: {}
}, {
name: "token"
projected: sources: [{
serviceAccountToken: path: "token"
}, {
configMap: {name: "kube-root-ca.crt", items: [{key: "ca.crt", path: "ca.crt"}]}
}, {
downwardAPI: items: [{path: "namespace", fieldRef: fieldPath: "metadata.namespace"}]
}]
}]
initContainers: [{
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, ","))",
"--out=/work/result.json",
]
// 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"}
}
volumeMounts: [{name: "work", mountPath: "/work"}]
}]
containers: [{
name: "write"
image: settings.$returns.value.data.image
imagePullPolicy: "IfNotPresent"
args: [
"--from=/work/result.json",
"--configmap=vela-defkit/\(_name)",
"--module=\(context.name)",
"--module-namespace=\(context.namespace)",
]
resources: {
requests: {cpu: "10m", memory: "32Mi"}
limits: {cpu: "200m", memory: "128Mi"}
}
volumeMounts: [{
name: "work"
mountPath: "/work"
readOnly: true
}, {
name: "token"
mountPath: "/var/run/secrets/kubernetes.io/serviceaccount"
readOnly: true
}]
}]
}
}
}
}

_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
// The git URL is left out: it may carry credentials.
message: strings.Join([for w in ["rendering DefKit module", parameter.ref, parameter.version] if w != "" {w}], " ")
}
}
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")]
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# 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:
# Definitions a new version drops are kept, not garbage collected: Applications may still use them.
- name: keep-removed-definitions
type: garbage-collect
properties:
keepLegacyResource: true
Comment thread
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
11 changes: 11 additions & 0 deletions experimental/addons/defkit/metadata.yaml
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
20 changes: 20 additions & 0 deletions experimental/addons/defkit/parameter.cue
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
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"
}] | [...#Repository]
}

// #Repository names its module by git or by ref, never both.
#Repository: ({git!: string, ref?: _|_, ...} | {ref!: string, git?: _|_, ...}) & {
name: string
git?: string
ref?: string
version?: string
description?: string
}
61 changes: 61 additions & 0 deletions experimental/addons/defkit/readme.md
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, unless it keeps them with the `garbage-collect` policy's `keepLegacyResource`, as the example does.

The render Job runs in the `vela-defkit` namespace. The module's code runs in a container with no service account token; a second container then writes the result to a ConfigMap, 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 --push render/
```
Loading
Loading