github.com/oam-dev/kubevela@v1.9.11/design/vela-cli/sdk_generating.md (about)

     1  # SDK Generating
     2  
     3  # Introduce
     4  
     5  This proposal introduces a framework which can generate KubeVela multiple language SDKs from scaffolds and the real
     6  world X-Definitions.
     7  
     8  # Background
     9  
    10  As KubeVela designs for separation of concerns, there are two roles of user: platform team and end user. They are
    11  dealing with Application in different ways.
    12  
    13  ![image](../resources/separation-of-roles.png)
    14  
    15  ### For platform team
    16  
    17  When platform team users typically build a platform. The platform allow end user to pass parameters to
    18  component/trait/policy/workflow, then the platform assemble an Application automatically using the parameters.
    19  
    20  Unfortunately, due to the extensibility of KubeVela X-Definition system, the property structure of different component (
    21  also for traits, workflow steps, policies) varies. In the source code, we use a `map[string]interface{}` to accept all
    22  kinds of properties. The unstructured code make it hard examine, modify, insert values of nested properties.
    23  
    24  Before KubeVela provide the SDK, the problem is mainly solved by providing OpenAPI schema to frontend and generate the
    25  form dynamically. There is also an enhancement scheme: ui-schema. After filling the form, the JSON returned by frontend
    26  is already satisfied the specification of X-Definition properties. This is how VelaUX works when assembling Application.
    27  
    28  ### For end user
    29  
    30  Basically there are two ways for end user to use Application:
    31  
    32  1. Through dashboard provided by platform team like VelaUX. The data is kept by the internal platform. In this pattern
    33     user's behavior can be better guided with typed form and UI indications.
    34  2. Storing Application as part of the codebase. Then through some way (e.g. GitOps) the application is applied to
    35     cluster.
    36  
    37  ### Goals & Non-Goals
    38  
    39  Goals include the following:
    40  
    41  1. Provide a framework to generate SDK for different languages. Definition can be discovered from
    42      - Local directory
    43      - KubeVela control plane cluster
    44  2. Provide a Go SDK as one of the first core SDK to proof of concept.
    45  3. The SDK must provide functions to meet the following scenarios:
    46      - Be able to do CRUD on OAM concepts including Component/Trait/Workflow/Policy.
    47      - Be able to generate application YAML and directly apply to KubeVela control plane cluster.
    48  
    49  Non-goals include the following:
    50  
    51  1. We hope to provide SDK for as many languages as we can, but it's not possible to provide sdks for all languages.
    52     We'll just target the popular languages such as Go, Typescript, Java, Python, PHP, and etc.
    53  
    54  # Proposal
    55  
    56  ## Benefits
    57  
    58  In the aforementioned ways of using Application, there are some issues for both roles.
    59  
    60  ### For platform team
    61  
    62  There are some scenarios which use JSON data passed from frontend is not enough:
    63  
    64  1. Platform is responsible for some examination and modification on user's application:
    65      1. Adding some traits and policies which is taken care of by platform team. (e.g. observability)
    66      2. Execute some check which can't be done with OpenAPI schema and ui-schema. (e.g. call other services to access
    67         needed data)
    68  2. Platform want to execute some offline batch jobs. For example, add observability trait to existing Applications
    69  
    70  In these scenarios, it's [painful](#3606) to develop with `map[string]interface{}`. With SDK, platform team can benefits
    71  from the typed X-Definition properties and builds, examines, modifies application more easily.
    72  
    73  ### For end user
    74  
    75  If user is writing Application YAML, they have to refer to the doc. Although we have done some toolchain on this topic
    76  like `vela show`, a typed SDK also provide a possibility for end user to code Application in different languages.
    77  
    78  ## Design and tools
    79  
    80  Thanks to the OpenAPI schema and related tool [openapi-generator](https://github.com/OpenAPITools/openapi-generator) in
    81  ecosystem, we can re-use the almost ready templates to generate code. The whole generation process is shown below.
    82  
    83  ![image](../resources/sdk-gen-process.png)
    84  
    85  **Step0**: The scaffold is written to destination if `--init` is specified. (omitted in pic)
    86  
    87  **Step1**: Generate OpenAPI schema from CUE. The generated schema may not fully prepared as input of openapi-generator
    88  and it will be correct and adjust.
    89  
    90  **Step2**: Call openapi-generator to generate SDK. After that some modification will be applied to make SDK API suited
    91  for KubeVela user.
    92  
    93  ## Examples
    94  
    95  This command requires `docker` in PATH as we'll run openapi-generator in docker.
    96  
    97  ```shell
    98  # Initialize the SDK, generate API from all definitions, 
    99  vela def gen-api --init -f /path/to/def/dir -o /path/to/sdk --language go
   100  
   101  # Incrementally generate API from definitions
   102  vela def gen-api -f /path/to/def/dir -o /path/to/sdk --language go
   103  ```
   104  
   105  ## Future work
   106  
   107  This PR only provide a framework on generating SDK and there are lots of jobs to do to provide
   108  user-friendly SDKs in multiple languages.
   109  
   110  ### For SDK generating
   111  
   112  1. Provide SDK in other languages. This is a LFX mentorship: #5365
   113  2. Allow user to customize the templates in Step2.
   114  
   115  ### For Golang SDK
   116  
   117  1. The default value of properties is not set in apis. Although there is a `default` field in OpenAPI schema, it's not
   118     sed in generated code. We can set the default value in code.
   119  2. Parameter validation using CUE. Sometimes the `parameter` field in CUE have more restrictions. We can use CUE to
   120     validate the parameters. (e.g. `parameter: { a : >=0 }`). For golang there is
   121     a [package](https://pkg.go.dev/cuelang.org/go/encoding/gocode/gocodec) that can help.
   122  3. Validate if the trait type is suited to be attached to the component. For example, `K8s-object` can only
   123     accept `labels` and `annotation` trait.
   124  
   125  ## Known Issues
   126  
   127  There are some problems when generating:
   128  
   129  1. `apply-terraform-provider` workflow step. Parameter are like below will cause the problem. Related
   130     issue: https://github.com/cue-lang/cue/issues/2259
   131  
   132  ```cue
   133  basic: { info: string }
   134  #A:{ 
   135    info
   136    a: string 
   137  }
   138  #B:{ 
   139    info
   140    b: string 
   141  }
   142  parameter: *#A|#B
   143  ```
   144  
   145  2. `label` and `annotation` trait. openapi-generator doesn't support top-level schema to be a map. The two traits'
   146     properties is actually just `map[string]string` so it's easy to build it without using SDK.