Configuration Files
Configure apps using a single .toml file
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>
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.
[[components]]
source = "./storage.toml"
[[components]]
source = "./container_image.toml"
name = "storage"
type = "terraform_module"
terraform_version = "1.5.3"
[public_repo]
directory = "components/storage"
repo = "nuonco/demo"
branch = "main"
name = "container_image"
type = "container_image"
[aws_ecr]
image_url = "ecr-repository"
tag = "latest"
region = "us-west-2"
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:
[[components]]
source = "./storage.toml"
name = "storage"
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"
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"
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"
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.
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}}"