About sandboxes¶
A sandbox is a snapshot of the configuration state of your production tenant that is made available as a copy. Use a sandbox to safely make configuration changes, and then promote those changes back to your production tenant.
A sandbox should be short-lived and should be used to make small, iterative changes within your tenant. After these changes are safely promoted to your production tenant, the sandbox should be deleted. Use a sandbox for each iterative change to ensure that you are never making large changes to your production tenant.
Important
Data is not moved between your production environment and a sandbox environment. Only the configuration state is copied to the sandbox environment and only changes to the configuration state are copied back to your production environment.
For example, if you use a sandbox to add the components required by a new data source, such as a courier, a feed, along with a custom domain table in which semantic tags are applied, after promoting those changes from a sandbox environment you will need to run the courier to pull the data to your production environment.
Note
The Allow sandbox administration policy allows full access to all sandboxes in a tenant, including the ability view details for any sandbox, access any sandbox, promote changes from any sandbox to production, and delete any sandbox.
A user must be assigned the Sandbox Administrator policy before they can manage use sandboxes to make configuration changes to their production tenant.
About sandbox workflows¶
A sandbox workflow provides a version history of all changes made in the sandbox, including when they were made, who made them, and which components within Amperity were changed. A record is maintained of all changes that are promoted from the sandbox to the production tenant.
Important
Only Sandbox Administrators are granted permission to merge promoted changes to a production tenant. This means that in many cases, promoted changes must be reviewed and accepted prior to completing the promotion workflow.
After you’ve validated your changes, contact your Sandbox Administrator to have them access your sandbox and promote your changes.
A sandbox workflow is similar to the workflows software engineers use with version control systems: a series of small, iterative changes are submitted and approved for use in the production environment.
Configuration states go in two directions:
Configuration states are pulled from the production tenant to the sandbox.
Note
Data is not moved from your production environment to a sandbox environment.
A banner within a sandbox notifies you if there are states that can be pulled from the production environment or promoted from the sandbox environment, along with notifying you of any conflicts that may exist between the configuration states.
A banner is shown when changes in your production tenant are available to be pulled to your sandbox.
Changes to configuration states that are made in a sandbox may be promoted to your production tenant.
Note
Data is not moved from a sandbox environment to your production environment.
A detailed list of all changes to all components and data sources is available for each promotion workflow.
A banner is shown when changes in a sandbox are ready to be promoted to your production tenant.
If there are conflicts between the two configuration states, one of the configuration states must be chosen.
Amperity will run a series of validations against the changes you have made in the sandbox environment against all workflows within the sandbox that depend on the changes you have made.
In some cases, a change will require additional updates to upstream or downstream dependencies within the sandbox that must be addressed before you can promote those changes to your production environment.
For example: a schema mismatch may exist between tables, a database table may be missing, or a data source may be unavailable.
Each validation error will be shown. Click on a validation error to view more details about how you can resolve the validation error.
You may see validation warnings. Warnings are important to ensure future workflows succeed, but the sandbox can be promoted as long as there are no errors.
Create a sandbox¶
If you have been assigned the DataGrid Administrator and Sandbox Administrator policies you can create and manage a sandbox.
You can create and manage your sandbox from the Users & Admin page. You can do this by going to the Sandboxes section on the Users & Admin page, and then clicking Create sandbox.
Delete a sandbox¶
You can delete your sandbox from the list of sandboxes by selecting the icon in the Sandboxes section on the Users & Admin page, and then from the list of options selecting Delte.
Note
Any DataGrid Operator or DataGrid Administrator can also delete sandboxes that they are the assigned tenant owner of. A user is assigned a tenant owner of a sandbox when they create the sandbox. It allows them to delete the sandbox and they will receive any communications from Amperity about the sandbox. Any user can be assigned as a tenant owner, and a sandbox can have more than one tenant owner.
Promote a sandbox¶
You can promote by reviewing and resolving the list of Added, Changed, and/or Removed configuration state changes in the Validations section in your sandbox and then clicking Promote.
Note
Errors must be addressed before the sandbox can be promoted.
Access your sandbox¶
A sandbox is accessible from the drop-down menu that is associated with the name of your production environment.
To access your sandbox
Log in to Amperity.
From the tenant drop-down menu, select the sandbox environment. A sandbox environment should have the same name as your production environment, but with “SB” appended to it.
This opens the sandbox environment for your production environment.
Review updates¶
When your production environment contains changes that are not present in your sandbox environment you will see an Updates available notification in a banner within the sandbox environment.
To review production updates
From an Amperity sandbox environment, next to Updates available, click Pull updates.
Under Updates to pull, a list of changes is shown.
Review each change.
When finished, click Pull.
Pull updates¶
Updates within your production environment must be pulled to the sandbox environment. After pulling these changes, refresh your sandbox environment by running couriers to refresh domain tables, and then regenerate Stitch results for all databases.
To pull updates from your production tenant to your sandbox
From an Amperity sandbox environment, next to Pull updates, click View changes.
Under Updates to pull, a list of changes is shown.
Review each change.
When finished, click Pull.
Resolve conflicts¶
In situations where there is a conflict between the state of the sandbox and the production tenant, that conflict must be resolved before any changes in production can be pulled into the tenant.
Sometimes, when you go to pull or promote changes, you’ll see net new validation errors in the sandbox validations table. These occur when a merge would result in invalid configuration and you must fix them before you can merge the changes.
When doing a merge, Amperity will attempt to combine the configuration in the sandbox environment with the configuration in the production environment. Sometimes this results in an invalid configuration.
If you need a table or database in both production and sandbox environments, create it in one or the other, and then merge the environments.
If you create a table or database in both environments, one (or more) of the following validation errors will be shown:
Error |
Why this happens? |
Resolution |
---|---|---|
Table name “X” is used 2 times in database “id-here”. Each table within a database must have a unique name. |
If you add the same table in both production and sandbox environments manually, these tables will have two different IDs. In this case, Amperity will attempt to put both tables into the database, which is invalid. |
Choose to resolve a conflict by removing one of the tables. Remove the table from your sandbox environment if you want to keep the table that exists in your production environment. Remove the table from your production environment if you want to keep the table that exists in the sandbox environment. |
Multiple tables (“X”, “Y”) are tagged with the unique “:customers” tag in database “Stitch QA”. At most one table per database can be tagged with a given unique tag. |
For the same reason as above - the table was added in both production and the sandbox environments manually, and then tagged in both. In this case, Amperity will try to combine them into a single database, which results in this error. |
Same as above - either resolve via conflict or remove the table fro your sandbox or production environments. |
To resolve conflicts between production and a sandbox
From an Amperity sandbox environment, next to Updates available, click Pull updates.
Under Conflicts, for each conflict, compare the changes between the production and sandbox environments.
Enable the Show full configuration checkbox to show additional configuration details.
After identifying the differences between the production and sandbox environments, select the radio button for the production environment or sandbox environment.
This will keep the changes in the sandbox environment or it will pull the change from the production environment to the sandbox environment.
When finished reviewing conflicts, click Pull.
Make configuration changes¶
When your sandbox environment is ready, you can make changes in the Sources, Stitch, Customer 360, and Destinations tabs.
Review and promote¶
When a sandbox environment contains changes that are ready for promotion to your production environment, a banner appears with the words Ready to promote. Changes in a sandbox must be promoted to the production tenant by a user assigned the Sandbox Administrator policy.
Note
Before promoting, or reaching out to your Sandbox Administrator to promote, be sure that you have pulled all updates into your sandbox environment, run each workflow successfully, and checked for sandbox validation errors.
Tip
Be sure to run your sandbox environment completely, and then compare the amounts of time required to generate Stitch and your databases in the sandbox environment to the amount of time required within your production environment. You should investigate the causes of any large increases in runtime.
For example, a large increase may be an indicator that expensive SQL actions, such as an implicit cross join across two very large tables, may be present in a custom domain table or database table.
A sandbox environment must be in a valid state before you can promote changes to your production environment.
Warning
If there is an existing workflow that is affected by changes in your sandbox that are currently running in production, a warning is shown. You must select the Yes, continue promoting these changes to production option to promote changes while that workflow is running.
To promote changes to the parent tenant from the sandbox
From an Amperity sandbox, next to Ready to promote, click Promote changes.
On the Changes to promote page, a list of changes is shown.
Review each change.
Be sure that all validation errors are addressed, and you’ve reviewed any outstanding warnings.
Write a merge message that describe the changes you are promoting.
Click Promote.
Once changes are promoted, the update should be reflected in the production tenant momentarily.
Only configuration changes in the sandbox will be promoted to the production tenant. After promoting these changes, refresh your production tenant by running couriers to refresh domain tables, and then regenerate Stitch results for all databases.
Restore changes¶
Changes that are promoted to production from a sandbox may be restored to a previous state. There are two approaches:
In many situations you can use a sandbox workflow to quickly restore the state of production, especially when a sandbox was used to make small, iterative changes. First create a sandbox, and then make changes in that sandbox that returns your tenant to its previous state.
Important
In situations where this cannot be done using a sandbox workflow, please ask for assistance from your Amperity Support team.
If Amperity Support restores your tenant all changes that were made to your tenant after the point in time to which your tenant will be restored will be lost. This includes changes made in production and changes that may have been promoted from other sandbox workflows.