Nuon App Templates

Package your existing application code and infrastructure to create Bring Your Own Cloud installable versions of your product.

An app template is what you build in Nuon to deliver your product into customer cloud accounts: the sandbox, components, inputs, and actions that point to the Terraform, Helm charts, manifests, and images behind your product. Each install is one deployment of an app template in a customer account.

Nuon is designed so you can lift and shift your existing application and infrastructure into new deployment options. Most Nuon users will create multiple app templates to offer different “flavors” of BYOC to their customers. e.g., AWS, Azure versions, dev, prod environment versions, create a VPC, re-use a VPC versions, etc.

What Is An App?

When you first set up Nuon, you will map your existing product into one or more app templates. An app template points to the code and artifacts that make up your product and describes how to install them into your customer’s cloud account.

How do you configure an App?

Each app template is represented as multiple configuration TOML files, called the app config.

New to app config? Configuration Files walks through the files an app needs and how to sync them.

Each app consists of the following parts:

• Sandbox - The base infrastructure layer e.g., AWS EKS, Azure AKS
• Runner - The Nuon service that manages the install
• Inputs - Customer-provided input values specific to each install e.g., product release, domain name
• Components - Your application e.g., Helm, manifests, load balancers, certificates, Terraform

Components can pull from your own Git repositories. To use private repositories, connect your GitHub account or organization to your Nuon org first — public repositories need no connection:

nuon orgs connect-github

Confirm the connection:

nuon orgs list-vcs-connections

You can also connect from the dashboard: click your organization name in the top left, then Add next to GitHub Connections. See Connect GitHub for the full walkthrough.

Sandbox

The sandbox sets up your application’s base compute environment, such as a Kubernetes (EKS, AKS, GKE) or ECS cluster. It gives your application a consistent, isolated place to run across every install. In a shared-responsibility model, the sandbox can also build on infrastructure a customer already provides, such as an existing cluster.

Read more about the Sandbox concept, or follow the Configuring Sandboxes guide to set one up.

Networking

Networking is provisioned by the install Stack: the Terraform or CloudFormation/Bicep that the customer deploys first.

The Stack creates:

• The network your application runs in (a VPC on AWS, a VNet on Azure)
• The Runner that deploys and operates your application
• The permissions the Runner needs

The sandbox then runs inside this network. The Stack can create a fresh network or reuse resources the customer already has. See Stacks for the available patterns.

Inputs

Inputs allow you to define different inputs that customers can provide to an app. This enables you to create “configuration” knobs that your customers can manage to control your application.

Inputs are commonly used to:

• Allow users to select regions and provide access to an account
• Customize application & infrastructure versions, such as pinning a Kubernetes cluster version
• Re-use existing infrastructure, such as providing a vpc_id that has been granted access

Read more about Inputs, and see Configuring Inputs & Secrets for a step-by-step walkthrough.

Components

Components are used to connect your existing application and infrastructure code to your app template.

Components allow you to:

• Import existing images, or build Dockerfiles and sync these artifacts into customer accounts
• Deploy Helm charts
• Deploy Kubernetes manifests
• Deploy Terraform code

Common components include certificates, load balancers, Kubernetes operators or Helm to deploy an application or database, etc.

Apps allow you to create dependencies between components and expose a rich configuration language to share outputs between components for configuration. You can use variables to configure components with the outputs of other components.

Read more about the Components concept, or get hands-on with Managing Components. Jump straight to your component type:

Helm Chart Components

Kubernetes Manifest Components

Terraform Components

Container Image Components

Image Update Policies

READMEs

When running your application in an Install, you often need to document important info. e.g., its access URL, the install state, links to documentation.

It can also be nice to have some level of programmability, such being able to render a button that will trigger an action. Additionally, this documentation must be rendered per-Install because certain values — such as URLs — will be different for each Install.

App READMEs were introduced to support this. Each app has a README.md text field where you can define a Markdown document which will be rendered in the dashboard for each Install of that App. You can use all valid Markdown, including HTML. You can also use variables, so that the document will be custom-rendered for each Install.

See the Using READMEs guide for more details.

App Management

The CLI exposes many operational commands to manage apps. The dashboard can also provide limited app management functionality. See the Managing App Templates guide for common workflows.

To see all available commands, run: nuon apps --help.

Commands for creating, deleting, and viewing apps.

Create a local app directory - Create a directory for your app’s configuration files, in a GitHub repository. It can have any name; the app branch’s directory setting tells Nuon where to find it.

mkdir your-app
cd your-app

Create an app template - .toml config files are used to represent a configuration for a single app.

nuon apps create --name=your-app

List all apps - List all apps using the CLI or dashboard.

nuon apps list

Pinning an app - pin your app

You can pin an app, which will set its ID as a default argument to all app commands. This is helpful to avoid having to pass -a to each command.

nuon apps select

Each example below assumes you have run nuon apps select first.

To show the currently pinned app:

nuon apps current

Get an app - Get basic info about app

nuon apps get

Rename - Rename an app

nuon apps rename --name=new-name

Configuration

You can view various configs for an app using the CLI. Config itself ships through app branches.

Ship config - Push to the git branch your app branch tracks

Each push to the tracked git branch starts a branch run. The run fetches your config at that commit, validates it, uploads it to the Nuon control plane, and builds components such as Terraform modules, Helm charts, Kubernetes manifests, and container images.

A run builds a component when its TOML file, or a related file such as a Helm values.yaml, has changed. If only a component’s source files changed, rebuild with nuon branches trigger --branch-id <branch> --force.

Create the app branch once by syncing its branch file:

nuon branches sync --file branches/main.toml

Configs - List all config versions for an app

nuon apps configs

Runner-config - Print the current runner config

nuon apps runner-config

The output of the following 2 sub-commands are JSON so to improve readability, use jq or python

nuon apps <sub-command> | jq
nuon apps <sub-command> | python -m json.tool

Sandbox-config - Print the current sandbox config

nuon apps sandbox-config

Input-config - Print the current input config

nuon apps input-config

App Metadata

You can add the following metadata to your app, which is used in installers:

• display_name
• description

This metadata can be added via a metadata.toml config file in the app root directory:

display_name = "Your app"
description  = "your app"
readme       = "./README.md"

The readme field points to a README.md file that will be rendered in the Dashboard for each app and its installs.