FAQ

    KubeVela is a platform builder tool to create easy-to-use yet extensible app delivery/management systems with Kubernetes. KubeVela relies on Helm as templating engine and package format for apps. But Helm is not the only templating module that KubeVela supports. Another first-class supported approach is CUE.

    Also, KubeVela is by design a Kubernetes controller (i.e. works on server side), even for its Helm part, a Helm operator will be installed.

    Error: unable to create new content in namespace cert-manager because it is being terminated

    Occasionally you might hit the issue as below. It happens when the last KubeVela release deletion hasn’t completed.

    3. install chart vela-core, version 0.1.0, desc : A Helm chart for Kube Vela core, contains 35 file
    5. Failed to install the chart with error: serviceaccounts "cert-manager-cainjector" is forbidden: unable to create new content in namespace cert-manager because it is being terminated
    7. failed to create resource
    9. helm.sh/helm/v3/pkg/kube.(*Client).Update.func1
    11.     /home/runner/go/pkg/mod/helm.sh/helm/v3@v3.2.4/pkg/kube/client.go:190
    13. ...
    15. Error: failed to create resource: serviceaccounts "cert-manager-cainjector" is forbidden: unable to create new content in namespace cert-manager because it is being terminated

    Take a break and try again in a few seconds.

    1. vela install
    1. - Installing Vela Core Chart:
    3. Vela system along with OAM runtime already exist.
    5. Automatically discover capabilities successfully ✅ Add(0) Update(0) Delete(8)
    10. TYPE        CATEGORY    DESCRIPTION
    12. -task       workload    One-off task to run a piece of code or script to completion
    14. -webservice workload    Long-running scalable service with stable endpoint to receive external traffic
    16. -worker     workload    Long-running scalable backend worker without network endpoint
    18. -autoscale  trait       Automatically scale the app following certain triggers or metrics
    20. -metrics    trait       Configure metrics targets to be monitored for the app
    22. -rollout    trait       Configure canary deployment strategy to release the app
    24. -route      trait       Configure route policy to the app
    26. -scaler     trait       Manually scale the app
    31. - Finished successfully.

    And manually apply all WorkloadDefinition and TraitDefinition manifests to have all capabilities back.

    1. vela up -f charts/vela-core/templates/defwithtemplate
    1. traitdefinition.core.oam.dev/autoscale created
    3. traitdefinition.core.oam.dev/scaler created
    5. traitdefinition.core.oam.dev/metrics created
    7. traitdefinition.core.oam.dev/rollout created
    9. traitdefinition.core.oam.dev/route created
    11. workloaddefinition.core.oam.dev/task created
    13. workloaddefinition.core.oam.dev/webservice created
    15. workloaddefinition.core.oam.dev/worker created
    1. vela workloads
    1. Automatically discover capabilities successfully ✅ Add(8) Update(0) Delete(0)
    6. TYPE        CATEGORY    DESCRIPTION
    8. +task       workload    One-off task to run a piece of code or script to completion
    10. +webservice workload    Long-running scalable service with stable endpoint to receive external traffic
    12. +worker     workload    Long-running scalable backend worker without network endpoint
    14. +autoscale  trait       Automatically scale the app following certain triggers or metrics
    16. +metrics    trait       Configure metrics targets to be monitored for the app
    17. +rollout    trait       Configure canary deployment strategy to release the app
    19. +route      trait       Configure route policy to the app
    21. +scaler     trait       Manually scale the app
    26. NAME        DESCRIPTION
    28. task        One-off task to run a piece of code or script to completion
    30. webservice  Long-running scalable service with stable endpoint to receive external traffic
    32. worker      Long-running scalable backend worker without network endpoint

    Occasionally you might hit the issue as below. It happens when there is an old OAM Kubernetes Runtime release, or you applied ScopeDefinition before.

    1. vela install
    1.   - Installing Vela Core Chart:
    3.   install chart vela-core, version 0.1.0, desc : A Helm chart for Kube Vela core, contains 35 file
    5.   Failed to install the chart with error: ScopeDefinition "healthscopes.core.oam.dev" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-name" must equal "kubevela": current value is "oam"; annotation validation error: key "meta.helm.sh/release-namespace" must equal "vela-system": current value is "oam-system"
    7.   rendered manifests contain a resource that already exists. Unable to continue with install
    9.   helm.sh/helm/v3/pkg/action.(*Install).Run
    11.     /home/runner/go/pkg/mod/helm.sh/helm/v3@v3.2.4/pkg/action/install.go:274
    13.   ...
    15.   Error: rendered manifests contain a resource that already exists. Unable to continue with install: ScopeDefinition "healthscopes.core.oam.dev" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-name" must equal "kubevela": current value is "oam"; annotation validation error: key "meta.helm.sh/release-namespace" must equal "vela-system": current value is "oam-system"
    1. kubectl delete ScopeDefinition "healthscopes.core.oam.dev"
    1. vela install
    1. - Installing Vela Core Chart:
    3. install chart vela-core, version 0.1.0, desc : A Helm chart for Kube Vela core, contains 35 file
    5. Successfully installed the chart, status: deployed, last deployed time = 2020-12-03 16:26:41.491426 +0800 CST m=+4.026069452
    7. WARN: handle workload template `containerizedworkloads.core.oam.dev` failed: no template found, you will unable to use this workload capabilityWARN: handle trait template `manualscalertraits.core.oam.dev` failed
    9. : no template found, you will unable to use this trait capabilityAutomatically discover capabilities successfully ✅ Add(8) Update(0) Delete(0)
    14. TYPE        CATEGORY    DESCRIPTION
    16. +task       workload    One-off task to run a piece of code or script to completion
    18. +webservice workload    Long-running scalable service with stable endpoint to receive external traffic
    20. +worker     workload    Long-running scalable backend worker without network endpoint
    22. +autoscale  trait       Automatically scale the app following certain triggers or metrics
    24. +metrics    trait       Configure metrics targets to be monitored for the app
    26. +rollout    trait       Configure canary deployment strategy to release the app
    28. +route      trait       Configure route policy to the app
    30. +scaler     trait       Manually scale the app
    35. - Finished successfully.

    You have reached your pull rate limit

    When you look into the logs of Pod kubevela-vela-core and found the issue as below.

    1. kubectl get pod -n vela-system -l app.kubernetes.io/name=vela-core
    1. NAME                                 READY   STATUS    RESTARTS   AGE
    3. kubevela-vela-core-f8b987775-wjg25   0/1     -         0          35m

    You can use github container registry instead.

    1. docker pull ghcr.io/oam-dev/kubevela/vela-core:latest

    If you hit the issue as below, an cert-manager release might exist whose namespace and RBAC related resource conflict with KubeVela.

    1. vela install
    1. - Installing Vela Core Chart:
    3. install chart vela-core, version 0.1.0, desc : A Helm chart for Kube Vela core, contains 35 file
    5. Failed to install the chart with error: Namespace "cert-manager" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "kubevela"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "vela-system"
    7. rendered manifests contain a resource that already exists. Unable to continue with install
    9. helm.sh/helm/v3/pkg/action.(*Install).Run
    11.         /home/runner/go/pkg/mod/helm.sh/helm/v3@v3.2.4/pkg/action/install.go:274
    13. ...
    15.         /opt/hostedtoolcache/go/1.14.12/x64/src/runtime/asm_amd64.s:1373
    17. Error: rendered manifests contain a resource that already exists. Unable to continue with install: Namespace "cert-manager" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "kubevela"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "vela-system"

    Try these steps to fix the problem.

    • Delete release cert-manager
    • Delete namespace cert-manager
    • Install KubeVela again
    1. helm delete cert-manager -n cert-manager
    1. release "cert-manager" uninstalled
    1. kubectl delete ns cert-manager
    1. vela install
    1. - Installing Vela Core Chart:
    2. install chart vela-core, version 0.1.0, desc : A Helm chart for Kube Vela core, contains 35 file
    4. Successfully installed the chart, status: deployed, last deployed time = 2020-12-04 10:46:46.782617 +0800 CST m=+4.248889379
    6. Automatically discover capabilities successfully ✅ (no changes)
    11. TYPE        CATEGORY    DESCRIPTION
    13. task        workload    One-off task to run a piece of code or script to completion
    15. webservice  workload    Long-running scalable service with stable endpoint to receive external traffic
    17. worker      workload    Long-running scalable backend worker without network endpoint
    19. autoscale   trait       Automatically scale the app following certain triggers or metrics
    21. metrics     trait       Configure metrics targets to be monitored for the app
    23. rollout     trait       Configure canary deployment strategy to release the app
    25. route       trait       Configure route policy to the app
    27. scaler      trait       Manually scale the app
    29. - Finished successfully.

    How to fix issue: MutatingWebhookConfiguration mutating-webhook-configuration exists?

    If you deploy some other services which will apply MutatingWebhookConfiguration mutating-webhook-configuration, installing KubeVela will hit the issue as below.

    1. - Installing Vela Core Chart:
    3. install chart vela-core, version v0.2.1, desc : A Helm chart for Kube Vela core, contains 36 file
    5. Failed to install the chart with error: MutatingWebhookConfiguration "mutating-webhook-configuration" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "kubevela"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "vela-system"
    7. rendered manifests contain a resource that already exists. Unable to continue with install
    9. helm.sh/helm/v3/pkg/action.(*Install).Run
    11.     /home/runner/go/pkg/mod/helm.sh/helm/v3@v3.2.4/pkg/action/install.go:274
    13. github.com/oam-dev/kubevela/pkg/commands.InstallOamRuntime
    15.     /home/runner/work/kubevela/kubevela/pkg/commands/system.go:259
    17. github.com/oam-dev/kubevela/pkg/commands.(*initCmd).run
    19.     /home/runner/work/kubevela/kubevela/pkg/commands/system.go:162
    21. github.com/oam-dev/kubevela/pkg/commands.NewInstallCommand.func2
    23.     /home/runner/work/kubevela/kubevela/pkg/commands/system.go:119
    25. github.com/spf13/cobra.(*Command).execute
    27.     /home/runner/go/pkg/mod/github.com/spf13/cobra@v1.1.1/command.go:850
    29. github.com/spf13/cobra.(*Command).ExecuteC
    31.     /home/runner/go/pkg/mod/github.com/spf13/cobra@v1.1.1/command.go:958
    33. github.com/spf13/cobra.(*Command).Execute
    35.     /home/runner/go/pkg/mod/github.com/spf13/cobra@v1.1.1/command.go:895
    37. main.main
    39.     /home/runner/work/kubevela/kubevela/references/cmd/cli/main.go:16
    41. runtime.main
    43.     /opt/hostedtoolcache/go/1.14.13/x64/src/runtime/proc.go:203
    45. runtime.goexit
    47.     /opt/hostedtoolcache/go/1.14.13/x64/src/runtime/asm_amd64.s:1373
    49. Error: rendered manifests contain a resource that already exists. Unable to continue with install: MutatingWebhookConfiguration "mutating-webhook-configuration" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "kubevela"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "vela-system"

    To fix this issue, please upgrade KubeVela Cli vela version to be higher than v0.2.2 from .

    Operating Autoscale depends on metrics server, so it has to be enabled in various clusters. Please check whether metrics server is enabled with command kubectl top nodes or kubectl top pods.

    If the output is similar as below, the metrics is enabled.

    1. kubectl top nodes
    1. NAME                     CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
    3. cn-hongkong.10.0.1.237   288m         7%     5378Mi          78%
    5. cn-hongkong.10.0.1.238   351m         8%     5113Mi          74%
    1. kubectl top pods
    1. NAME                          CPU(cores)   MEMORY(bytes)
    3. php-apache-65f444bf84-cjbs5   0m           1Mi
    5. wordpress-55c59ccdd5-lf59d    1m           66Mi
    • ACK (Alibaba Cloud Container Service for Kubernetes)

    Metrics server is already enabled.

    • ASK (Alibaba Cloud Serverless Kubernetes)

    Metrics server has to be enabled in Operations/Add-ons section of Alibaba Cloud console as below.

    Please refer to if you hit more issue.

    • Kind

    Install metrics server as below, or you can install the latest version.

    1. kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/v0.3.7/components.yaml

    Also add the following part under .spec.template.spec.containers in the yaml file loaded by kubectl edit deploy -n kube-system metrics-server.

    Noted: This is just a walk-around, not for production-level use.

    1. command:
    3. - /metrics-server
    • MiniKube

    Enable it with following command.

    1. minikube addons enable metrics-server

    Have fun to on your application.