corestack_ environment_ create
Add an environment.
When to use it
Add a staging environment to a site — empty, copied from another environment (or a snapshot of one), or from a Git branch — protected by HTTP authentication from birth.
When another change in the same region is starting at that moment, the create waits for it instead of being refused: it is accepted at once, its operation stays pending with the status_label "Waiting for another change to finish. This carries on by itself." (the words the Control Panel shows), and it carries on by itself within a few minutes. Do not send it again. The task's status reads the same words while it waits.
When its DNS records cannot be published yet (Cloudflare busy, or a platform DNS problem for Corefinity to fix), the create waits at its dns step instead of failing: its operation stays pending with the status_label "Waiting for DNS", and the task's status reads the same words. It is tried again every minute and goes on by itself; do not send it again.
When the region has no room for the new environment yet, the create is not refused: it is accepted, waits briefly for room (capacity_being_added, "Setting up your site. This can take a little longer.") and then continues by itself. Do not retry it or create it again; follow it as usual.
When the region has no room for the environment's disk yet, the environment waits at its first step until there is, however long that takes: it carries on by itself, so do not create it again.
While restoring anywhere is switched on, source.type snapshot with snapshot_id restores any snapshot of the company's websites (corestack_company_snapshots_list lists them) into the new environment, optionally anonymised. A pinned token needs the snapshot's website covered as well. A snapshot that cannot be used (not ready, gone, past its retention, in another region) is invalid_arguments on source.snapshot_id, with the reason in its sentence.
If the environment's usual platform address is already used by another site, a standalone CoreStack environment is created on the next free one and its operation's notes say so (platform_address_changed, naming the address it uses); in a CoreCluster the create is refused in_use before anything is made, naming the address (choose another environment name, or contact Corefinity support). A name still held by an earlier create of the same environment that failed and is being cleaned up is waited for (up to about 20 seconds) instead of refused.
The new environment takes the PHP memory limit, upload size and max execution time of the environment it is made from (the clone source, else production). A value its size does not allow is changed to the nearest one it does: the completed task's result then carries notes ([{code, text}], code php_settings_clamped) naming each setting changed and the value it has now, as corestack_site_operation_get does; corestack_php_settings_get on the environment carries the same note while those values still apply.
On a Shopware site, the new environment's search follows the environment it is made from (the clone source, a snapshot's own environment, else production): on if it is on there and the new size is Medium (8 GB) or larger, otherwise off. RabbitMQ always starts off. Its operation's notes say what happened: search_carried (search is on, as on the source), search_stays_off (the source has search on, but the size is under Medium (8 GB); choose Medium or larger, or switch search on later after a resize) and search_not_carried (the source's setting could not be read, so search starts off; the create is never refused for it — switch search on from the Shopware tab once it is ready). Nothing is said when the source has search off. Search does not change the environment's size or price.
A new environment never fails while its certificate is issued: the task keeps waiting, for up to a few hours, and corestack_site_operation_get says "Certificate on its way" (note certificate_on_its_way) until it carries on by itself.
A create that stops on a temporary problem (the platform, its DNS or its SSH gateway not ready in time) is tried again automatically, at most three times, a few minutes apart; follow it with corestack_site_progress_get or corestack_site_operation_get (notes) instead of creating it again.
An environment is never refused because the region's staging servers are not ready yet: it is created on the region's production servers instead. When the region's servers are not taking new environments for the moment (being set up or replaced), it is created and waits, then goes on by itself once they are; there is nothing to retry.
An environment that needs a new server in the region while changes to cluster capacity are paused for planned maintenance is not refused: it is created and waits for its server, then goes on by itself once the pause ends; there is nothing to retry.
When the PHP version the new environment would run is not open to new sites yet (just after a PHP security update, before its tested release is opened), the create is not refused if the environment keeps the site's own PHP version (php_version left out, or the one production runs) or if no PHP version of its list is open. It is accepted and waits for that version, then goes on by itself once it is open, never on another one. Its operation stays pending with the status_label "Waiting for PHP 8.3 to be available", corestack_site_get on the new environment's row returns version_wait with kind php and php (the version it waits for), and the task says "Waiting for PHP 8.3 to be available for new sites. Your environment will be set up as soon as it is." Do not create it again. An environment that waits can be deleted with corestack_environment_delete.
Ask for it
Using the Corefinity MCP server, call corestack_environment_create with site_id 4211, name Staging, source {"type":"empty"}. (Add an environment.) Tell me what it returned.Inputs
Default the site's own. A site on a version new sites are not offered keeps it for its environments (a Magento 2 site on MariaDB 12.3 gets environments on 12.3); any other version must be one new sites are offered. For a clone whose scope copies the database and that names no snapshot_id, the default is the clone source row's own version instead when the copy engine would refuse the site's own (a database of MariaDB 12.3 cannot be copied into a row running 11.8), so leave it out to copy a moved 12.3 environment onto 12.3.
Up to 40 characters.
["eol"] once the person knows the Node.js major the environment will run, chosen or inherited, is end of life (refused with ack_required otherwise). Up to 1 items.
eolDefault the source row's Node.js major (the clone source, else production), with its global packages, which a chosen major keeps. 10 to 99.
Up to 8 characters.
Return the secret to you instead of opening it in the person's browser. Needs exec. Defaults to false.
Any row of the site. At least 1.
Default from the name; unique among the site's environments. Up to 16 characters.
snapshot_id: clone: a ready snapshot of that row; snapshot (only while restore_anywhere is on): any snapshot of the company's websites.
Fields
branch: deploy each push.
branch: the Git branch. Up to 255 characters.
branch: copy the data of this row. At least 1.
clone: the row to copy from. At least 1.
clone: what to copy (files_db).
files_dbdbfilesclone: a ready snapshot of that row; snapshot: any snapshot of the company's websites. At least 1.
emptyclonebranchsnapshotA CoreCluster site's environment: a tier the package offers (default the production row's). Up to 16 characters.
A CoreStack site's environment: a size from corestack_uat_sizes_list. Up to 16 characters.
Magento 2 only: {enabled: true|false, version?}. Left out, the environment follows the site: Varnish on at the site's version, or off when the person switched Varnish off on the site. version is one the site's Magento version allows (version_unsupported otherwise); a size with no room for Varnish is varnish_too_small.
Fields
anonymise(boolean; only whilerestore_anywhereandrestore_anonymiseare on): With a snapshot source: anonymise the copied data.
Example call
{
"name": "corestack_environment_create",
"arguments": {
"site_id": 4211,
"name": "Staging",
"source": {
"type": "empty"
}
}
}If it is refused
| Reason | What to do |
|---|---|
ack_required | The change needs the person's acknowledgements first; required[] lists them — confirm with the person, then call again with them. |
invalid_arguments | On source.environment_id or source.snapshot_id (message: "This WordPress site is built with Bedrock, so it can only be copied to a site that deploys the same way. For a staging copy, use a branch (Git) environment."): a new environment made from a copy deploys manually, and a WordPress site built with Bedrock that deploys from Git is not copied into one. Create a branch environment instead (source.type branch with data_from_environment_id for the data). A copy of the database alone (scope db) is not refused for this. |
snapshot_transfer | On source.snapshot_id (message: "A saved snapshot can be copied only to an environment on the same servers for now, and these two environments are on different servers. Copy the live environment instead, or restore the snapshot to an environment on the same servers."): with source.type clone, the new environment would run on other servers than the row the snapshot was taken from (a staging tier of its own, for example), and a saved snapshot is not copied across. corestack_site_clone_preview with no target lists it in blockers first. Tell the person they can copy the live environment instead (leave out source.snapshot_id), or restore the snapshot to an environment on the same servers. Nothing was created. Where it is switched on and both servers can, a saved snapshot on other servers is sent to the new environment's servers first instead: the answer's source.transport reads sent_local, and the new environment's size must leave room on those servers for the snapshot too. snapshot_transfer stays for a snapshot the servers cannot send. |
feature_off | An input needs a feature that is switched off (for example apply: "tonight" while the maintenance window queue is switched off); leave that input out. |
demo_keep_required | The site or cluster is a free demo that is not kept yet, and an extra priced environment costs money: it starts once the demo is kept. Ask the person to keep it (corestack_demo_keep, or open keep_url); change names this change and what it would cost a month once kept. |
managed_elsewhere | Another control panel manages this site, so environments are added there. This is refused before anything else about the site is checked, as in the Control Panel and the API. Nothing was created. |
rate_limited | The person has added as many environments this minute as the limit allows (60 by default, shared with the Control Panel and the API; changing an environment's settings has a limit of its own). A create that is refused does not count. Wait retry_after_seconds, then call again. |
tenant_mismatch | The object does not exist or the token may not see it. Check the id. |
scope_required | The token lacks a scope this call needs. Open the link in the answer to add it, then call again. |
pin_refused | The grant is limited to chosen clusters, sites or environments, and this call is outside them. Open the link in the answer to widen it. |
temporarily_unavailable | The Control Panel could not answer just now. Nothing was started; try again shortly. |
internal_error | Something went wrong on our side. Quote the trace id to support. |