Skip to main content Link Menu Expand (external link) Document Search Copy Copied
Napptive docs

The application catalog

Managing applications involves taking into consideration how we plan to distribute them. In the Kubernetes ecosystem we are used to either rendering our YAML files with a tool such as kustomize and distributing those through a selected channel (e.g., storing them in a repository), or using tools such as Helm and defining 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 the complexity of the maintenance a notch, since creating a chart is not a straightforward 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 convenient 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 you get for single containers but for complete applications. Think of this as another step forward 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 applications

There are two types of applications: public and private. While public applications will be available to all users, private ones can only be consulted by users of the accounts to which the application belongs. All versions of the same application must have the same scope (public or private).

Catalog applications

The private applications have a small padlock on the left to identify them. To upload a private application, check the catalog push command documentation for more details.

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 public applications from all repositories and their own private ones.
  • All users can pull public applications from all repositories and their own private ones.
  • 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.