Configuration Files

Config files allow you to define a BYOC application using a single .toml file. Under the hood, Nuon will handle keeping your configuration in sync.

Create an app

Config files are used to sync the configuration for a single app. To create an app and an example config file:

nuon apps create --name=<app-name>

This will create an example config file named nuon.<app-name>.toml.

Sync an App

To sync an app, and it’s configuration run:

nuon apps sync

This will sync each configuration file in the current working directory.

To sync only a single file:

nuon apps sync -c <file>

Note

Nuon uses terraform to keep your application config in sync. If you would like to migrate from a config file to terraform, you can run nuon apps export-terraform.

Export Terraform

You can export terraform from your application configuration using:

nuon apps export-terraform

Reusable components

You can reuse components by using a source field in your config file. This is useful for sharing components between applications or splitting up large configuration files.

nuon.your-app.toml

[[components]]
source = "./storage.toml"

[[components]]
source = "./container_image.toml"

storage.toml

name = "storage"
type = "terraform_module"
terraform_version = "1.5.3"

[public_repo]
directory = "components/storage"
repo = "nuonco/demo"
branch = "main"

container_image.toml

name = "container_image"
type = "container_image"

[aws_ecr]
image_url = "ecr-repository"
tag = "latest"
region = "us-west-2"

Note

When loading a component from a source, the components prefix is not needed for each field, like it is in the main config file.

You can also override fields from a source config file, by setting the values directly in your main toml file:

nuon.your-app.toml

[[components]]
source = "./storage.toml"
name = "storage"

storage.toml

type = "terraform_module"
terraform_version = "1.5.3"

Config Variables

You can define config variables to be used throughout your config, allowing you to set variables for common values.

To add a configuration variable, add the config_vars block to the top of your config file:

version = "v1"

[config_vars]
component_prefix = "app_"

You can then reference anywhere in your config:

[[components]]
name = "{{.component_prefix}}_storage"

Note

Config variables do not currently work with reusable component files.

Validate

You can validate a config file using nuon apps validate:

nuon apps validate -c nuon.<your-app>.toml

The CLI will automatically generate Terraform code from your config and run terraform validate on it and print any errors.

Reference

The configuration file allows you to configure an app similarly to the Nuon terraform provider.

Input Config

Define inputs for an app using the [input] block.

To configure a sensitive api_key and vpc_id input:

[inputs]
[[inputs.input]]
name = "vpc_id"
description = "vpc_id to install application into"
default = ""
sensitive = false
display_name = "VPC ID"

[[inputs.input]]
name = "api_key"
description = "API key"
default = ""
sensitive = true
display_name = "API Key"

Note

Inputs are not required, unless you are using a sandbox that requires inputs (such as a byovpc one).

Runner Config

Define the runner for an app using a [runner] block.

To configure a runner for an ecs sandbox:

[runner]
runner_type = "aws-ecs"

[runner.env_vars]
runner-env-var = "runner-env-var"

Note

Runners are a required configuration for all apps. In most cases, you do not need to customize them using environment variables.

Installer Config

Define an installer for an app using an [installer] block.

[installer]
name = "<your-app> Installer"
description = "Install <your-app> in your cloud."
homepage_url = "<your-homepage-url>"
documentation_url = "<your-docs-url>"
community_url = "<your-community-url>"
github_url = "<your-github-url>"
demo_url = "<your-demo-video-url>"
logo_url = "<your-logo-url>"
og_image_url = "<your-og-image-url>"
favicon_url = "<your-favicon-url>"

copyright_markdown = """
© 2024 <your-company>.
"""

footer_markdown = """
[Terms of Service](<your-terms-url>)
"""

post_install_markdown = """
# <your-app>

<your-app> is being deployed.
"""

apps = [
  "<your-app-id>",
  "<your-other-app-id>"
]

Sandbox Config

Define the sandbox for an app using a [sandbox] block.

To define an aws-ecs-byo-vpc sandbox:

[sandbox]
terraform_version = "1.5.4"
[sandbox.public_repo]
directory = "aws-ecs-byo-vpc"
repo = "nuonco/sandboxes"
branch = "main"

[sandbox.vars]
vpc_id = "{{.nuon.install.inputs.vpc_id}}"

Component Config

You can define components using a [components] block. Components must declare a type field and any relevant component-specific configuration.

Note

Each component will have dependencies automatically defined based on the order in the config file. Learn more about depencencies here.

Terraform Module Component

To define a terraform module component use the terraform_module type.

To configure a terraform component using a connected repo:

[[components]]
name = "terraform"
type = "terraform_module"
terraform_version = "1.5.3"

[components.connected_repo]
directory = "infra"
repo = "org/repo"
branch = "main"

[components.env_vars]
AWS_REGION = "{{.nuon.install.sandbox.account.region}}"

[components.vars]
account_id = "{{.nuon.install.sandbox.account.id}}"

Helm Chart Component

To define a helm chart component use the helm_chart type.

To configure a helm chart in a connected repo:

[[components]]
name = "helm"
type = "helm_chart"
chart_name = "chart-name"

[components.connected_repo]
directory = "helm"
repo = "org/repo"
branch = "main"

[components.values]
"api.ingresses.public_domain" = "{{.nuon.components.infra.outputs.iam_role}}"

Docker Build Component

To define a docker build component use the docker_build type.

To configure a docker build component from a private repo:

[[components]]
name = "docker_build"
type = "docker_build"

dockerfile = "Dockerfile"

[components.connected_repo]
directory = "deployment"
repo = "powertoolsdev/mono"
branch = "main"

Container Image Component

To define a container image component use the container_image type.

To configure a public container image:

[[components]]
name = "container_image"
type = "container_image"

[components.public]
image_url = "kennethreitz/httpbin"
tag = "latest"

To configure a container image from an ECR repo:

[[components]]
name = "container_image_ecr"
type = "container_image"

[components.aws_ecr]
iam_role_arn = "iam_role_arn"
image_url = "ecr-url"
tag = "latest"
region = "us-west-2"

Job Component

To define a job component use the job type.

To configure a job using a docker image from another component:

[[components]]
name = "job"
type = "job"

image_url = "{{.nuon.components.e2e_docker_build.image.repository.uri}}"
tag   = "{{.nuon.components.e2e_docker_build.image.tag}}"
cmd   = ["printenv"]
args    = ["-a"]

[components.env_vars]
PUBLIC_DOMAIN = "{{.nuon.components.infra.outputs.iam_role}}"

To configure a job using a docker image from docker hub:

[[components]]
name = "job"
type = "job"

image_url = "bitnami/kubectl"
tag   = "latest"
cmd   = ["printenv"]
args    = ["-a"]

[components.env_vars]
PUBLIC_DOMAIN = "{{.nuon.components.infra.outputs.iam_role}}"