README
¶
cue-gen
cue-gen is a tool that generates OpenAPI schema and Kubernetes CustomResourceDefinition(CRD) configurations. It relies on cuelang packages to translate
Protobuf definitions to OpenAPI schemas, specifically
structural schemas in CRDs.
Usage
cue-gen can be used to generate OpenAPI schemas for each package respectively, OpenAPI schemas of all packages in one file, and CRDs in a file.
Generate OpenAPI schemas
To generate the OpenAPI schemas, configurations need to be specified in a JSON or YAML file. Use cue-gen -help to find out the configuration options.
Generate for each package respectively
directories need to be specified in the configuration file for packages that need OpenAPI schemas. Use cue-gen -f={PATH_TO_CONFIG_FILE} -paths={PATH_TO_PROTO_IMPORTS}
to get the OpenAPI schema file(s) in each package.
Generate for all packages in one file
In addition to directories field in the configuration file, the all field needs to be specified. Use cue-gen -all -f={PATH_TO_CONFIG_FILE} -paths={PATH_TO_PROTO_IMPORTS}
to get the OpenAPI schemas in a single file.
Generate CRDs
Configurations on how CRDs are generated are specified in the comments of the protos that map to the CRDs. For example, to generate CRD for DestinationRule, the following configuration
needs to be added to the comment of the DestinationRule proto.
// <!-- crd generation tags
// +cue-gen:DestinationRule:groupName:networking.istio.io
// +cue-gen:DestinationRule:version:v1alpha3
// +cue-gen:DestinationRule:storageVersion
// +cue-gen:DestinationRule:annotations:helm.sh/resource-policy=keep
// +cue-gen:DestinationRule:labels:app=istio-pilot,chart=istio,heritage=Tiller,release=istio
// +cue-gen:DestinationRule:subresource:status
// +cue-gen:DestinationRule:scope:Namespaced
// +cue-gen:DestinationRule:resource:categories=istio-io,networking-istio-io,shortNames=dr
// +cue-gen:DestinationRule:printerColumn:name=Host,type=string,JSONPath=.spec.host,description="The name of a service from the service registry"
// +cue-gen:DestinationRule:printerColumn:name=Age,type=date,JSONPath=.metadata.creationTimestamp,description="CreationTimestamp is a timestamp
// representing the server time when this object was created. It is not guaranteed to be set in happens-before order across separate operations.
// Clients may not set this value. It is represented in RFC3339 form and is in UTC.
// Populated by the system. Read-only. Null for lists. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
// -->
Use cue-gen -crd -f={PATH_TO_CONFIG_FILE} -paths={PATH_TO_PROTO_IMPORTS} to get the CRD file at {PWD}/kubernetes/customresourcedefinitions.gen.yaml.
Documentation
¶
Overview ¶
genoapi generates OpenAPI files from .proto definitions and other sources of CUE constraints. It requires the definition of a configuration file that is specified at the Go or CUE module root for which one wishes to generate the OpenAPI files.
Generation adopts the Proto <-> JSON mappings conventions. Most notably, field names are converted to JSON names.
Generation involves the following steps:
- Convert .proto files to CUE files
- Validate the consistency of the CUE defintions
- Convert CUE files to self-contained OpenAPI files.
Each of which is documented in more detail below.
1. Converting Proto to CUE
genoapi generates all .proto files using a single builder. As the Istio OpenAPI files are self-contained, this is not strictly necessary, but it allows for better checking and works better if one wants to generate the intermediate CUE results for evaluation.
Field names are mapped using JSON naming.
Protobuf definitions may contain (cue.val) and (cue.opt) options to annotate fields with constraints.
Caveats:
- It is assumed that the input .proto files are valid and compile with protoc. The conversion may ignore errors if files are invalid.
- CUE package names share the same naming conventions as Go packages. CUE requires the go_package option to exist and be well-defined. Note that some of the gogoproto go_package definition are illformed. Be sure to use the original .proto files for the google protobuf types.
2. Combine and validate generated CUE
CUE files that reside in the same directory as a .proto file and that have the same package name as the corresponding Go package are automatically merged into the generated CUE definitions. Merging happens based on the generated CUE names.
The combines CUE definitions are validated for consistency before proceeding to the next step.
3. Converting CUE to OpenAPI
In this step a self-contained OpenAPI definition is generated for each directory containing proto definitions. Files are made self-contained by including a schema definition for each imported type within the OpenAPI spec itself. To avoid name collissions, types are, by convention, prefixed with their proto package name.
Possible extensions to the generation pipeline ¶
The generation pipeline can be augmented by injecting CUE from other sources before step 2. As combining CUE sources is a commutative operation, order of injection does not matter and there is no need for the user to be explicit about any order or injection points.
Examples of other possible CUE sources are: - constraints extracted from Go code
Source Files