Add BYOC installation to your app

Enable customers to manage their installs through your UI

All the features of the Nuon platform are exposed via a REST API, allowing for fully programmatic operation. We also maintain a Golang SDK, which we use ourselves for the Dashboard and CLI. This guide walks through how to implement a complete install lifecycle using the API so your customers can manage their installs directly from your own product.

Provision an Install

At a high-level, provisioning a new install consists of 3 steps:

1. Creating the install in the Nuon control plane.
2. Installing the runner in the customer’s cloud account.
3. Approving the provision of the app components into the customer’s cloud account.

Create an Install

curl

curl -X POST https://api.nuon.co/v1/installs \
  -H "Authorization: Bearer $NUON_API_TOKEN" \
  -H "X-Nuon-Org-ID: $NUON_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app...",
    "name": "acme-corp-production",
    "aws_account": {
      "region": "us-west-2"
    },
    "inputs": {
      "domain": "acme.example.com"
    }
  }'

Install the Runner

Installing the runner happens out of band, entirely on the customer’s side. You just need to provide them with directions. We provide these for each install as part of the provision workflow.

Once the runner is installed, it will phone home automatically.

Approve the Provision

Once the runner is installed, it will be ready to provision the sandbox and app components. The platform supports approving each step individually or approving all steps at once. Typically, the customer will want to approve resources being created in their account, so we recommend exposing this to them — mapping a single “Approve” button in your UI to “Approve All” keeps the experience simple.

The workflowID is returned when creating the install. You will need to store this to approve the provision workflow.

curl

curl -X PATCH https://api.nuon.co/v1/workflows/$WORKFLOW_ID \
  -H "Authorization: Bearer $NUON_API_TOKEN" \
  -H "X-Nuon-Org-ID: $NUON_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"approval_option": "approve-all"}'

Maintain an Install

Even though the goal of using Nuon it to provide a SaaS-like experience, where you can maintain the install for your customer, there are still a few things they will need to be able to do themselves. Common use cases are:

• Accepting a new version of the app
• Allowing you to break glass to triage an issue
• Updating an input value that was incorrect
• Updating a secret that was incorrect
• Inspecting audit trails for compliance reasons

We will cover the API calls needed for these use-cases here.

Update Inputs

curl

curl -X PATCH https://api.nuon.co/v1/installs/$INSTALL_ID/inputs \
  -H "Authorization: Bearer $NUON_API_TOKEN" \
  -H "X-Nuon-Org-ID: $NUON_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "domain": "new-domain.example.com",
      "replicas": "3"
    }
  }'

Update Secrets

curl

curl -X POST https://api.nuon.co/v1/installs/$INSTALL_ID/sync-secrets \
  -H "Authorization: Bearer $NUON_API_TOKEN" \
  -H "X-Nuon-Org-ID: $NUON_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"plan_only": false}'

Delete an Install

Uninstalling an app requires performing the same operations as a provision, but in reverse.

1. Deprovision the app resources from your customer’s cloud account.
2. Uninstall the runner.
3. Delete the install from the control plane.

Deprovision the App

To deprovision the app resources and sandbox, you will need to run an install deprovision workflow. Just like the provision workflow, this will require approvals — typically mapped to a single “Approve” button in your UI for simplicity.

curl

curl -X POST https://api.nuon.co/v1/installs/$INSTALL_ID/deprovision \
  -H "Authorization: Bearer $NUON_API_TOKEN" \
  -H "X-Nuon-Org-ID: $NUON_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"plan_only": false}'

Uninstall the Runner

Just like installing the runner, uninstalling it happens out of band. The instructions are provided in the deprovision workflow.

Delete the Install

Once all the resources have been removed from your customer’s cloud account, you can delete the install from the control plane.

curl

curl -X DELETE https://api.nuon.co/v1/installs/$INSTALL_ID \
  -H "Authorization: Bearer $NUON_API_TOKEN" \
  -H "X-Nuon-Org-ID: $NUON_ORG_ID"

Forget an Install

Sometimes, an install can get into a bad enough state that you cannot even run deprovision operations. Usually, this means something catastrophic has happened out of band in the customer’s account, and it would be easier for Nuon to simply forget the current install and re-install the app from scratch.

curl

curl -X POST https://api.nuon.co/v1/installs/$INSTALL_ID/forget \
  -H "Authorization: Bearer $NUON_API_TOKEN" \
  -H "X-Nuon-Org-ID: $NUON_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'