> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuon.co/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS

> Deploy and manage BYOC apps on AWS.

## Configuration

To deploy an app to AWS, configure it to use an AWS sandbox and runner. We provide a minimal sandbox you can use to get started. You will need to set some vars to configure the sandbox. Create inputs for the public and private domains, since those will be different for each install. You will also need to set some IAM roles to grant the runner access to the EKS cluster.

```toml sandbox.toml theme={null}
# 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}}"
public_root_domain   = "{{ .nuon.inputs.inputs.root_domain }}"
internal_root_domain = "internal.{{ .nuon.inputs.inputs.root_domain }}"

[[var_file]]
contents = "./sandbox.tfvars"
```

```toml sandbox.tfvars theme={null}
maintenance_role_eks_access_entry_policy_associations = {
  eks_admin = {
    policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSAdminPolicy"
    access_scope = {
      type = "cluster"
    }
  }
  eks_view = {
    policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
    access_scope = {
      type = "cluster"
    }
  }
}
```

```toml runner.toml theme={null}
# runner

runner_type = "aws"
helm_driver = "configmap"
```

## Installation

When you create a new install, Nuon generates the install stack your customer uses to provision the runner and base infrastructure in their AWS account. Two stack formats are produced for every AWS install, and your customer can use whichever fits their tooling:

* **CloudFormation** — a generated Cloudformation template, installable via a Quick-Create URL or the AWS CLI.
* **Terraform** — a generated `install.tfvars` for the [`install-stacks/aws`](https://github.com/nuonco/install-stacks) Terraform module, applied with the standard `terraform` CLI.

Both formats describe the same set of resources (IAM operation roles, secrets, and trust to the Nuon control plane), so installs end up in the same state regardless of which one your customer runs.

### Create an Install

Navigate to the Installs tab in the Nuon dashboard, click "Create Install", and select the app you want to install.

This kicks off a provision workflow. Both the CloudFormation stack and the Terraform tfvars are generated with the install ID, region, and other settings already interpolated. The provision workflow's "await install stack" step exposes both via tabs ("CloudFormation" and "Terraform"), which can be shared with your customer.

### Install the Stack

Your customer must log into the AWS account they want to install your app in, and ensure they have the required permissions.

#### Option 1: CloudFormation

Either:

* Open the **Quick-Create URL** in a browser and complete the web flow, or
* Run the provided **AWS CLI** `create-stack` snippet ([install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) first).

#### Option 2: Terraform

From the Terraform tab in the dashboard:

1. Download the generated `install.tfvars`.
2. Create a `backend.tf` to store Terraform state (an S3 snippet is provided in the dashboard).
3. Run `terraform init && terraform apply -var-file=install.tfvars` against the [`install-stacks/aws`](https://github.com/nuonco/install-stacks) module.

Custom resources from CloudFormation nested stacks are not translated automatically. If you extend the install stack with custom Cloudformation resources, fork [`install-stacks`](https://github.com/nuonco/install-stacks) and make the equivalent Terraform changes there.

## Updating

If you make changes to the install stack, the install must be reprovisioned.

1. From the install's Overview page, click "Reprovision install" in the "Manage" drop-down. This triggers a reprovision workflow.
2. A new CloudFormation template and Terraform tfvars are generated.
3. Send the updated Quick-Create URL / CLI command, or the new `install.tfvars`, to your customer.
4. Customers using Terraform re-run `terraform apply -var-file=install.tfvars` against the same backend.