kubevela
/
kubevela.github.io
mirror of https://github.com/kubevela/kubevela.github.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

refine user guide 

Signed-off-by: Jianbo Sun <jianbo.sjb@alibaba-inc.com>
This commit is contained in:
Jianbo Sun 2022-05-19 16:14:52 +08:00
parent a929386f8d
commit 894fbc41ef
16 changed files with 611 additions and 424 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/case-studies/multi-cluster.md
View File

@ -1,5 +1,5 @@
---
title: Multi-Cluster Delivery
title: Deploy across Multi-Clusters
---
KubeVela is by design a full functional Continuous Delivery (CD) platform with fine grained support for hybrid/multi-cloud/multi-cluster deployment.
@ -17,22 +17,10 @@ The following guide will introduce how to manage applications across clusters on
## Preparation
You can simply join an existing cluster into KubeVela by specifying its KubeConfig as below
Please make sure you have clusters in your control plane, in general, this work should be done by operator engineers.
If you're a DevOps engineer or trying KubeVela, you can refer to [manage cluster docs](../platform-engineers/system-operation/managing-clusters) to learn how to join clusters.
```shell script
vela cluster join <your kubeconfig path>
```
It will use the field `context.cluster` in KubeConfig as the cluster name automatically,
you can also specify the name by `--name` parameter. For example:
```shell
$ vela cluster join beijing.kubeconfig --name beijing
$ vela cluster join hangzhou-1.kubeconfig --name hangzhou-1
$ vela cluster join hangzhou-2.kubeconfig --name hangzhou-2
```
After clusters joined, you could list all clusters managed by KubeVela.
For the rest docs, we assume you have clusters with the following names:
```bash
$ vela cluster list
@ -45,27 +33,6 @@ cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
You can also detach a cluster if you do not want to use it anymore.
```shell script
$ vela cluster detach beijing
```
> It is dangerous to detach a cluster that is still in-use. But if you want to do modifications to the held cluster credential, like rotating certificates, it is possible to do so.
You can also give labels to your clusters, which helps you select clusters for deploying applications.
```bash
$ vela cluster labels add cluster-hangzhou-1 region=hangzhou
$ vela cluster labels add cluster-hangzhou-2 region=hangzhou
$ vela cluster list
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
local Internal - true
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true region=hangzhou
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true region=hangzhou
```
## Deliver Application to Clusters
To deliver your application into multiple clusters, you simply need to configure which clusters you want to deploy through the `topology` policy. For example, you can deploy an nginx webservice in hangzhou clusters by running the following commands
@ -530,7 +497,3 @@ If you already have applications running in production environment and do not wa
In this section, we introduced how KubeVela delivering micro services in multiple clusters, the whole process can be easily modeled as a declarative deployment plan.
No more add-hoc scripts or glue code, KubeVela will get the application delivery workflow done with full automation and determinism. Most importantly, KubeVela expects you keep using the CI solutions you are already familiar with and KubeVela is fully complementary to them as the CD control plane.
## Next Step
* Refer to more examples about [integrating with Jenkins](../tutorials/jenkins).

102
docs/end-user/components/ref-objects.md
View File

@ -1,5 +1,103 @@
---
title: Distributed External Kubernetes Objects
title: Distribute Reference Objects
---
This docs has been migrated, please refer to the [k8s-objects docs](../../tutorials/k8s-object#distributed-external-kubernetes-objects).
> This section requires you to know the basics about how to deploy multi-cluster application with policy and workflow. You can refer to [Multi-cluster Delivery](../../case-studies/multi-cluster) for container images, they're working in the same way.
You can reference and distribute existing Kubernetes objects with KubeVela in the following scenarios:
- Copying secrets from the hub cluster into managed clusters.
- Promote deployments from canary clusters into production clusters.
- Using Kubernetes apiserver as the control plane and storing all Kubernetes objects data in external databases. Then dispatch those data into real Kuberenetes managed clusters.
### Refer to Existing Kubernetes Objects in Component
To use existing Kubernetes objects in the component, you need to use the `ref-objects` typed component and declare which resources you want to refer to. For example, in the following example, the secret `image-credential-to-copy` in namespace `examples` will be taken as the source object for the component. Then you can use the topology policy to dispatch it into hangzhou clusters.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-example
namespace: examples
spec:
components:
- name: image-pull-secrets
type: ref-objects
properties:
objects:
- resource: secret
name: image-credential-to-copy
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
```
### Details for the *ref-objects* typed component
The most simple way to specify resources is to directly use `resource: secret` or `resource: deployment` to describe the kind of resources. If no `name` or `labelSelector` is set, the application will try to find the resource with the same name as the component name in the application's namespace. You can also explicitly specify `name` and `namespace` for the target resource as well.
In addition to `name` and `namespace`, you can also specify the `cluster` field to let the application component refer to resources in managed clusters. You can also use the `labelSelector` to select resources in replace of finding resources by names.
In the following example, the application will select all deployments in the *hangzhou-1* cluster inside the *examples* namespace, which matches the desided labels. Then the application will copy these deployments into *hangzhou-2* cluster.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-duplicate-deployments
namespace: examples
spec:
components:
- name: duplicate-deployment
type: ref-objects
properties:
objects:
- resource: deployment
cluster: hangzhou-1
# select all deployment in the `examples` namespace in cluster `hangzhou-1` that matches the labelSelector
labelSelector:
need-duplicate: "true"
policies:
- name: topology-hangzhou-2
type: topology
properties:
clusters: ["hangzhou-2"]
```
> In some cases, you might want to restrict the scope for the application to access resources. You can set the `--ref-objects-available-scope` to `namespace` or `cluster` in KubeVela controller's bootstrap parameter, to retrict the application to be only able to refer to the resources inside the same namespace or the same cluster.
### Working with Trait
The *ref-objects* typed component can also be used together with traits. The implicit main workload is the first referenced object and trait patch will be applied on it. The following example demonstrate how to set the replica number for the referenced deployment while deploying it in hangzhou clusters.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-multiple-resources
namespace: examples
spec:
components:
- name: nginx-ref-multiple-resources
type: ref-objects
properties:
objects:
- resource: deployment
- resource: service
traits:
- type: scaler
properties:
replicas: 3
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
```

158
docs/how-to/dashboard/application/create-application.md
View File

@ -1,6 +1,6 @@
---
title: Create Application
description: create an application by kubevela dashboard
title: Lifecycle of Application
description: lifecycle of an application by kubevela dashboard
---
### Configure the basic information
@ -30,8 +30,156 @@ Different component types are different significantly, you can fill in the forms
After you finished configuring the application, click "Submit" to create the application. This means the application configuration was saved.
You need to [bind environment](./bind-new-environment) for real deployment.
### Bind Application with Environment
### Next Step
We can specify bind with one or more environments before deploy.
* [Bind Application with Environment](./bind-new-environment)
After we have created application and configured the baseline well, we can bind an application with environment to deploy.
You can bind with one environment as `dev` environment for develop and debug. When everything works well, you can bind with the production environment.
The operation likes below:
![bind-new-env](../../../resources/bind-new-env.jpg)
As the picture shows, in the application management page, click `Bind Environment`, choose the environment prepared.
If there's no environment, you can click the `Create new environment` for creation.
After choose well, click the `submit` button, it will show the new environment created on the right side of the baseline config as a tab.
KubeVela will automatically generate the deploy workflow for the newly created environments.
In the environment tab, you can click `Deploy` button to deploy the application.
### Deploy Application
After application created and bond with an environment, you can deploy the application instance.
#### First time deploy
You can view the application detail page by click the application name or the UI card.
The tabs on the right side of the `Baseline Config` are environments which bond by the application. Choose one of the environment you want to deploy. Click that tab, you'll see the picture below.
![app-not-deploy](../../../resources/app-not-deploy.jpg)
If this is the first time deploy, you'll see the Deploy button in the middle of the environment page, just click the `Deploy` button to deploy.
Then the workflow start to running, you can see the workflow status on the top right corner.
If you have configured a suspend workflow step, it will run and stop in that state. It will wait until you have checked your application well and click the approve button.
![workflow-suspend](../../../resources/workflow-suspend.jpg)
If there's something wrong with the workflow step, the workflow node will become red. Move your mouse to hover that area, you'll see the error reason.
![workflow-error](../../../resources/workflow-error.jpg)
#### Upgrade the application
There's a `Deploy` button on the top right corner, you can click that for deploy. On the right side of the button, there's detail button, you can choose which workflow to run if there's multiple environments configured.
![select-workflow](../../../resources/select-workflow.jpg)
You can upgrade the application in any state, as KubeVela is a declarative system. There will be a kindly reminder for you if the workflow is running when you want to upgrade.
### Check Application State
Different tabs of environment will show different application instances inside.
By default, it will display all instances deployed in the environment, you can filter the status by select targets.
![pod list](../../../resources/pod-list.jpg)
As the picture shows, check the application pod details by click the expand button("+") on the left. You can view the pod status including the events and error message about it.
For cloud resources, there will be a link to the cloud console for management.
![rds-instances](../../../resources/rds-instances.jpg)
### View Application Logs
![pod log](https://static.kubevela.net/images/1.3/pod-log.jpg)
You can view the logs of application in the environment tab.
By default, the logs will refresh every 5s. If your logs didn't have timestamp, you can click the `Show timestamps` to see.
You can also view logs from command line:
```bash
vela logs <app_name> -n <namespace>
```
Select a workload to view the logs.
### Expose your application for public access
You can configure your application for public access.
There're mainly three ways to expose your service.
1. Choose `webservice` Type and configure the service type to be `LoadBalancer` or `NodePort`.
2. Configure `gateway` trait, it works for `webservice`, `worker` and `task` component types. `gateway` trait must configure a domain and works only for HTTP/HTTPs protocols.
3. Case by case component configurations.
#### Expose service for `webservice` typed component
You can modify `ExposeType` to choose the way, and you should configure the `Service Ports` to listen the ports and turn on the `Expose` radio.
![webservice](../../../resources/webservice-port.jpg)
#### Add `gateway` trait
The `gateway` trait requires you have `Ingress Controller` available in your cluster. You can add this trait to expose your service and configure a domain.
![trait](../../../resources/gateway-trait-add.jpg)
As the picture shows, the `Domain` field configure your domain, please configure your DNS for domain to route to the Kubernetes cluster gateway IP.
In the `Http` section, you can configure the routing rules. For example, set `/`:`80` means the domain index page will route to the port `80`. You can configure this rule as you need.
Other component types can also be able to configure the service expose, but they're usually case by case, especially for helm charts.
### Get the service endpoint
After the application deployed with service exposed configuration, you can see a `Service Endpoint` button on the left of the `Recycle` button. You'll see the endpoint when hover your mouse there.
![service endpoint](../../../resources/service-endpoint.jpg)
### List Resources Created
If you want to learn the resources created by the applications, you can open the environment status page.
![app-resources](https://static.kubevela.net/images/1.3/app-resources.jpg)
There're three kinds of information including `Applied Resources`,`Conditions` and `Component Status`. The `Applied Resources` are all resources created by the applications.
You can also list resources from command line:
```bash
$ vela status <app_name> -n <namespace> --tree
```
### Recycle Application Instance
When you want to delete the application instance in some environment, you can click the `Recycle` button in that environment.
![pod list](../../../resources/pod-list.jpg)
It will delete the whole application instance with related resources.
> Note that recycle means delete an application, data can't be recovered automatically. Please make sure you have back up all the important data of this instance before recycle it.
### Delete Application
After all application instance were recycled, you can click `Remove` for deletion.
![delete application](../../../resources/app-delete.jpg)
As the picture shows, the `Remove` button is hidden in the application detail.
Now you have learned the basic lifecycle of an application.

60
docs/platform-engineers/system-operation/managing-clusters.md
View File

@ -15,33 +15,63 @@ For connecting the ACK clusters, the platform will save some cloud info, Region,
## Manage the cluster via CLI
### vela cluster list
This command could list all clusters managed by KubeVela currently.
```bash
$ vela cluster list
CLUSTER TYPE ENDPOINT
CLUSTER ALIAS TYPE ENDPOINT ACCEPTED LABELS
local Internal - true
ask-beijing X509Certificate https://*.*.*.*:6443 true
```
### vela cluster join
This command can join new cluster into KubeVela and name it as `cluster-prod`. The joined cluster can be used in [Multi-Environment Deployment](../../end-user/policies/envbinding).
You can simply join an existing cluster into KubeVela by specifying its KubeConfig as below
```shell script
$ vela cluster join example-cluster.kubeconfig --name cluster-prod
vela cluster join <your kubeconfig path>
```
It will use the field `context.cluster` in KubeConfig as the cluster name automatically,
you can also specify the name by `--name` parameter. For example:
```shell
$ vela cluster join beijing.kubeconfig --name beijing
$ vela cluster join hangzhou-1.kubeconfig --name hangzhou-1
$ vela cluster join hangzhou-2.kubeconfig --name hangzhou-2
```
### vela cluster list
After clusters joined, you could list all clusters managed by KubeVela.
```bash
$ vela cluster list
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
local Internal - true
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true
```
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
### label your cluster
You can also give labels to your clusters, which helps you select clusters for deploying applications.
```bash
$ vela cluster labels add cluster-hangzhou-1 region=hangzhou
$ vela cluster labels add cluster-hangzhou-2 region=hangzhou
$ vela cluster list
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
local Internal - true
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true region=hangzhou
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true region=hangzhou
```
### vela cluster detach
This command can be used to detach cluster from KubeVela.
You can also detach a cluster if you do not want to use it anymore.
```shell script
$ vela cluster detach cluster-prod
$ vela cluster detach beijing
```
> It is dangerous to detach a cluster that is still in-use. But if you want to do modifications to the held cluster credential, like rotating certificates, it is possible to do so.
### vela cluster rename
This command can rename cluster managed by KubeVela.

4
docs/tutorials/helm.md
View File

@ -128,7 +128,3 @@ Services:
```
At this point, Helm Chart in KubeVela is no stranger to you, go ahead and try more!
## Next step
- [Deploy Kubernetes Objects](./k8s-object)

107
docs/tutorials/k8s-object.mdx
View File

@ -11,13 +11,6 @@ KubeVela supports you to render, orchestrate and deploy Kubernetes objects. The
3. Multi-env/cluster in application delivery.
4. The control loop of application deployment: Rollback, Terminate and Continue.
What's more, you can even distribute existing Kubernetes objects with KubeVela in the following scenarios:
- Copying secrets from the hub cluster into managed clusters.
- Promote deployments from canary clusters into production clusters.
- Using Kubernetes apiserver as the control plane and storing all Kubernetes objects data in external databases. Then dispatch those data into real Kuberenetes managed clusters.
## Before starting
- Prepare a Deployment+Service yaml config resource.
@ -197,104 +190,4 @@ $ vela up -f https://kubevela.io/example/applications/app-with-k8s-objects.yaml
$ vela workflow resume app-with-k8s-objects
```
## Distributed External Kubernetes Objects
> This section requires you to know how to deploy multi-cluster application with policy and workflow first. You can refer to [Multi-cluster Application Delivery](../case-studies/multi-cluster) for details.
### Refer to Existing Kubernetes Objects in Component
To use existing Kubernetes objects in the component, you need to use the `ref-objects` typed component and declare which resources you want to refer to. For example, in the following example, the secret `image-credential-to-copy` in namespace `examples` will be taken as the source object for the component. Then you can use the topology policy to dispatch it into hangzhou clusters.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-example
namespace: examples
spec:
components:
- name: image-pull-secrets
type: ref-objects
properties:
objects:
- resource: secret
name: image-credential-to-copy
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
```
### Details for the *ref-objects* typed component
The most simple way to specify resources is to directly use `resource: secret` or `resource: deployment` to describe the kind of resources. If no `name` or `labelSelector` is set, the application will try to find the resource with the same name as the component name in the application's namespace. You can also explicitly specify `name` and `namespace` for the target resource as well.
In addition to `name` and `namespace`, you can also specify the `cluster` field to let the application component refer to resources in managed clusters. You can also use the `labelSelector` to select resources in replace of finding resources by names.
In the following example, the application will select all deployments in the *hangzhou-1* cluster inside the *examples* namespace, which matches the desided labels. Then the application will copy these deployments into *hangzhou-2* cluster.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-duplicate-deployments
namespace: examples
spec:
components:
- name: duplicate-deployment
type: ref-objects
properties:
objects:
- resource: deployment
cluster: hangzhou-1
# select all deployment in the `examples` namespace in cluster `hangzhou-1` that matches the labelSelector
labelSelector:
need-duplicate: "true"
policies:
- name: topology-hangzhou-2
type: topology
properties:
clusters: ["hangzhou-2"]
```
> In some cases, you might want to restrict the scope for the application to access resources. You can set the `--ref-objects-available-scope` to `namespace` or `cluster` in KubeVela controller's bootstrap parameter, to retrict the application to be only able to refer to the resources inside the same namespace or the same cluster.
### Working with Trait
The *ref-objects* typed component can also be used together with traits. The implicit main workload is the first referenced object and trait patch will be applied on it. The following example demonstrate how to set the replica number for the referenced deployment while deploying it in hangzhou clusters.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-multiple-resources
namespace: examples
spec:
components:
- name: nginx-ref-multiple-resources
type: ref-objects
properties:
objects:
- resource: deployment
- resource: service
traits:
- type: scaler
properties:
replicas: 3
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
```
Congrats! Now you've learned how to deploy Kubernetes objects.
## Next step
- [Deploy Cloud Service](./consume-cloud-services)
- [Distributed External Kubernetes Objects](../end-user/components/ref-objects)

4
docs/tutorials/webservice.md
View File

@ -119,7 +119,3 @@ Services:
* Refer to [webservice details](../end-user/components/references#webservice) to know usage of full fields.
* Refer to [trait reference](../end-user/traits/references) to know which traits can be used for webservice.
## Next Step
[Learn to deploy Helm Chart](./helm)

18
sidebars.js
View File

@ -33,7 +33,6 @@ module.exports = {
'end-user/traits/rollout',
'end-user/traits/ingress',
'end-user/traits/sidecar',
'tutorials/k8s-object',
],
},
{
@ -59,6 +58,7 @@ module.exports = {
collapsed: true,
items: [
'tutorials/k8s-object',
'end-user/components/ref-objects',
],
},
{
@ -73,23 +73,9 @@ module.exports = {
],
},
{
'How-to manage the applications': [
'General CD Features': [
'how-to/dashboard/application/create-application',
'how-to/dashboard/application/bind-new-environment',
'tutorials/workflows',
'how-to/dashboard/application/deploy-application',
'how-to/dashboard/application/get-application-instance',
'tutorials/scaler',
'how-to/dashboard/application/get-application-log',
'how-to/dashboard/application/get-application-endpoint',
'how-to/dashboard/application/view-application-resource',
'how-to/dashboard/application/get-application-revision',
'how-to/dashboard/application/recycle-environment',
'how-to/dashboard/application/delete-application',
],
},
{
'Advanced Features': [
'end-user/workflow/component-dependency-parameter',
'end-user/version-control',
'end-user/policies/apply-once',

45
versioned_docs/version-v1.3/case-studies/multi-cluster.md
View File

@ -1,5 +1,5 @@
---
title: Multi-Cluster Delivery
title: Deploy across Multi-Clusters
---
KubeVela is by design a full functional Continuous Delivery (CD) platform with fine grained support for hybrid/multi-cloud/multi-cluster deployment.
@ -17,22 +17,10 @@ The following guide will introduce how to manage applications across clusters on
## Preparation
You can simply join an existing cluster into KubeVela by specifying its KubeConfig as below
Please make sure you have clusters in your control plane, in general, this work should be done by operator engineers.
If you're a DevOps engineer or trying KubeVela, you can refer to [manage cluster docs](../platform-engineers/system-operation/managing-clusters) to learn how to join clusters.
```shell script
vela cluster join <your kubeconfig path>
```
It will use the field `context.cluster` in KubeConfig as the cluster name automatically,
you can also specify the name by `--name` parameter. For example:
```shell
$ vela cluster join beijing.kubeconfig --name beijing
$ vela cluster join hangzhou-1.kubeconfig --name hangzhou-1
$ vela cluster join hangzhou-2.kubeconfig --name hangzhou-2
```
After clusters joined, you could list all clusters managed by KubeVela.
For the rest docs, we assume you have clusters with the following names:
```bash
$ vela cluster list
@ -45,27 +33,6 @@ cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
You can also detach a cluster if you do not want to use it anymore.
```shell script
$ vela cluster detach beijing
```
> It is dangerous to detach a cluster that is still in-use. But if you want to do modifications to the held cluster credential, like rotating certificates, it is possible to do so.
You can also give labels to your clusters, which helps you select clusters for deploying applications.
```bash
$ vela cluster labels add cluster-hangzhou-1 region=hangzhou
$ vela cluster labels add cluster-hangzhou-2 region=hangzhou
$ vela cluster list
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
local Internal - true
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true region=hangzhou
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true region=hangzhou
```
## Deliver Application to Clusters
To deliver your application into multiple clusters, you simply need to configure which clusters you want to deploy through the `topology` policy. For example, you can deploy an nginx webservice in hangzhou clusters by running the following commands
@ -530,7 +497,3 @@ If you already have applications running in production environment and do not wa
In this section, we introduced how KubeVela delivering micro services in multiple clusters, the whole process can be easily modeled as a declarative deployment plan.
No more add-hoc scripts or glue code, KubeVela will get the application delivery workflow done with full automation and determinism. Most importantly, KubeVela expects you keep using the CI solutions you are already familiar with and KubeVela is fully complementary to them as the CD control plane.
## Next Step
* Refer to more examples about [integrating with Jenkins](../tutorials/jenkins).

102
versioned_docs/version-v1.3/end-user/components/ref-objects.md
View File

@ -1,5 +1,103 @@
---
title: Distributed External Kubernetes Objects
title: Distribute Reference Objects
---
This docs has been migrated, please refer to the [k8s-objects docs](../../tutorials/k8s-object#distributed-external-kubernetes-objects).
> This section requires you to know the basics about how to deploy multi-cluster application with policy and workflow. You can refer to [Multi-cluster Delivery](../../case-studies/multi-cluster) for container images, they're working in the same way.
You can reference and distribute existing Kubernetes objects with KubeVela in the following scenarios:
- Copying secrets from the hub cluster into managed clusters.
- Promote deployments from canary clusters into production clusters.
- Using Kubernetes apiserver as the control plane and storing all Kubernetes objects data in external databases. Then dispatch those data into real Kuberenetes managed clusters.
### Refer to Existing Kubernetes Objects in Component
To use existing Kubernetes objects in the component, you need to use the `ref-objects` typed component and declare which resources you want to refer to. For example, in the following example, the secret `image-credential-to-copy` in namespace `examples` will be taken as the source object for the component. Then you can use the topology policy to dispatch it into hangzhou clusters.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-example
namespace: examples
spec:
components:
- name: image-pull-secrets
type: ref-objects
properties:
objects:
- resource: secret
name: image-credential-to-copy
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
```
### Details for the *ref-objects* typed component
The most simple way to specify resources is to directly use `resource: secret` or `resource: deployment` to describe the kind of resources. If no `name` or `labelSelector` is set, the application will try to find the resource with the same name as the component name in the application's namespace. You can also explicitly specify `name` and `namespace` for the target resource as well.
In addition to `name` and `namespace`, you can also specify the `cluster` field to let the application component refer to resources in managed clusters. You can also use the `labelSelector` to select resources in replace of finding resources by names.
In the following example, the application will select all deployments in the *hangzhou-1* cluster inside the *examples* namespace, which matches the desided labels. Then the application will copy these deployments into *hangzhou-2* cluster.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-duplicate-deployments
namespace: examples
spec:
components:
- name: duplicate-deployment
type: ref-objects
properties:
objects:
- resource: deployment
cluster: hangzhou-1
# select all deployment in the `examples` namespace in cluster `hangzhou-1` that matches the labelSelector
labelSelector:
need-duplicate: "true"
policies:
- name: topology-hangzhou-2
type: topology
properties:
clusters: ["hangzhou-2"]
```
> In some cases, you might want to restrict the scope for the application to access resources. You can set the `--ref-objects-available-scope` to `namespace` or `cluster` in KubeVela controller's bootstrap parameter, to retrict the application to be only able to refer to the resources inside the same namespace or the same cluster.
### Working with Trait
The *ref-objects* typed component can also be used together with traits. The implicit main workload is the first referenced object and trait patch will be applied on it. The following example demonstrate how to set the replica number for the referenced deployment while deploying it in hangzhou clusters.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-multiple-resources
namespace: examples
spec:
components:
- name: nginx-ref-multiple-resources
type: ref-objects
properties:
objects:
- resource: deployment
- resource: service
traits:
- type: scaler
properties:
replicas: 3
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
```

158
versioned_docs/version-v1.3/how-to/dashboard/application/create-application.md
View File

@ -1,6 +1,6 @@
---
title: Create Application
description: create an application by kubevela dashboard
title: Lifecycle of Application
description: lifecycle of an application by kubevela dashboard
---
### Configure the basic information
@ -30,8 +30,156 @@ Different component types are different significantly, you can fill in the forms
After you finished configuring the application, click "Submit" to create the application. This means the application configuration was saved.
You need to [bind environment](./bind-new-environment) for real deployment.
### Bind Application with Environment
### Next Step
We can specify bind with one or more environments before deploy.
* [Bind Application with Environment](./bind-new-environment)
After we have created application and configured the baseline well, we can bind an application with environment to deploy.
You can bind with one environment as `dev` environment for develop and debug. When everything works well, you can bind with the production environment.
The operation likes below:
![bind-new-env](../../../resources/bind-new-env.jpg)
As the picture shows, in the application management page, click `Bind Environment`, choose the environment prepared.
If there's no environment, you can click the `Create new environment` for creation.
After choose well, click the `submit` button, it will show the new environment created on the right side of the baseline config as a tab.
KubeVela will automatically generate the deploy workflow for the newly created environments.
In the environment tab, you can click `Deploy` button to deploy the application.
### Deploy Application
After application created and bond with an environment, you can deploy the application instance.
#### First time deploy
You can view the application detail page by click the application name or the UI card.
The tabs on the right side of the `Baseline Config` are environments which bond by the application. Choose one of the environment you want to deploy. Click that tab, you'll see the picture below.
![app-not-deploy](../../../resources/app-not-deploy.jpg)
If this is the first time deploy, you'll see the Deploy button in the middle of the environment page, just click the `Deploy` button to deploy.
Then the workflow start to running, you can see the workflow status on the top right corner.
If you have configured a suspend workflow step, it will run and stop in that state. It will wait until you have checked your application well and click the approve button.
![workflow-suspend](../../../resources/workflow-suspend.jpg)
If there's something wrong with the workflow step, the workflow node will become red. Move your mouse to hover that area, you'll see the error reason.
![workflow-error](../../../resources/workflow-error.jpg)
#### Upgrade the application
There's a `Deploy` button on the top right corner, you can click that for deploy. On the right side of the button, there's detail button, you can choose which workflow to run if there's multiple environments configured.
![select-workflow](../../../resources/select-workflow.jpg)
You can upgrade the application in any state, as KubeVela is a declarative system. There will be a kindly reminder for you if the workflow is running when you want to upgrade.
### Check Application State
Different tabs of environment will show different application instances inside.
By default, it will display all instances deployed in the environment, you can filter the status by select targets.
![pod list](../../../resources/pod-list.jpg)
As the picture shows, check the application pod details by click the expand button("+") on the left. You can view the pod status including the events and error message about it.
For cloud resources, there will be a link to the cloud console for management.
![rds-instances](../../../resources/rds-instances.jpg)
### View Application Logs
![pod log](https://static.kubevela.net/images/1.3/pod-log.jpg)
You can view the logs of application in the environment tab.
By default, the logs will refresh every 5s. If your logs didn't have timestamp, you can click the `Show timestamps` to see.
You can also view logs from command line:
```bash
vela logs <app_name> -n <namespace>
```
Select a workload to view the logs.
### Expose your application for public access
You can configure your application for public access.
There're mainly three ways to expose your service.
1. Choose `webservice` Type and configure the service type to be `LoadBalancer` or `NodePort`.
2. Configure `gateway` trait, it works for `webservice`, `worker` and `task` component types. `gateway` trait must configure a domain and works only for HTTP/HTTPs protocols.
3. Case by case component configurations.
#### Expose service for `webservice` typed component
You can modify `ExposeType` to choose the way, and you should configure the `Service Ports` to listen the ports and turn on the `Expose` radio.
![webservice](../../../resources/webservice-port.jpg)
#### Add `gateway` trait
The `gateway` trait requires you have `Ingress Controller` available in your cluster. You can add this trait to expose your service and configure a domain.
![trait](../../../resources/gateway-trait-add.jpg)
As the picture shows, the `Domain` field configure your domain, please configure your DNS for domain to route to the Kubernetes cluster gateway IP.
In the `Http` section, you can configure the routing rules. For example, set `/`:`80` means the domain index page will route to the port `80`. You can configure this rule as you need.
Other component types can also be able to configure the service expose, but they're usually case by case, especially for helm charts.
### Get the service endpoint
After the application deployed with service exposed configuration, you can see a `Service Endpoint` button on the left of the `Recycle` button. You'll see the endpoint when hover your mouse there.
![service endpoint](../../../resources/service-endpoint.jpg)
### List Resources Created
If you want to learn the resources created by the applications, you can open the environment status page.
![app-resources](https://static.kubevela.net/images/1.3/app-resources.jpg)
There're three kinds of information including `Applied Resources`,`Conditions` and `Component Status`. The `Applied Resources` are all resources created by the applications.
You can also list resources from command line:
```bash
$ vela status <app_name> -n <namespace> --tree
```
### Recycle Application Instance
When you want to delete the application instance in some environment, you can click the `Recycle` button in that environment.
![pod list](../../../resources/pod-list.jpg)
It will delete the whole application instance with related resources.
> Note that recycle means delete an application, data can't be recovered automatically. Please make sure you have back up all the important data of this instance before recycle it.
### Delete Application
After all application instance were recycled, you can click `Remove` for deletion.
![delete application](../../../resources/app-delete.jpg)
As the picture shows, the `Remove` button is hidden in the application detail.
Now you have learned the basic lifecycle of an application.

60
versioned_docs/version-v1.3/platform-engineers/system-operation/managing-clusters.md
View File

@ -15,33 +15,63 @@ For connecting the ACK clusters, the platform will save some cloud info, Region,
## Manage the cluster via CLI
### vela cluster list
This command could list all clusters managed by KubeVela currently.
```bash
$ vela cluster list
CLUSTER TYPE ENDPOINT
CLUSTER ALIAS TYPE ENDPOINT ACCEPTED LABELS
local Internal - true
ask-beijing X509Certificate https://*.*.*.*:6443 true
```
### vela cluster join
This command can join new cluster into KubeVela and name it as `cluster-prod`. The joined cluster can be used in [Multi-Environment Deployment](../../end-user/policies/envbinding).
You can simply join an existing cluster into KubeVela by specifying its KubeConfig as below
```shell script
$ vela cluster join example-cluster.kubeconfig --name cluster-prod
vela cluster join <your kubeconfig path>
```
It will use the field `context.cluster` in KubeConfig as the cluster name automatically,
you can also specify the name by `--name` parameter. For example:
```shell
$ vela cluster join beijing.kubeconfig --name beijing
$ vela cluster join hangzhou-1.kubeconfig --name hangzhou-1
$ vela cluster join hangzhou-2.kubeconfig --name hangzhou-2
```
### vela cluster list
After clusters joined, you could list all clusters managed by KubeVela.
```bash
$ vela cluster list
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
local Internal - true
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true
```
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
### label your cluster
You can also give labels to your clusters, which helps you select clusters for deploying applications.
```bash
$ vela cluster labels add cluster-hangzhou-1 region=hangzhou
$ vela cluster labels add cluster-hangzhou-2 region=hangzhou
$ vela cluster list
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
local Internal - true
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true region=hangzhou
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true region=hangzhou
```
### vela cluster detach
This command can be used to detach cluster from KubeVela.
You can also detach a cluster if you do not want to use it anymore.
```shell script
$ vela cluster detach cluster-prod
$ vela cluster detach beijing
```
> It is dangerous to detach a cluster that is still in-use. But if you want to do modifications to the held cluster credential, like rotating certificates, it is possible to do so.
### vela cluster rename
This command can rename cluster managed by KubeVela.

4
versioned_docs/version-v1.3/tutorials/helm.md
View File

@ -128,7 +128,3 @@ Services:
```
At this point, Helm Chart in KubeVela is no stranger to you, go ahead and try more!
## Next step
- [Deploy Kubernetes Objects](./k8s-object)

107
versioned_docs/version-v1.3/tutorials/k8s-object.mdx
View File

@ -11,13 +11,6 @@ KubeVela supports you to render, orchestrate and deploy Kubernetes objects. The
3. Multi-env/cluster in application delivery.
4. The control loop of application deployment: Rollback, Terminate and Continue.
What's more, you can even distribute existing Kubernetes objects with KubeVela in the following scenarios:
- Copying secrets from the hub cluster into managed clusters.
- Promote deployments from canary clusters into production clusters.
- Using Kubernetes apiserver as the control plane and storing all Kubernetes objects data in external databases. Then dispatch those data into real Kuberenetes managed clusters.
## Before starting
- Prepare a Deployment+Service yaml config resource.
@ -197,104 +190,4 @@ $ vela up -f https://kubevela.io/example/applications/app-with-k8s-objects.yaml
$ vela workflow resume app-with-k8s-objects
```
## Distributed External Kubernetes Objects
> This section requires you to know how to deploy multi-cluster application with policy and workflow first. You can refer to [Multi-cluster Application Delivery](../case-studies/multi-cluster) for details.
### Refer to Existing Kubernetes Objects in Component
To use existing Kubernetes objects in the component, you need to use the `ref-objects` typed component and declare which resources you want to refer to. For example, in the following example, the secret `image-credential-to-copy` in namespace `examples` will be taken as the source object for the component. Then you can use the topology policy to dispatch it into hangzhou clusters.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-example
namespace: examples
spec:
components:
- name: image-pull-secrets
type: ref-objects
properties:
objects:
- resource: secret
name: image-credential-to-copy
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
```
### Details for the *ref-objects* typed component
The most simple way to specify resources is to directly use `resource: secret` or `resource: deployment` to describe the kind of resources. If no `name` or `labelSelector` is set, the application will try to find the resource with the same name as the component name in the application's namespace. You can also explicitly specify `name` and `namespace` for the target resource as well.
In addition to `name` and `namespace`, you can also specify the `cluster` field to let the application component refer to resources in managed clusters. You can also use the `labelSelector` to select resources in replace of finding resources by names.
In the following example, the application will select all deployments in the *hangzhou-1* cluster inside the *examples* namespace, which matches the desided labels. Then the application will copy these deployments into *hangzhou-2* cluster.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-duplicate-deployments
namespace: examples
spec:
components:
- name: duplicate-deployment
type: ref-objects
properties:
objects:
- resource: deployment
cluster: hangzhou-1
# select all deployment in the `examples` namespace in cluster `hangzhou-1` that matches the labelSelector
labelSelector:
need-duplicate: "true"
policies:
- name: topology-hangzhou-2
type: topology
properties:
clusters: ["hangzhou-2"]
```
> In some cases, you might want to restrict the scope for the application to access resources. You can set the `--ref-objects-available-scope` to `namespace` or `cluster` in KubeVela controller's bootstrap parameter, to retrict the application to be only able to refer to the resources inside the same namespace or the same cluster.
### Working with Trait
The *ref-objects* typed component can also be used together with traits. The implicit main workload is the first referenced object and trait patch will be applied on it. The following example demonstrate how to set the replica number for the referenced deployment while deploying it in hangzhou clusters.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: ref-objects-multiple-resources
namespace: examples
spec:
components:
- name: nginx-ref-multiple-resources
type: ref-objects
properties:
objects:
- resource: deployment
- resource: service
traits:
- type: scaler
properties:
replicas: 3
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
```
Congrats! Now you've learned how to deploy Kubernetes objects.
## Next step
- [Deploy Cloud Service](./consume-cloud-services)
- [Distributed External Kubernetes Objects](../end-user/components/ref-objects)

4
versioned_docs/version-v1.3/tutorials/webservice.md
View File

@ -119,7 +119,3 @@ Services:
* Refer to [webservice details](../end-user/components/references#webservice) to know usage of full fields.
* Refer to [trait reference](../end-user/traits/references) to know which traits can be used for webservice.
## Next Step
[Learn to deploy Helm Chart](./helm)

57
versioned_sidebars/version-v1.3-sidebars.json
View File

@ -67,10 +67,6 @@
{
"type": "doc",
"id": "version-v1.3/end-user/traits/sidecar"
},
{
"type": "doc",
"id": "version-v1.3/tutorials/k8s-object"
}
]
},
@ -120,6 +116,10 @@
{
"type": "doc",
"id": "version-v1.3/tutorials/k8s-object"
},
{
"type": "doc",
"id": "version-v1.3/end-user/components/ref-objects"
}
]
},
@ -149,63 +149,16 @@
{
"collapsed": true,
"type": "category",
"label": "How-to manage the applications",
"label": "General CD Features",
"items": [
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/create-application"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/bind-new-environment"
},
{
"type": "doc",
"id": "version-v1.3/tutorials/workflows"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/deploy-application"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/get-application-instance"
},
{
"type": "doc",
"id": "version-v1.3/tutorials/scaler"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/get-application-log"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/get-application-endpoint"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/view-application-resource"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/get-application-revision"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/recycle-environment"
},
{
"type": "doc",
"id": "version-v1.3/how-to/dashboard/application/delete-application"
}
]
},
{
"collapsed": true,
"type": "category",
"label": "Advanced Features",
"items": [
{
"type": "doc",
"id": "version-v1.3/end-user/workflow/component-dependency-parameter"