kubevela / kubevela.github.io

KubeVela documentations and website (https://kubevela.io).

KubeVela Docs & Website

This repo contains the source code of Kubevela website and all of the docs for KubeVela. It's built by Docusaurus 2, a modern static website generator.

Welcome to join us and you are more than appreciated to contribute!

Contributing to KubeVela EN Docs

First, we have the source documentation of Kubevela website and it's written in English. Follow Localization README for contributing to other languages. Any files modifid here will trigger the check-docs Github action to run and validate the docs could be build successfully into the website. Any changes on these files(docs/en/*, docs/en/resource/*, sidebars.js) will be submitted to the corresponding locations of the repo kubevela.io. The Github-Action there will parse the document and publish it to the Kubevela Website automatically.

Please follow our guides below to learn how to write the docs in the right way.

Add or Update Docs

When you add or modify the docs, these three files(docs/en/, docs/en/resource/ and sidebars.js) should be taken into consideration.

1. docs/en/, the main English documentation files are mainly located in this folder. All markdown files need to follow the format, that the title at the beginning should be in the following format:

   ---
   title: Title Name
   ---
   

   When you want to add a link refer to any .md files inside the docs(docs/en), you need to use relative path and remove the .md suffix. For example, the en/helm/component.md has a link refer to en/platform-engineers/definition-and-templates.md. Then the format should like:

   [the definition and template concepts](../platform-engineers/definition-and-templates)

2. docs/en/resource/, image files are located in this folder. When you want to use link any image in documentation, you should put the image resources here and use a relative path like below:

    ![alt](./resources/concepts.png)

3. sidebars.js, this file contain the navigation information of the KubeVela website. Please read the official docs of docusaurus to learn how to write sidebar.js.

      {
         type: 'category',
         label: 'Capability References',
         items: [
           // Note!: here must be add the path under "docs/en" 
           'developers/references/README',
           'developers/references/workload-types/webservice',
           'developers/references/workload-types/task',
           ...
         ],
       },

After you finished modify the docs, please try to have a preview of the changes.

Localization README

Language
Chinese

Website Preview

Please make sure you have yarn installed in your OS environment.

Installation

yarn install

Local Development

yarn start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

Build

yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

Versions for new release

All docs of new features should be updated in the latest docs, we will create a new version of docs along with the code release.

Build New Version

yarn docusaurus docs:version v1.x

Update Docs for version

make update-version version=v1.x

Send your pull request

After all changes checked well, please creating a pull request with DCO.

kubevela.github.io's Issues

update site.webmanifest

minor update
add name & short name
/assign

center hero block

/assign

change the jenkins CI integration document and use `vela up` command

https://kubevela.net/docs/case-studies/jenkins-cicd

This document working on vela core, there is no API server, so we will use vela up command to upgrade the application in the Deploy stage.

vela CLI must depend on the Kube API server.

编辑本页 got 404

Clicked the link of 编辑本页 in the page https://kubevela.io/zh/blog/kubevela-the-extensible-app-platform-based-on-open-application-model-and-kubernetes/, got 404.

Note: The language is in Chinese.

trait/rollout.md gives wrong command

trait/rollout.md may give wrong command

In rollout.md , expansion part:

$ kubectl get deploy express-server-v1 -l app.oam.dev/component=express-server
NAME READY UP-TO-DATE AVAILABLE AGE
express-server-v1 7/7 7 7 2m

which will give error message:
error: name cannot be provided when a selector is specified

change i18n icon to en/zh

Our i18n icon is en/jp while we don't have jp version of docs, we have zh. I hope we can change the icon.

We should change the icon from:

to the expect:

Here's a doc site which is also built with Docusaurus, we can refer to their way to change: https://wails.io/ .

ping @Arhell please help.

Add some reference documents about LDAP and OIDC connector configurations.

https://kubevela.net/docs/how-to/dashboard/config/dex-connectors

Add examples link in the website

The example should redirect to https://github.com/kubevela/samples

align the chinese content of the multi-cluster Delivery with the English version

As we have updated the docs : https://github.com/oam-dev/kubevela.io/blob/main/docs/case-studies/multi-cluster.md in #571 .

But the Chinese docs haven't updated.

https://github.com/oam-dev/kubevela.io/blob/main/i18n/zh/docusaurus-plugin-content-docs/current/case-studies/multi-cluster.md

translation of doc: contributor/release-process

https://kubevela.net/zh/docs/contributor/release-process

change the rollout how-to document

After 1.3, the rollout controller moves to Addon, so, we should let users know, they must enable rollout addon before using.

Doc path: docs/end-user/traits/rollout

translation: contributor/code-conventions

https://kubevela.net/zh/docs/contributor/code-conventions

[Update] Remove ZONE and PVC parameter for alibaba-rds

ZONE and PVC won't be available after v1.2.

Principle: the published feature must be ready to use not ready to read.

translate i18n/zh/docusaurus-plugin-content-docs/current/helm/trait.md

除翻译规则外，是否可以使用自动翻译软件修改呢？谢谢

4 parameters of build-in Component "task" are not introduced in doc

1. run vela def get task
2. it shows that "task" has 14 parameters
3. "labels", "annotations", "imagePullPolicy" and "imagePullSecrets" are not introduced in document.

vela version is

Version: v1.2.1
GitRevision: git-12f392c
GolangVersion: go1.16.13

[i18n] Translate AI blog into English

Welcome to contribute the i18n of KubeVela.

Following these steps:
1.The original Chinese:https://github.com/oam-dev/kubevela.io/pull/530/files
2.Translate it into English.
3.ping @BinaryHB0916 to see how to publish it.

Provide an image for offline deploying in closed k8s cluster

Can kubevela.io website alone deployed in offline K8s cluster.
I find an image in dockerhub, but can not run normally.
！！！HELP

here what i DO:

1. docker pull yangsoon/kubevela.io:v1
2. docker run

Write a blog to introduce how to immigrate your legacy Terraform cloud resources to KubeVela

Based on the implementation of kubevela/kubevela#3672, it's better to write a blog to introduce how to immigrate your legacy Terraform cloud resources to KubeVela.

/cc @loheagn

Make offline installation more easier

Declare EXPOSE in Dockerfile

Give a standard and easy deployment method（including deployment, svc, ingress） in source code

(I build the source for the image, but now i have no idea the container port)

Explain `your ip address` when visiting an appliation by trait

In the doc, users are asked to visit the application by the following command https://kubevela.io/zh/docs/next/quick-start#%E4%B8%80%E4%B8%AA%E6%9C%80%E7%AE%80%E5%8D%95%E7%9A%84%E7%A4%BA%E4%BE%8B, while your ip address is not well documented.
$ curl -H "Host:testsvc.example.com" http://<your ip address>/

You can see the endpoint or address of your ingress. By getting it, you can direct users to visit the console of a cloud provider or by listing the ingress ojbect.

➜  kubevela.io git:(main) kubectl get ingress
NAME             CLASS    HOSTS                 ADDRESS         PORTS   AGE
express-server   <none>   testsvc.example.com   8.210.233.186   80      13m

Documentation plan about version 1.3

Getting Started

OAM Engine(Vela Core)

Tutorials

• Deploy the across the cloud application.
• Deploy Kubernetes workloads to multiple clusters.
• Deploy differentiated applications in multiple clusters.

How-To Guides

• how to list your application history versions. #603
• how to roll back your application at any time. #603
• how to deploy the existed deployment and service to other clusters.

VelaUX

Tutorials

• SSO with GitHub or LDAP.

How-To Guides

• how to manage the projects. #597
• how to manage the users. #597
• how to manage the roles. #597
• how to manage the cloud provider.
• how to manage the helm repository.
• how to manage the docker registry. #612
• how to manage the SSO provider.

Extension

• how to create a private addon registry.

References

remove package-lock.json

unnecessary file

Misleading message for new release 1.1

https://kubevela.io/docs/v1.1/end-user/components/webservice/#specification

Release 1.1 should not be the out-of-date release, right?

allow user to zoom larger the pictures in docs by mouse click

Currently, pictures in our docs are fixed in size, we can't see more details by click the pictures. Is it possible to zoom larger the picture by clicking it?

• Current experience:
  

• Expected experience by clicking mouse on the picture:
  

There is a title level error in the "Read" cue operator section of the velaql document

Add the addon English how-to document

https://kubevela.net/docs/how-to/dashboard/addon/overview

Command copy is not friendly

On page https://kubevela.io/docs/quick-start#step-2-deploy-your-first-application, when copying the command and paste it in cli, it will show as below.

$ kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/docs/examples/vela-app.yaml
application.core.oam.dev/first-vela-app created

This is not as expected. Only the command should be copied.

[Non code Contribution] Auto-generate cloud resource reference documentation

KubeVela is a powerful CI/CD platform that let you import and manage all kinds of cloud resources from almost every cloud vendor. To all these cloud resources, a clear doc of each that guides us to smoothly use it is necessary and very friendly to the community.

Regarding tons of cloud resources adding into the KubeVela platform, maintain their accordingly docs is a major task. It'll be landed even more faster with the help from you. Thanks for contribution!

Missing cloud resources doc (up to date of 2020/02/25, KEEP UPDATING):

• Azure MariaDB, example, adding up the missing ones at below
• Azure/GCP/AWS/TencentCloud/AlibabaCloud XXX
• ....

How-to in simply using Vela CLI(Make Azure MariaDB as a guide):

1. run a Vela CLI command vela addon enable terraform-azure that installs Azure Terraform provider for you
2. using vela def list to check the official name of MariaDB
   
3. using vela def doc-gen azure-database-mariadb -n vela-system to generate the doc
4. you'll find 2 azure-database-mariadb.md files that are in Chinese and English at the current directory
5. go submitting a PR to Supported Cloud Resource list
6. comment in this issue to let the community know and Hooray!

Installation link is broken on kubevela.io/docs

Section What's Next of Introduction has a link to Installation: https://kubevela.io/docs#whats-next

The link points to https://kubevela.io/install which does not exists.

The link works for the same page with an extra / at the end: https://kubevela.io/docs/#whats-next

Perhaps a redirect is needed.

fix logo on dark theme

/assign

Flux v2 chart package should put crd yaml in folder crds

Kubeval provide an instruction install flux2, detail in the link.
We should put crd.yaml in the package crds as the helm docs, otherwise if we uninstall fluxv2, the releated cr will be deleted.

add some installation guides for developer Prerequisites

1 Golang version 1.17+
2 Kubernetes version v1.20+ with ~/.kube/config configured.
3 ginkgo 1.14.0+ (just for E2E test)
4 golangci-lint 1.38.0+, it will install automatically if you run make, you can install it manually if the installation is too slow.
5 kubebuilder v3.1.0+ and you need to manually install the dependency tools for unit test.
6 CUE binary v0.3.0+

https://kubevela.io/docs/contributor/code-contribute#prerequisites

Remove prerequisites that can be automatically installed.

Provider a way to visit folders like "traits"

Currently, there seems no way to provide a link to introduce all traits to someone.

translate blog abstraction-kubevela

https://kubevela.net/zh/blog/2022/05/30/abstraction-kubevela

translate doc access application

https://kubevela.net/zh/docs/tutorials/access-application

update dependencies

up to date docusaurus
/assign

Make kubevela.io AS an addon in vela-core

The problem for the url route casue page-not-found

I'm not the expert for the GUI, but I guess the route has some problem, see:
when I refresh page: https://kubevela.io/docs/concepts/ and click the link at the end of this page, for example:

Then will get:

without refresh that page then click link no such issue.

translate doc helm multi-cluster

https://kubevela.net/zh/docs/tutorials/helm-multi-cluster

parameter "installTimeout" is not described in document for build-in component "helm"

Please refer to https://github.com/oam-dev/catalog/blob/master/addons/fluxcd/definitions/helm-release-def.yaml, "installTimeout" is one parameter of build-in component "helm".
But it is not described in online document

update btns on mobile

/assign

translation contributor/principle-of-test

https://kubevela.net/zh/docs/contributor/principle-of-test

[i18n] translate the serviceAccount Integration mechanism to ZH/CN

中文翻译： #542

[Todo] remove one deprecated section of CUE basic

Location: https://kubevela.io/docs/platform-engineers/cue/basic\
https://kubevela.io/zh/docs/platform-engineers/cue/basic#%E5%AF%BC%E5%85%A5-kubernetes-%E5%8C%85

Apply to: Both zh and en docs in v1.1 and NEXT

Confirmed with @leejanee

Doc link is missing

https://kubevela.io/zh/docs/next/quick-start#%E6%9D%A5%E8%87%AA-git-%E4%BB%93%E5%BA%93%E7%9A%84%E7%BB%84%E4%BB%B6%EF%BC%88%E5%9F%BA%E4%BA%8E-kustomize%EF%BC%89

enable velaux error

procedure:

1. follow https://kubevela.net/zh/docs/install to enable velaux

2. enable velaux

vela addon enable velaux serviceType=NodePort --version 1.3.1

3. one error is raised

➜  local vela addon enable velaux serviceType=NodePort --version 1.3.1
Error: specified version 1.3.1 not exist
➜  local

expected result:

1. velaux can be installed without error

investigation:

1. try to list all addons

➜  local vela addon list | grep vela
velaux                   	KubeVela	KubeVela User Experience (UX). An extensible, application-oriented delivery and management Dashboard.	[v1.3.1, v1.3.0, v1.3.0-beta.2, ...]	disabled
➜  local

you will see the version is not "1.3.1" but "v1.3.1"

2. so try

➜  local vela addon enable velaux serviceType=NodePort --version v1.3.1
I0416 10:27:22.365686   40354 apply.go:107] "creating object" name="workflowstep-uischema-webhook" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.378243   40354 apply.go:107] "creating object" name="component-uischema-task" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.386727   40354 apply.go:107] "creating object" name="addon-uischema-velaux" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.397918   40354 apply.go:107] "creating object" name="trait-uischema-scaler" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.407483   40354 apply.go:107] "creating object" name="trait-uischema-storage" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.416482   40354 apply.go:107] "creating object" name="component-uischema-k8s-objects" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.426224   40354 apply.go:107] "creating object" name="component-uischema-webservice" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.437073   40354 apply.go:107] "creating object" name="workflowstep-uischema-notification" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.447968   40354 apply.go:107] "creating object" name="workflowstep-uischema-deploy2env" resource="/v1, Kind=ConfigMap"
I0416 10:27:22.460360   40354 apply.go:107] "creating object" name="addon-secret-velaux" resource="/v1, Kind=Secret"
Addon: velaux enabled Successfully.
Please access the velaux from the following endpoints:
+---------+-----------+----------------------------+---------------------------+
| CLUSTER | COMPONENT |  REF(KIND/NAMESPACE/NAME)  |         ENDPOINT          |
+---------+-----------+----------------------------+---------------------------+
|         | velaux    | Service/vela-system/velaux | http://192.168.65.4:30150 |
+---------+-----------+----------------------------+---------------------------+

It works now!

The Chinese and English documents on deploying "kubevela" using "kind" in the official website are inconsistent

The Chinese and English documents on deploying "kubevela" using "kind" in the official website are inconsistent, and there are problems with the Chinese version of the documents.

Chinese:

English:

add favicons

https://realfavicongenerator.net/favicon_checker?protocol=https&site=kubevela.io%2F#.Yo32sKjP23A
/assign

fix github icon on dark theme

/assign

[bug] incorrect output for vela cli installation

install vela cli using https://kubevela.io/script/install.sh, the output like:

Installing v1.2.0-rc.2 Vela CLI...
Downloading https://github.com/oam-dev/kubevela/releases/download/v1.2.0-rc.2/vela-v1.2.0-rc.2-darwin-amd64.tar.gz ...
cp: /usr/local/bin/vela: Permission denied
vela installed into /usr/local/bin successfully.
A Highly Extensible Platform Engine based on Kubernetes and Open Application Model.

i have old version vela-cli at /usr/local/bin/vela, and the cp command was failed by Permission denied, but it still output vela installed into /usr/local/bin successfully.