diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index 8eaa07a7f..705aa820a 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -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 diff --git a/docs/README.md b/docs/README.md index 413429887..b0e7b0c76 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) diff --git a/docs/developers/references/README.md b/docs/developers/references/README.md index 9e40b5ca0..1291b4d83 100644 --- a/docs/developers/references/README.md +++ b/docs/developers/references/README.md @@ -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. diff --git a/docs/platform-engineers/extending-kubevela.md b/docs/platform-engineers/extending-kubevela.md index b10fc7c12..65c4954ce 100644 --- a/docs/platform-engineers/extending-kubevela.md +++ b/docs/platform-engineers/extending-kubevela.md @@ -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. - \ No newline at end of file +```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/ +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/ +EOF +``` + +Deploy it: + +``` +$ vela up +``` diff --git a/pkg/commands/refresh.go b/pkg/commands/refresh.go index 1c6d26364..e86c64684 100644 --- a/pkg/commands/refresh.go +++ b/pkg/commands/refresh.go @@ -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 diff --git a/resources/kubewatch-notif.jpg b/resources/kubewatch-notif.jpg new file mode 100644 index 000000000..54eacf4da Binary files /dev/null and b/resources/kubewatch-notif.jpg differ