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}}"