cue-gen

command
v1.15.0-bzc-beta.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 20, 2022 License: Apache-2.0 Imports: 35 Imported by: 0

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:

  1. Convert .proto files to CUE files
  2. Validate the consistency of the CUE defintions
  3. 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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL