Generating OpenAPI Schema

For any capabilities installed via Definition Objects, KubeVela will automatically generate OpenAPI v3 JSON schema based on its parameter list, and store it in a ConfigMap in the same namespace with the definition object.

The default KubeVela system namespace is vela-system, the built-in capabilities and schemas are laid there.

KubeVela support generate different versions of Component/Trait Definition. Thus, we use ConfigMap to store the parameter information of different versions of Definition. This ConfigMap will have a common label definition.oam.dev=schema, the default ConfigMap without a version suffix will point to the latest version, you can find easily by:

  1. kubectl get configmap -n vela-system -l definition.oam.dev=schema
  1. NAME                   DATA     AGE
  2. schema-ingress         1        46m
  3. schema-scaler          1        50m
  4. schema-webservice      1        2m26s
  5. schema-webservice-v1   1        40s
  6. schema-worker          1        1m45s 
  7. schema-worker-v1       1        55s
  8. schema-worker-v2       1        20s

For the sack of convenience, we also specify a unified label for the ConfigMap which stores the parameter information of the same Definition. And we can list the ConfigMap which stores the parameter of the same Definition by specifying the label like definition.oam.dev/name=definitionName, where the definitionName is the specific name of your component or trait.

  1. kubectl get configmap -l definition.oam.dev/name=worker
  1. NAME                   DATA     AGE
  2. schema-worker          1        1m50s
  3. schema-worker-v1       1        1m
  4. schema-worker-v2       1        25s

The ConfigMap name is in the format of schema-<your-definition-name>, and the data key is openapi-v3-json-schema.

For example, we can use the following command to get the JSON schema of webservice.

  1. kubectl get configmap schema-webservice -n vela-system -o yaml
  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: schema-webservice
  5.   namespace: vela-system
  6. data:
  7.   openapi-v3-json-schema: '{"properties":{"cmd":{"description":"Commands to run in
  8.     the container","items":{"type":"string"},"title":"cmd","type":"array"},"cpu":{"description":"Number
  9.     of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core)","title":"cpu","type":"string"},"env":{"description":"Define
  10.     arguments by using environment variables","items":{"properties":{"name":{"description":"Environment
  11.     variable name","title":"name","type":"string"},"value":{"description":"The value
  12.     of the environment variable","title":"value","type":"string"},"valueFrom":{"description":"Specifies
  13.     a source the value of this var should come from","properties":{"secretKeyRef":{"description":"Selects
  14.     a key of a secret in the pod''s namespace","properties":{"key":{"description":"The
  15.     key of the secret to select from. Must be a valid secret key","title":"key","type":"string"},"name":{"description":"The
  16.     name of the secret in the pod''s namespace to select from","title":"name","type":"string"}},"required":["name","key"],"title":"secretKeyRef","type":"object"}},"required":["secretKeyRef"],"title":"valueFrom","type":"object"}},"required":["name"],"type":"object"},"title":"env","type":"array"},"image":{"description":"Which
  17.     image would you like to use for your service","title":"image","type":"string"},"port":{"default":80,"description":"Which
  18.     port do you want customer traffic sent to","title":"port","type":"integer"}},"required":["image","port"],"type":"object"}'

Specifically, this schema is generated based on parameter section in capability definition:

  • For CUE based definition: the parameter is a keyword in CUE template.
  • For Terraform based definition: the variable is the keyword in TF template.

Refer to UX of Definition

Last updated on Feb 9, 2023 by dependabot[bot]