Link Search Menu Expand Document

The application catalog

Managing applications involves taking into consideration how we plan to distribute them. In the Kubernetes ecosystem we are used to either render our YAML files with a tool such as kustomize and distribute those through a selected channel (e.g., store them in a repository), or make use of tools such as Helm and define our applications as charts. The first approach requires us as developers to define the intermediate tooling to upload, download, deploy the applications from the selected repository while maintaining a low complexity from the point of view of maintaining the core YAML files. The second approach increases a notch the complexity of the maintenance since creating a chart is not a straitforward task, and also requires preparing a repository compatible with Helm.

With respect to discovery and reusability, both approaches have downsides related to how an application is defined, what is the effect of deploying a template (i.e., which entities are expected to be generated), and how we can share and compose complex applications reusing existing components.

On the other hand, if we focus on a single container, we are quite used to how docker hub, or how any other registry (e.g., Google Container Registry) works. The ease by which we are able to upload, download, update and remove containers makes it quite convinient for both users and automation steps.

The NAPPTIVE Catalog is highly inspired by the way container registries work in such a way that we offer the same experience that you get for single containers but for complete applications. Think of this as another step in the gitops movement.

The elements

The catalog will store applications on a repository named after your username (which matches the one you are using in github). An application is referenced on the catalog using the following identifier:

[catalog/]namespace/appName[:tag]

Where:

  • catalog is an optional prefix related to the target catalog you are using. By default if omitted, the application will be stored/retrieved in the NAPPTIVE Playground public catalog.
  • namespace is the namespace associated with the user, team, etc. For a personal account, this matches the name of your github account associated with your free Playground account.
  • appName is the name of the application to be uploaded.
  • tag is the optional tag associated with a version of the application. Notice that if omitted latest will be used.

An application in the catalog is a collection of YAML entities that specify which elements are involved in its deployment. In order to fully identify the application, a metadata file is required. This enables a better discovery of what is available on the catalog. To upload an application, please include a metadata.yaml file with the other elements of the application, with the following content:

apiVersion: core.napptive.com/v1alpha1
kind: ApplicationMetadata
# Name of the application, not necessarily a valid k8s name.
name: "My App Name"
version: 1.0
description: Short description for searchs. Long one plus how to goes into the README.md
# Keywords facilitate searches on the catalog
keywords:
  - "tag1"
  - "tag2"
  - "tag3" 
license: "Apache License Version 2.0"
url: "https://..."
doc: "https://..."
# Requires gives a list of entities that are needed to launch the application.
requires:
  traits:
    - my.custom.trait
  scopes:
    - my.custom.scope
  # K8s lists Kubernetes specific entities. This provides a separation between OAM entities in an orchestration-agnostic environment, and applications that specifically require Kubernetes.
  k8s:
    - apiVersion: my.custom.package
      kind: CustomEntityKind
      name: name
# The logo can be used as visual information when listing the catalog so the user recognizes more easily the application.
logo:
  - src: "https://my.domain/path/logo.png"
    type: "image/png"
    size: "120x120"

As for the layout of the application YAML we recommend:

/<application>
  |- metadata.yaml
  |- README.md
  |- app_cfg.yaml
  |
  |- <opt_directory>
  |  |- OAM_entity.yaml
  |  \- K8s_entity.yaml
  |- OAM_entity.yaml
  \- K8s_entity.yaml

Adding a README.md file will also help consumers of the application understand how it is intended to be deployed, how parameters interact, etc.

Private and public catalogs

We support two types of catalogs with respect to their visibility and permissions. The NAPPTIVE Catalog available on the Playground is public, meaning:

  • All users can list applications from all repositories.
  • All users can pull applications from all repositories.
  • Only the owner can push, and remove applications from its own repository.

To use private catalogs (e.g., having a private company catalog), you need to deploy the catalog on your own infrastructure in the same way a private docker registry is installed. We are currently working on the distribution method for the catalog component so let us know if you are interested in testing this approach, as we may release this initially to a set of beta users.

What’s next

  • Discover how you can use the catalog to deploy existing applications or upload your own.