Skip to main content
Let your customers deploy your product into their own cloud account from your app’s settings page. Your app calls the Nuon API in the background.

​
Before you start

Create a service account for your app with the least access that works, and store its token with your other secrets. Every call in this guide uses that token.
Creating cloud resources in your customer’s account takes a while. Run setup as a background job, and send a request_id on each call that starts work, so a retry after a timeout doesn’t run it twice. See Idempotent operations.

​
1. Collect the customer’s inputs

When the customer clicks Start setup, create an install with their inputs.
The response is the new install. Trimmed to the fields you’ll use:
Response
Save id with the customer’s record. Every later call uses it.

​
2. Have the customer connect their account

Your customer connects their account by creating your app’s stack, in their own cloud console. It’s a good idea to give a quick explainer for your customer’s security team. Call GET /v1/installs/{install_id}/stack. A trimmed example response:
Response
Point your connect button at the newest version’s quick_link_url. When the customer runs it, the stack creates the network, the permissions, and the runner in their account. Positioning safety of BYOC covers the follow-up questions customers usually ask.

​
3. Show setup progress

Once the customer initiates the install on their cloud account, Nuon deploys your product without any more input from the customer. You can show your customer each stage as it completes, and let them leave the page. Most software vendors track progress with webhooks:
  1. Register a webhook for workflow step events on your installs, with a secret so you can verify each request came from Nuon.
  2. On each event, update the matching stage from data.step.name and data.transition.
  3. On a failed event, show the customer data.step.name and data.outcome.error. Your support team sees the same error in Nuon.
If your app can’t receive webhooks, check the install’s status on a timer instead with GET /v1/installs/{install_id}.

​
4. Getting customer approvals

You can set installs to pause before anything your customers consider sensitive. Approvals happen on plan steps, before a Terraform, Helm, or Kubernetes manifest change applies. You choose which steps wait for the customer:
  • Set approval_option = "prompt" in the install config to require approval on the install.
  • Set auto_approve_on_policies_passing = true on a component or the sandbox to let its routine changes through. That step only waits for the customer when a policy check fails.
See Workflow approvals for how approvals work. When a step is waiting, find it with:
Then send the customer’s approval:
You don’t have to check for waiting steps on a timer. Set approval_requests to true in your webhook subscription, and Nuon calls your app as soon as a step needs approval. That’s your cue to show the customer this screen.