Skip to main content

​
What is a Sandbox?

Sandboxes create a consistent, isolated environment that your application can be guaranteed to work with, across your App Installs different installs. They are responsible for defining the basic networking, permissioning, and infrastructure compute primitives e.g., a Kubernetes cluster - to power the App. In a shared responsiblity model, a customer may provide some infrastructure in the Sandbox, such as an existing VPC or Kubernetes cluster. In this case, Sandboxes enable you to leverage this customer infrastructure to meet security requirements, while also having a consistent way to deploy and manage your App in any account. 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, are entered both inline in the sandbox.toml and also the tfvars file - 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) such as Nuon’s public repository of AWS and Azure sandboxes - 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?type=sandbox
terraform_version = "1.11.3"

[public_repo]
directory = "."
repo      = "nuonco/aws-eks-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"
sandbox.tfvars
additional_namespaces = ["grafana"]

min_size = 2
max_size = 3
desired_capacity = 2

​
Nuon Managed Sandboxes

We maintain managed Sandboxes for each platform that we support. Each platform has a turnkey sandbox (where all resources are provisioned). These sandboxes are designed to be a stable, configurable starting point and most relevant options around the network, cluster and compute are configurable.
Let us know if you have a use case for bringing your own VPC or Kubernetes cluster, and we can show how to adjust the sandbox configuration.
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 Azure AKS Sandbox
The AWS Min Sandbox does not create a Kubernetes cluster, but still provisions a Route 53 Zone and IAM roles for the install. See the Lambda function example that leverages the AWS Min Sandbox.

​
Runner Types

Update the runner.toml in your App Config to specify the type of Cloud runner to use for your App. The runner is responsible for executing the deployment of your App into the customer’s account.
runner.toml
#:schema https://api.nuon.co/v1/general/config-schema?type=runner

runner_type = "aws"
helm_driver = "configmap"
runner.toml
#:schema https://api.nuon.co/v1/general/config-schema?type=runner

runner_type = "azure"
helm_driver = "configmap"

​
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:
components/e2e_helm.toml
name   = "e2e_helm"
type = "helm_chart"
chart_name = "e2e-helm"

[public_repo]
repo      = "org/repo"
directory = "chart"
branch    = "main"

[values]
account_region = "{{.nuon.install.sandbox.outputs.account.region}}"
See the outputs.tf for the AWS EKS Sandbox for a full list of available outputs or the outputs.tf for the AWS Min Sandbox. Example outputs include:
  • account.id - The AWS Account ID
  • account.region - The AWS Region
  • vpc.id - The VPC ID
  • cluster.cluster_name - The EKS Cluster name
  • cluster.cluster_endpoint - The EKS Cluster endpoint
  • ecr.repository_url - The ECR repository URL
  • ecr.registry_url - The ECR registry URL
  • nuon_dns.public_domain - The public root domain for the install
  • nuon_dns.internal_domain - The internal root domain for the install
  • namespaces - A list of namespaces created in the cluster

​
Configure Sandboxes

Each 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 the mandatory 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_name         = "n-{{.nuon.install.id}}"
enable_nuon_dns      = "true"
public_root_domain   = "{{ .nuon.install.id }}.nuon.run"
internal_root_domain = "internal.{{ .nuon.install.id }}.nuon.run"

[[var_file]]
contents = "./sandbox.tfvars"
sandbox.tfvars
additional_namespaces = ["grafana"]

min_size = 2
max_size = 3
desired_capacity = 2

​
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?type=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.
⌘I