VMware Carvel Community Meetings, 19 Jul 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Carvel kapp-controller Demo - Kubernetes Package Management API

Description

At our Community Meeting on July 15, Carvel maintainers, Eli Wrenn and Daniel Helfand, walked through the latest release of kapp-controller.

You can find more details about this release within the release notes: https://github.com/vmware-tanzu/carvel-kapp-controller/releases/tag/v0.20.0

A

uh So next we have the package management, api intro, the demo, for the release. Regarding cap controller, I will stop sharing my screen.

B

Cool um so yeah up to this point, our discussions about packaging stuff have been very hand wavy and descriptive. Instead of concrete with actual examples, um so dan and I threw together a little demo to hopefully solidify everyone's understanding of how it works, what it's doing and hopefully show some of the value in it.

B

We split it up into sort of two sections where I'll be showing the package author side so I'll, be writing a package publishing it in a package repository and putting that into an oci registry, and then daniel will sort of take the role of a packaged consumer who wants to install this package onto their cluster.

B

So I will start sharing my screen and get to package authoring.

B

Can everyone see? Is the font size good? Should I bump it up?

B

You could honestly bump it just a little bigger, okay.

C

How's that that's lovely science.

B

Okay cool so to orient ourselves since I'm taking the role of a package author, I would be somebody that has an application that I want to publish in a way that anybody that wants to install my application doesn't need to know any of the intimate details about what kind of templates I'm using like where specific versions of my manifest are stored.

B

What specific deployment tool to use! So all that to say I'm starting with an app and it's pretty simple: it's got a service and a deployment and just prints out a little hello message when somebody connects to it from or connects to the service, and then it has some configurable values. So you can configure what port the service will listen on and then you can also configure part of the hello message that will be displayed to users.

B

So, in order to package this up, I need to first create, what's called the package. Contents bundle. um So for this we're using an image package bundle, it will store our application configuration and any references to images used by that application. In this case the kate, simple, app docker image.

B

So I'll start by sort of creating that directory structure for that file or directory or bundle um and then moving over my manifests to that directory.

B

So now, if we take a look at package contents, you can see, we've got this config directory where our config is stored, and then, since this is an image package bundle, we also need some of the image package metadata files in the dot image package directory, so I'll make that and also populate them. And to do this we want to create.

B

We want to populate the images yaml with references to images used by our application config, so we'll run the config directory through k, build which will pull out any image references present in the deployments or any other resources it finds, and it will output this image lock file into the images.yaml so running that we can then take a look at what that output looks like.

B

And you can see here, we have a record that this bundle references, the kate, simple, app docker image. So now, whenever somebody moves this bundle around image package will be smart enough to also copy any docker images. It relies on as well and now that all of that is where it needs to be. We can just push this up into our registry.

B

Is demo app version 1.0.0.

B

So now that our application is packaged up into this contents bundle and stored in a registry, we now need to create the crs that instruct cap controller, where to fetch manifest from how to template them and how to install them so that users don't need to know any of that information.

B

So we'll start with creating, what's called a package metadata file at metadata.yaml, and this files just acts as sort of a high-level view of what the package is.

B

None of this information is versioned, it's sort of like a github readme, in that it just lays out what the package is, what it does like some descriptions and categories you could find it under and for this demo we'll be calling our package demoapp.carville.dev, it's good to sort of name space with a fully qualified name, so that if two people publish their own versions of the same package like prometheus, it's distinguished and there's no collisions.

B

As you can see, we've got a display name, so this is a more human-friendly name for the package and then some high-level descriptions in the categories.

B

There are also some other metadata fields in the docs that can be filled out, like logos, maintainers, etc, just for more info, and once we have that we can create our actual the other cr, which is our package definition.

B

Our versioned package definition so.

B

That is what this looks like, so we've got our name, which is just a combination of the package name and what which version? The specific definition is for.

B

Some release notes and then a value schema, and it's important to note that this is for informational purposes only. So this is a way for package authors to convey to consumers. What are the configurable values you can pass into this package.

B

It can be consumed by like uis in order to create a richer experience with configuration, input or just consumed in this state by people using cube, ctl.

B

And as we saw earlier, we've got two values that can be configured a service port, which is an integer and defaults to 80 and a hello message, which is a string in defaults to stranger.

B

If you did want your schema to actually do validations, you would have to include it down here in the templating steps as either like a ytt schema or a json schema for helm, templating steps.

B

And then, as we get down to the actual package definition where it instructs cap controller like where to fetch the configuration from so here we're using that package contents bundle. We just pushed that stores. All of our configuration we're telling cap controller that you then need to template it using ytt, which will render all of our manifests run it through k, build to sort of replace any image references that may have changed throughout the relocation process and then deploy it. Finally, using cap.

B

So with this definition, users won't have to know about any of this. They can just create a cr as you'll see in a bit.

B

So once you write that we now need to move this package into a package repository, which is a image package bundle again, which stores a collection of different packages.

B

So we'll start this similar process as before, where we'll create all the directories, we need the dot image package directory again to store some metadata, as well as this packages directory with our package name.

B

And then we can look at what the final looks like here and our recommendation is for each package. You have stored in the repository you give it its own directory and then put any version versions or metadata into that directory.

B

So sticking to that, we will copy over those two files that we just made: let's actually move them into the demo app carville.dev directory, and if we look again, we can see now we've got version one of that package, as well as the metadata stored in the repository now.

B

We also need to make sure that the package repository is able to reference all the package content bundles that we previously created so that the fetch stages of the package are able to succeed so we'll again create this images lock file inside of the package repository, and if we look at this again, we see that we now have a reference to that demo. App package contents bundle that we had created at the start of the demo and then finally, we can push this repository to an oci registry.

B

And we can then share this digest with anybody that would like to consume our packages.

B

In this case, daniel.

C

So, as eli has kind of touched on in the first portion of this demo, what cap controller allows us to do is basically capture not only the configuration, the associated images at every level that you're sort of deploying here right, like we resolve the container images in our manifest to their digest format and the image package bundles themselves for packages are resolved to this digest format.

C

We have a lot of stability in the way that we're able to take the configuration, the images and the process by which we would deploy out to a kubernetes cluster through a lot of the concepts that we've introduced through cap controller and through the carbo tool suite that helps us build up these packages.

C

What we now want to do from a consumption standpoint is we want to go through this process of how do we take this software and how do we actually get it running on our cluster and the first step that we would take as far as beginning this journey of actually having something run is that we want a really simple way to actually introduce our packages onto our cluster so that they can be easily discovered by developers working against this kubernetes cluster.

C

So, in my particular case, I'm going to use cap controller's package repository concept and use the image package bundle that eli just pushed, which contains the package definition that he just created for the piece of software that someone might want to deploy on the cluster.

C

So our expectation here is when I create this package repository. What I should see is that I have packages available on my cluster, so in order to do that, I'm going to come out to my terminal and I'm going to really quickly run this command here with cap, and so what we should expect after we run.

C

This is that this package, repository called simple package repository, is going to create be created in my default namespace, and what I should see is that the package that eli just created is now discoverable on my cluster, such that people can view the package and decide whether or not it's something that they want to install.

C

So if I go ahead and click yes here, we get this confirmation message just basically saying that the package repository is being created and if I just create a quick watch here, what we should be able to see is that the package repository is in this state of reconciliation and basically, what that means is that this package repository is a request to cap controller, to basically go ahead and take everything. That's in the image package, bundle definition associated with it and create those packages on my cluster.

C

So now that it's in this reconcile succeeded stage, what we should be able to see is that these packages are now available to actually be installed.

C

So if I do a control c here and then I just do a k get packages, what we see is that I have this um package definition that eli just created, but it's now actually living on my cluster in such a way that it's easy to find. We can see that um the actual version of it is 1.0, and so this we can expect to be the 1.0 version that eli just created the next thing that we'd want to do as far as this process of discovering packages is figure out.

C

You know what are some configurable aspects of this package. So if I go ahead and just take a quick look at the package definition, what I can see is the value schema here and the properties that are associated with it. So, from my perspective, as a consumer, I'm using this value I can configure, and one of the properties that looks interesting to me. Is this hello message property, so the description of it says name used in hello message from app when app is pinged.

C

So my expectation here is that this package is creating an app and that this value that's specified here is what the response from the application will be, and I see that the default is stranger. So that looks good to me from the perspective of what I expect when I install this package.

C

So after looking over this package definition and seeing what is it that I'm going to install the next process, is I want to select what package I want to install and what version of that package I want to install and that can be accomplished through a a cap controller custom resource called a package install.

C

So this is basically a request that can be made to cap controller to specify what package you want that's available on the cluster and to have it actually deployed out to a particular name space on your cluster and then what version of that package you'll also see some commented out information here and we'll discuss that a little bit later in the demo. But for now what you can focus on is the spec of the package install which defines a service account.

A

C

So you'll note uh notice here that this service account name is needed for the package install because we are actually going to create resources on our cluster that are defined in the package itself, which, if you'll remember back to the beginning of our demo, was the deployment and the service associated with this package, so we're basically defining the appropriate level of our back that this package install needs to have to create things on our cluster.

C

The other portion of the spec here that we have is that we have a package reference, so this is a way to choose what package you want to install and the particular version, so we're going to select demo app, karbal.dev and then we're going to under the version selection constraints, select that we want version 1.0, and this should correspond to what we already have on our cluster.

C

So if I come back out to the terminal now and I'll just do a quick, cue control get all here just show we don't have anything in our namespace currently, but after we create our package install with cap, we should expect to see that we have our deployment and our service running that's associated with our package.

C

So if I go ahead and confirm that I want to create this package install, I get this confirmation that the package install has been created.

C

And if I go out now, I can see some basic information about the package install itself and, if you're confused by package, I there it's just basically a shorthand of saying package install with cube control. So I see that I have a package install uh created called package demo. It corresponds to the correct package name and the version that we expect and now, if I do acute control get all again, I have this deployment. I have this pod created and I also have an associated service.

C

So the last thing that we'd, maybe want to check, is to see if that hello message has that default value of stranger when we ping it and the easiest way that we can do. That is by setting up a port forward here and if we just do a curl local host on port 3000.

C

I get back this confirmation message here that says hello, stranger, so we've been able to through this request of a packaging install actually have this software running on our cluster. That's defined by this package definition, but one thing we also mentioned is that this package install is this way to configure these values.

C

So one thing that we can do here is using this unco or uncomment this portion of the ammo here and say that we also want to create a kubernetes secret as part of the process of creating our package install, and we actually want to reference this secret in our package install under this values section and within the secret.

C

We can basically say that this hello message: I want to change it to carvel community, so we should expect here that when we recreate this package install or update it, what will happen is we'll get a different response back from the application. That's been deployed so coming back out here.

C

um If I now go ahead and rerun this command to create the package, install you'll see that we have this update, that's going to take place for the package install and we're going to create the secret I'll go ahead and create this now and we'll just make sure to see that it finishes reconciling and picks up our update.

C

So there it's gone through and we can see that everything should be running successfully now. So, if I come back- and I do my port forward again, my expectation is that I get this um hello, um carmel community message back. So one of the things that we can do here is not only highlight a lot of the aspects of you know the configuration and how we deploy things out to our cluster. We can also make it really simple to configure these values in such a way.

C

That's useful for end users to not have to think about all the details about what is being deployed and how we're going to deploy something.

C

So this concludes our demo from a package author and package consumption standpoint and learning about these package management apis that cap controller introduces for anyone who is interested in more information on the work that we're doing on cap controller. We have this whole website here and it's got tons of information on cap controller.

C

That should give you some basics of the continuous delivery and package management features that cap controller offers. We also for anyone interested have more hands-on information. Like our terminology and apis that basically goes through all of the resources that cap controller introduces.

C

You can go through the flow that eli introduced of authoring packages or, if you're, just a big fan of me like not having to know all the details and just installing stuff easily package consumption is probably a good workflow for you to check out as well.

C

So with that, I will go ahead and kick it back over for the rest of the community thanks. Everyone.