​
What is a Sandbox?

Sandboxes create a consistent, isolated environment that your application can be guaranteed to work with, across hundreds or thousands of different installs. They are responsible for defining the basic networking, permissioning, and compute primitives to power the App. In a shared responsiblity model, a customer may provide some infrastructure in the Sandbox, such as an existing network or compute cluster. In this case, Sandboxes enable you to leverage this customer infrastructure, while also having a consistent way to deploy and manage your App in any account.
Sandboxes ensure you can install your App into any account - whether a completely new account with no prior provisioning, or an account with other workflows.Sandboxes can ensure isolation, reproducability and repeatability with each install - regardless of the account.

​
How is a Sandbox configured?

A Sandbox is configured in a sandbox.toml file inside the root of your App Config directory. To configure a Sandbox, specify a repo and the correct parameters for your Sandbox. Inputs and variables, either inline in the sandbox.toml or a tfvars file, can be used to configure the Sandbox, and these are passed to the Terraform code that is run by the Sandbox. You can configure Sandboxes to use either a public repo (using a public_repo block) or a private GitHub repo (using a connected_repo block). Read more about VCS configuration here.
sandbox.toml
#:schema https://api.nuon.co/v1/general/config-schema?source=sandbox
terraform_version = "1.11.3"

[public_repo]
directory = "."
repo      = "nuonco/aws-eks-karpenter-sandbox"
branch    = "main"

[vars]
cluster_version = "1.33"
cluster_name    = "n-{{.nuon.install.id}}"

enable_nuon_dns      = "true"
public_root_domain   = "{{ .nuon.inputs.inputs.root_domain }}"
internal_root_domain = "internal.{{ .nuon.inputs.inputs.root_domain }}"

[[var_file]]
contents = "./sandbox.tfvars"
You can configure Sandboxes to use either a public repo (using a public_repo block) or a private GitHub repo (using a connected_repo block). Read more about VCS configuration here.

​
Nuon Managed Sandboxes

We maintain managed Sandboxes for each platform that we support. Each platform has both a turnkey (where all resources are provisioned) and a bring-your-own-vpc sandbox. These sandboxes are designed to be a stable, configurable starting point and most relevant options around the network, cluster and compute are configurable. We publish each Sandbox as a GitHub repository and you can find detailed documentation for each Sandbox there. These repositories are what you will reference in your sandbox.toml. AWS EKS Sandbox AWS EKS with Karpenter Sandbox AWS Min Sandbox

​
Sandbox Outputs

Sandbox outputs are made accessible to all components using variables. You can use any output from your selected Sandbox by setting a config value on your component. In this example, we are using the account.region output from the Sandbox to configure a Helm chart component:
nuon.<your-app>.toml
[[components]]
name   = "e2e_helm"
type = "helm_chart"
chart_name = "e2e-helm"
[components.public_repo]
repo      = "org/repo"
directory = "chart"
branch    = "main"
[components.values]
account_region = "{{.nuon.install.sandbox.outputs.account.region}}"

​
Configure Sandboxes

Each managed Sandbox has a set of variable inputs. Most variables are either supplied by the Nuon platform during install, via inputs, or by setting default values.

​
Use Default Values

To configure a Sandbox parameter with a default value for your App, add a vars block to your sandbox.toml file, or a sandbox.tfvars file in the same directory as your sandbox.toml. The values in this block will be used as defaults for all installs of this App.:
sandbox.toml
[vars]
cluster_version = "1.33" # default in 1.32
min_size = "3" # default is 2
max_size = "6" # default is 5

​
Use Inputs

Inputs allow you to collect customer input in the dashboard at App Install for values such as resource IDs, tokens and more. These Inputs are accesible to all Components and your Sandbox, using variables. To configure a Sandbox parameter using an Input, you can define an Input in your inputs.toml file and then reference it in your sandbox.toml file. In this example, we define a root domain Input and use it to set the public_root_domain variable in the Sandbox:
inputs.toml
[[group]]
name         = "dns"
description  = "DNS Configrations"
display_name = "Configurations for the root domain for Route53"

[[input]]
name         = "root_domain"
description  = "The root domain. Services will be made available at subdomains of this root domain."
default      = "app.example.com"
display_name = "Root Domain"
group        = "dns"
sandbox.toml
[vars]
public_root_domain   = "{{ .nuon.inputs.inputs.root_domain }}"

​
Create a Custom Sandbox

While our open source Sandboxes are a great starting point, you can always fork them, or create your own Sandbox to support customizing. To use a custom Sandbox, simply update your App Config’s sandbox.toml to point to your new Sandbox code. Custom Sandboxes can also use private GitHub repos, that are connected to Nuon.
sandbox.toml
#:schema https://api.nuon.co/v1/general/config-schema?source=sandbox
terraform_version = "1.11.3"

[public_repo]
repo = "your-org/private-repo"
directory = "sandbox"
branch = "main"

If one of our managed Sandboxes does not work for you, and you are considering creating a custom Sandbox, we would love to hear about your use case!Please get in touch.