github/kubevela
1
0
Fork 0
mirror of https://github.com/kubevela/kubevela.git synced 2026-08-19 04:26:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: add extending vela (#511)

Browse Source 
* doc: add extending vela

- also rename in `system update` name -> type, type -> category

Signed-off-by: Hongchao Deng <hongchaodeng1@gmail.com>

* github action: fixed ubuntu version

Signed-off-by: Hongchao Deng <hongchaodeng1@gmail.com>

* update
This commit is contained in:
Hongchao Deng
2020-11-05 10:09:29 +08:00
committed by GitHub
parent d621cc34b6
commit 1809b47bb9
6 changed files with 144 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/go.yml
+1 -2
View File
@@ -9,7 +9,7 @@ on:
jobs:
build:
name: unit-tests
runs-on: ubuntu-latest
runs-on: ubuntu-20.04
steps:
- name: Set up Go 1.14
uses: actions/setup-go@v1
@@ -22,7 +22,6 @@ jobs:
- name: Install ginkgo
run: |
sudo apt-get update
sudo apt-get install -y golang-ginkgo-dev
- name: Setup Kind Cluster
docs/README.md
+1
View File
@@ -21,6 +21,7 @@ Learn and use KubeVela with tutorials and user stories.
- [Port Forward to Container](developers/port-forward.md)
- [Configuring data/env in Application](developers/config-app.md)
- [Consuming Cloud Services](developers/cloud-service.md)
- [Capability References](developers/references/README.md)
**For Platform Engineers**
- [Extending KubeVela](platform-engineers/extending-kubevela.md)
docs/developers/references/README.md
+7 -6
View File
@@ -1,8 +1,9 @@
# KubeVela Workload Types and Traits References.
Note: All the contents under this directory are designed to be referenced by other documentations as the full schema or usage of specific workload types or traits..
In the upcoming releases, we plan to auto-generate all these reference documentations from the CUE templates in KubeVela's definition objects.
# KubeVela Capability References
- [workload types](https://github.com/oam-dev/kubevela/tree/master/docs/developers/references/workload-types)
- [trait types](https://github.com/oam-dev/kubevela/tree/master/docs/developers/references/traits)
- [trait](https://github.com/oam-dev/kubevela/tree/master/docs/developers/references/traits)
Note: All the contents under this directory are designed to be referenced by other documentations as the full schema or usage of specific workload types or traits.
In the upcoming releases, we plan to auto-generate all these reference documentations from the CUE templates in KubeVela's definition objects.
docs/platform-engineers/extending-kubevela.md
+134 -12
View File
@@ -1,22 +1,144 @@
# Extending KubeVela
# Extending Capabilities in KubeVela
## Add a new application trait to KubeVela
## How Capabilities Work
> TODO: Steps to integrate a external capability, use kubewatch as example is good.
A Capability is a functionality provided by the infrastructure that users can configure to run and operate applications.
Vela has [an extensible capability system](../design.md#2-capability-oriented-architecture) that allows platform builders to bring bespoke infrastructure capabilityes into Vela by writing YAML definitions and CUE templates.
### Step 1: Reference the API resource as capability
In the following tutorial, you will learn how to add a new capability and expose it to users via CLI/Appfile.
The new capability is a type of trait but the same process applies to workload as well.
> TODO: introducing Definition object
## Add A New Capability
### Step 2: Define the capability template
Prerequisites:
> TODO: introducing CUE template
- [helm v3](https://helm.sh/docs/intro/install/)
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
### Step 3 (optional): Define the third-party dependencies
### Step 1: Install KubeWatch
> TODO: how to define that my trait relies on Prometheus by using CRD discover mechanism? Manually install and guarantee the dependency for now is fine.
```console
$ helm repo add vela-demo https://wonderflow.info/kubewatch/archives/
$ helm install kubewatch vela-demo/kubewatch --version 0.1.0
```
## Add a new workload type to KubeVela
### Step 2: Add Trait Definition with CUE template
> TODO: Steps to integrate a external capability, use statefulset or cloneset as example is good.
<!-- Three steps to integrate a external capability -->
```console
$ cat << EOF | kubectl apply -f -
apiVersion: core.oam.dev/v1alpha2
kind: TraitDefinition
metadata:
name: kubewatch
annotations:
definition.oam.dev/apiVersion: labs.bitnami.com/v1alpha1
definition.oam.dev/kind: KubeWatch
definition.oam.dev/description: "Add a watch for resource"
spec:
appliesToWorkloads:
- "*"
workloadRefPath: spec.workloadRef
definitionRef:
name: kubewatches.labs.bitnami.com
extension:
template: |
output: {
apiVersion: "labs.bitnami.com/v1alpha1"
kind: "KubeWatch"
spec: handler: webhook: url: parameter.webhook
}
parameter: {
webhook: string
}
EOF
```
That's it! Once you have applied the definition file the feature will be automatically registered in Vela Server and exposed to users.
### Step 3: Verify New Trait
Verify new trait:
```console
$ vela traits
Synchronizing capabilities from cluster⌛ ...
Sync capabilities successfully ✅ Add(1) Update(0) Delete(0)
TYPE CATEGORY DESCRIPTION
+kubewatch trait Add a watch for resource
Listing trait capabilities ...
NAME DESCRIPTION APPLIES TO
kubewatch Add a watch for resource
...
```
### Step 4: Adding Kubewatch Trait to The App
Write an Appfile:
```console
$ cat << EOF > vela.yaml
name: testapp
services:
testsvc:
type: webservice
image: crccheck/hello-world
port: 8000
route:
domain: testsvc.example.com
EOF
```
Deploy it:
```console
$ vela up
...
✅ App has been deployed 🚀🚀🚀
Port forward: vela port-forward testapp
SSH: vela exec testapp
Logging: vela logs testapp
App status: vela status testapp
Service status: vela status testapp --svc testsvc
```
You can use either of the following options to attach the newly added kubewatch trait to the App:
#### Option 1: Testing in CLI
Add kubewatch trait to the application:
```console
$ vela kubewatch testapp --svc testsvc --webhook https://hooks.slack.com/<your-token>
Adding kubewatch for app testsvc
⠋ Checking Status ...
✅ Application Deployed Successfully!
- Name: testsvc
Type: webservice
HEALTHY Ready: 1/1
Traits:
- ✅ kubewatch: webhook=https://hooks.slack.com/...
...
```
Check your Slack channel to verify the nofitications:
![Image of Kubewatch](../../resources/kubewatch-notif.jpg)
#### Option 2: Testing in Appfile
Instead of using CLI, you can add `kubewatch` config to Appfile:
```yaml
$ cat << EOF >> vela.yaml
kubewatch:
webhook: https://hooks.slack.com/<your-token>
EOF
```
Deploy it:
```
$ vela up
```
pkg/commands/refresh.go
+1 -1
View File
@@ -79,7 +79,7 @@ func RefreshDefinitions(ctx context.Context, c client.Client, ioStreams cmdutil.
func printRefreshReport(newCaps, oldCaps []types.Capability, io cmdutil.IOStreams) {
report := refreshResultReport(newCaps, oldCaps)
table := uitable.New()
table.AddRow("NAME", "TYPE", "DESCRIPTION")
table.AddRow("TYPE", "CATEGORY", "DESCRIPTION")
if len(report[added]) == 0 && len(report[updated]) == 0 && len(report[deleted]) == 0 {
// no change occurs, just show all existing caps
resources/kubewatch-notif.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB