VMware Carvel Community Meetings, 6 Dec 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Demo: Generate an OpenAPI Schema From a ytt Data Values Schema

Description

Carvel maintainer, Cari, demos how to generate an OpenAPI Schema from a ytt data values schema (and put it in your kapp-controller Package)

Files used: https://gist.github.com/cari-lynn/89a2a9796b5aa8d8bc5fecd17c782007

A

Right carrie: are you ready to do the demo sure yeah I can? I can share my screen.

A

All right cool, so I just wanted to show a little bit about how you can use a ytt data value schema to generate an open api doc that you can use in many different ways. You can use it for documentation for your api.

A

You can use it to deploy a package in your cap controller cr, um it's a way to just declaratively state what is allowed in your configuration as inputs, so.

A

Let me just start out from the beginning: we need to talk about what a data value schema is before we can get into an open api document created from a data value schema. So on the left. Here we have a data value schema. You can tell, because it's got this annotation.

A

It's got some schema annotations in it.

A

If you're using ytt right now and using data values, you might be more familiar with a data values file which might look like this. So it's got comments in it to describe things um its players, values, um inline, so similar differences here are in a data value schema. It provides not only like the values themselves as defaults, but also type information, so, for example, for your load, balancer enabled this value is defaulted to true, but it also provides type information, so this must be a boolean.

A

So if you're a configuration author, you declare a database schema your configuration. Consumers must include that information using the correct types so like, for example,.

A

If we're going to use this, we've got uh this value file, schema file and then just like a simple template here. I'll show you what that looks like it really just outputs the data values.

A

So if we run that it should work, and it's going to be all the defaults in your schema.

A

Overlaid with the values included in your data values, file right so enabled was overwritten to false because that's allowed it's a boolean.

A

For arrays, you can declare defaults in your schema here, and any values included in your data value file will be added right. So it's additive here.

A

One of the benefits here is, if you are totally messing up- and you accidentally put something that is not a bullying here- you try to run the skin you're, going to see an error that actually prevents this from being templated, so it'll catch things before you deploy them.

A

All right so we're going to totally forget about this values file um and only going to use the schema, because, really that's all that's needed to create an open api document.

A

So these fields here.

A

They can create open api keys, so, for example, this can provide us documentation when reading your schema. So you know what this means, but it also will include a description key in your open api schema that has this string.

A

um The schema nullable will allow this value to be either a string or it can be null and you'll see that reflected in your open api schema.

A

So like, let's see what that looks like all right, we're going to take our schema file and we're going to run it through this command in ytt data value, schema, inspect dash, o for output, and it's going to be an open api, v3 format and we're just going to write it to a file.

A

Alright, so this was created.

A

So this is what the open api document looks like that y2 just made from your data values schema and you can see everything under component schemas data values. Everything in here is the actual schema for your um everything above that is, uh like header information. That's used by, uh like any other third-party open api tools that you need. This just makes this valid open api. So, if you wanted to, like, I don't know, generate uh html or documentation based on this schema, then you'll know it's in open api, 3.0 format.

A

And then just you had to highlight this like, for example, load balance without enabled it's a boolean and it defaults to true. You can see that right here or sorry right here, yep, so it creates all of the type information. That's in your data value schema and any comments has descriptions right um right. So this can be used in a cap controller package.

A

That's one of the use cases that it it supports, and.

A

You might do that by having a package custom resource as a ytt template, for example, and say you want to put your open api schema in this open api v3 field.

A

This acts like documentation for what values are allowed in your package. That, for example, like this package, will get your configuration from an image and then template it using ytt.

A

uh You can add values here, and you can read this open api v3 section to know what values you can put in your templates here.

A

um So what we got here is just this key. Let me show you the command. We're going to run. Make this make a little bit more sense.

A

So we're going to just template this package and we're going to include our open api document as a data values file and we're going to name it open api and include that file as that data value.

A

So that's what this is here. It's going to take that open api key and it's going to get the component schema's data values out of it right. So, if you remember that's everything down here,.

A

um And then this is necessary because uh when reading from the command line, it's going to read it in as a string, so we just need to convert that into yaml so that we can access this field.

A

All right, so, let's template this and see what we get.

A

Yep we get our package out and it's got all of our schema here.

A

So then we can deploy this and use it for uh our configuration.

A

um So that's really like the main use case that I wanted to go over today. The open api schema can be used for other things as well, um but yeah I'm happy to answer any questions about that.