Resource Adoption

    By default, when KubeVela application tries to dispatch (create or update) one resource, it will first check if this resource belongs to itself. This check is done by comparing the label values of & app.oam.dev/namespace and see whether they are equal to the application’s name & namespace.

    If this resource does not belongs to the application itself (belongs to no one or some other application), the application will stop the dispatch operation and report an error. This mechanism is designed to prevent unintended edits to resources managed by other operators or systems.

    If the resource is currently managed by other applications, you can refer to shared-resource policy and read more about sharing resources across multiple applications.

    If the resource is managed by no one, to allow KubeVela application to manage the resource, you can leverage the read-only policy or take-over policy to enforce resource adoption on these resources.

    With read-only policy, you can select resources that could be adopted by the current application. For example, in the below application, Deployment typed resources are treated as read-only resources and are able to be adopted by the given application.

    The read-only policy allows application to read the selected resources but will skip all edits to the target resource. Error will be reported if the target resource does not exist.

    The target resource will NOT be attached with the application’s label. It is possible for multiple applications to use the same resource with read-only policy concurrently. The deletion of the application will also skip the recycle process of the target resources.

    Although the resources selected in the read-only policy will not be editable through application, both health check and resource topology graph can work normally. Therefore, you can use KubeVela application with read-only policy to build “monitoring group” for underlying resources and leverage tools such as vela top or velaux to observe them, without any modification.

    practice

    1. First creat the nginx deployment.
    1. kubectl create deploy nginx --image=nginx
    1. Deploy the application with read-only policy.
    1. cat <<EOF | vela up -f -
    2. apiVersion: core.oam.dev/v1beta1
    3. kind: Application
    4. metadata:
    5.   name: read-only
    6. spec:
    7.   components:
    8.     - name: nginx
    9.       type: webservice
    10.       properties:
    11.         image: nginx
    12.   policies:
    13.     - type: read-only
    14.       name: read-only
    15.       properties:
    16.         rules:
    17.           - selector:
    18.               resourceTypes: ["Deployment"]
    19. EOF
    1. Check the running status of the application.
    1. vela status read-only

    1. Use vela top to see the resource topology of the application.

    2. Use velaux to see the resource topology graph of the application. read-only-velaux

    In the case you not only want KubeVela application to observe underlying resource but also want the application to be able to edit them, you can use the take-over policy in replace of the read-only policy.

    1. apiVersion: core.oam.dev/v1beta1
    2. kind: Application
    3. metadata:
    4.   name: take-over
    5. spec:
    6.   components:
    7.     - name: nginx-take-over
    8.       type: k8s-objects
    9.       properties:
    10.         objects:
    11.           - apiVersion: apps/v1
    12.             kind: Deployment
    13.             metadata:
    14.               name: nginx
    15.       traits:
    16.         - type: scaler
    17.           properties:
    18.             replicas: 3
    19.   policies:
    20.     - type: take-over
    21.       name: take-over
    22.       properties:
    23.         rules:
    24.           - selector:
    25.               resourceTypes: ["Deployment"]

    After the resource is taken over by the application, the application will control the upgrades and deletion of the target resource. Therefore, differ from read-only policy, each resource can only be managed by one application with take-over policy.

    The take-over policy is helpful when you want to let the application to take the complete control for the given resources.

    practice

    1. First create the nginx deployment
    1. kubectl create deploy nginx --image=nginx
    1. Deploy the application with take-over policy.
    1. cat <<EOF | vela up -f -
    2. apiVersion: core.oam.dev/v1beta1
    3. kind: Application
    4. metadata:
    5.   name: take-over
    6. spec:
    7.   components:
    8.     - name: nginx-take-over
    9.       type: k8s-objects
    10.       properties:
    11.         objects:
    12.           - apiVersion: apps/v1
    13.             kind: Deployment
    14.             metadata:
    15.               name: nginx
    16.       traits:
    17.         - type: scaler
    18.           properties:
    19.             replicas: 3
    20.   policies:
    21.     - type: take-over
    22.       name: take-over
    23.       properties:
    24.         rules:
    25.           - selector:
    26.               resourceTypes: ["Deployment"]
    27. EOF
    1. Check the application running status.
    1. vela status take-over

    The read-only policy and take-over policy provide a way for users to directly adopt resources within KubeVela application api. If you prefer directly build KubeVela application by existing resources from scratch, you can use the vela adopt CLI command.

    By providing a list of native Kubernetes resources, vela adopt command can help you automatically adopt those resources in an application. You can follow the below procedure to try it out.

    1. Create some resources for adoption.
    2. kubectl create service clusterip example --tcp=80:80
    3. kubectl create configmap example
    4. kubectl create secret generic example
    1. vela adopt deployment/example service/example configmap/example secret/example

    expected output

    ```yaml apiVersion: core.oam.dev/v1beta1 kind: Application metadata: creationTimestamp: null labels: app.oam.dev/adopt: native name: example namespace: default spec: components: - name: example.Deployment.example properties: objects: - apiVersion: apps/v1 kind: Deployment metadata: name: example namespace: default spec: progressDeadlineSeconds: 600 replicas: 1 revisionHistoryLimit: 10 selector: matchLabels: app: example strategy: rollingUpdate: maxSurge: 25% maxUnavailable: 25% type: RollingUpdate template: metadata: creationTimestamp: null labels: app: example spec: containers: - image: nginx imagePullPolicy: Always name: nginx resources: terminationMessagePath: /dev/termination-log terminationMessagePolicy: File dnsPolicy: ClusterFirst restartPolicy: Always schedulerName: default-scheduler securityContext: terminationGracePeriodSeconds: 30 type: k8s-objects - name: example.Service.example properties: objects: - apiVersion: v1 kind: Service metadata: name: example namespace: default spec: clusterIP: 10.43.65.46 clusterIPs: - 10.43.65.46 internalTrafficPolicy: Cluster ipFamilies: - IPv4 ipFamilyPolicy: SingleStack ports: - name: 80-80 port: 80 protocol: TCP targetPort: 80 selector: app: example sessionAffinity: None type: ClusterIP type: k8s-objects - name: example.config properties: objects: - apiVersion: v1 kind: ConfigMap metadata: name: example namespace: default - apiVersion: v1 kind: Secret metadata: name: example namespace: default type: k8s-objects policies: - name: read-only properties: rules: - selector: componentNames: - example.Deployment.example - example.Service.example - example.config type: read-only status: ```

    By default, the application first embeds all the given resources in its components. Then it attaches the read-only policy. You can edit the returned configuration and make your own adoption application. Or you can directly apply this application with the --apply arg.

    You can also set the application name you would like to use.

    1. vela adopt deployment/example service/example configmap/example secret/example --apply --app-name=adopt-example

    Now if you can use vela status and vela status -t -d command show the status the applied application.

    1. vela status adopt-example

    expected output

    1. About:                                
    3.   Name:         adopt-example                 
    4.   Namespace:    default                       
    5.   Created at:   2023-01-11 14:21:21 +0800 CST
    6.   Status:       running                                                                                                                                                       
    8. Workflow:                                                                                                                                                                     
    10.   mode: DAG-DAG                                                                                                                                                               
    11.   finished: true                                                                                                                                                              
    12.   Suspend: false                                                                                                                                                              
    13.   Terminated: false
    14.   Steps
    15.   - id: 8d8capzw7e
    16.     name: adopt-example.Deployment.example
    17.     type: apply-component
    18.     phase: succeeded 
    19.   - id: 6u6c6ai1gu
    20.     name: adopt-example.Service.example
    21.     type: apply-component
    22.     phase: succeeded 
    23.   - id: r847uymujz
    24.     name: adopt-example.config
    25.     type: apply-component
    26.     phase: succeeded 
    28. Services:
    30.   - Name: adopt-example.Deployment.example   
    31.     Cluster: local  Namespace: default
    32.     Type: k8s-objects
    33.     Healthy 
    34.     No trait applied
    36.   - Name: adopt-example.Service.example  
    37.     Cluster: local  Namespace: default
    38.     Type: k8s-objects
    39.     Healthy 
    40.     No trait applied
    42.   - Name: adopt-example.config  
    43.     Cluster: local  Namespace: default
    44.     Type: k8s-objects
    45.     Healthy 
    46.     No trait applied
    1. vela status adopt-example -t -d
    1. CLUSTER       NAMESPACE     RESOURCE           STATUS    APPLY_TIME          DETAIL
    2. local     ─── default   ─┬─ ConfigMap/example  updated   2023-01-11 14:15:34 Data: 0  Age: 6m1s
    3.                          ├─ Secret/example     updated   2023-01-11 14:15:52 Type: Opaque  Data: 0  Age: 5m43s
    4.                          ├─ Service/example    updated   2023-01-11 14:12:00 Type: ClusterIP  Cluster-IP: 10.43.65.46  External-IP: <none>  Port(s): 80/TCP  Age: 9m35s
    5.                          └─ Deployment/example updated   2023-01-11 14:11:06 Ready: 1/1  Up-to-date: 1  Available: 1  Age: 10m

    The read-only only allows the application to observe resources, but disallow any edits to it. If you want to make modifications you can use the --mode=take-over to use the take-over policy in the adoption application.

    1. For example, you can firstly deploy a mysql instance through helm.
    1. helm repo add bitnami https://charts.bitnami.com/bitnami
    2. helm repo update
    3. helm install mysql bitnami/mysql
    1. You can validate the installation through helm ls.
    1. helm ls
    1. NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
    2. mysql   default         1               2023-01-11 14:34:36.653778 +0800 CST    deployed        mysql-9.4.6     8.0.31
    1. Run vela adopt command to adopt resources from existing release. Similar to native resource adoption, you can get a KubeVela application with read-only policy.
    1. vela adopt helm --type helm

    expected output

    1. You can similarly use --apply parameter to apply the application into cluster and use --mode=take-over to allow modifications by enforcing take-over policy. In addition to that, if you want to completely adopt resources in helm chart into KubeVela application and disable the management of that helm chart (prevent multiple sources), you can add --recycle flag to remove the helm release secret after the application has entered running status.
    1. vela adopt mysql --type helm --mode take-over --apply --recycle
    1. resources adopted in app default/mysql
    2. successfully clean up old helm release
    1. You can check the application status using vela status and vela status -t -d.
    1. vela status mysql

    expected output

    1. About:
    3.   Name:         mysql                        
    4.   Namespace:    default                      
    5.   Created at:   2023-01-11 14:40:16 +0800 CST
    6.   Status:       running                      
    8. Workflow:
    10.   mode: DAG-DAG
    11.   finished: true
    12.   Suspend: false
    13.   Terminated: false
    15.   - id: orq8dnqbyv
    16.     name: mysql.StatefulSet.mysql
    17.     type: apply-component
    18.   - id: k5kwoc49jv
    19.     name: mysql.Service.mysql-headless
    20.     type: apply-component
    21.     phase: succeeded 
    22.   - id: p5qe1drkoh
    23.     name: mysql.Service.mysql
    24.     type: apply-component
    25.     phase: succeeded 
    26.   - id: odicbhtf9a
    27.     name: mysql.config
    28.     type: apply-component
    29.     phase: succeeded 
    30.   - id: o36adyqqal
    31.     name: mysql.sa
    32.     type: apply-component
    33.     phase: succeeded 
    35. Services:
    37.   - Name: mysql.StatefulSet.mysql  
    38.     Cluster: local  Namespace: default
    39.     Type: k8s-objects
    40.     Healthy 
    41.     No trait applied
    43.   - Name: mysql.Service.mysql-headless  
    44.     Cluster: local  Namespace: default
    45.     Type: k8s-objects
    46.     Healthy 
    47.     No trait applied
    49.   - Name: mysql.Service.mysql  
    50.     Cluster: local  Namespace: default
    51.     Type: k8s-objects
    52.     Healthy 
    53.     No trait applied
    55.   - Name: mysql.config  
    56.     Cluster: local  Namespace: default
    57.     Type: k8s-objects
    58.     Healthy 
    59.     No trait applied
    61.   - Name: mysql.sa  
    62.     Cluster: local  Namespace: default
    63.     Type: k8s-objects
    64.     Healthy 
    65.     No trait applied
    1. vela status mysql -t -d
    1. CLUSTER       NAMESPACE     RESOURCE               STATUS    APPLY_TIME          DETAIL
    2. local     ─── default   ─┬─ ConfigMap/mysql        updated   2023-01-11 14:40:16 Data: 1  Age: 7m41s
    3.                          ├─ Secret/mysql           updated   2023-01-11 14:40:16 Type: Opaque  Data: 2  Age: 7m41s
    4.                          ├─ Service/mysql          updated   2023-01-11 14:40:16 Type: ClusterIP  Cluster-IP: 10.43.154.7  External-IP: <none>  Port(s): 3306/TCP  Age: 7m41s
    5.                          ├─ Service/mysql-headless updated   2023-01-11 14:40:16 Type: ClusterIP  Cluster-IP: None  External-IP: <none>  Port(s): 3306/TCP  Age: 7m41s
    6.                          └─ StatefulSet/mysql      updated   2023-01-11 14:40:16 Ready: 1/1  Age: 7m41s
    1. If you run helm ls you will not be able to find the original mysql helm release since the records have been recycled.
    1. helm ls
    1. NAME    NAMESPACE       REVISION        UPDATED STATUS  CHART   APP VERSION

    tip

    There are multiple ways to use KubeVela together with Helm.

    If you want to use Helm to control the release process of charts and use KubeVela to monitor those resources, you can use the default mode (read-only) and do not recycle the helm release secret. In this case, you will be able to monitor resources dispatched by Helm Chart with KubeVela tools or eco-system (like viewing on Grafana).

    If you want to migrate existing resources from Helm Chart to KubeVela application, you can use the take-over mode and use the --apply flag to recycle helm release records.

    By default, vela adopt will take resources from given source (native resource list or helm chart) and group them into different components. For resources like Deployments or Statefulsets, the original spec will be reserved. For other resources like ConfigMap or Secret, the data will not be recorded in the adoption application (which means the application does not care for the content in them). For special resources (CustomResourceDefinition), the garbage-collect and apply-once policy will be additionally attached in the application.

    The conversion from resources into application is achieved by using the CUE template. You can refer to to see the default template.

    You can also build your own adoption rule using CUE and add --adopt-template to vela adopt command.

    1. For example, let’s create an example deployment.
    1. kubectl create deploy custom-adopt --image=nginx
    1. Create a file named my-adopt-rule.cue.

    This customized adoption rule will automatically recognize deployment resources and convert it into KubeVela application’s webservice component. It can intelligently detect the replicas number of the given deployment and attach a scaler trait to the component.

    1. Run vela adopt deployment/custom-adopt --adopt-template=my-adopt-rule.cue. You can see the converted application as
    1. apiVersion: core.oam.dev/v1beta1
    2. kind: Application
    3. metadata:
    4.   creationTimestamp: null
    5.   labels:
    6.     app.oam.dev/adopt: native
    7.   name: custom-adopt
    8. spec:
    9.   components:
    10.   - name: custom-adopt
    11.     properties:
    12.       image: nginx
    13.     traits:
    14.     - properties:
    15.         replicas: 1
    16.       type: scaler
    17.     type: webservice
    18.   policies:
    19.   - name: read-only
    20.     properties:
    21.       rules:
    22.       - selector:
    23.           componentNames:
    24.           - custom-adopt
    25.     type: read-only

    With this capability, you can make your own rules for building application from existing resources or helm charts.