DOCS-10140 The datadog-sync-cli tool #29456
Conversation
Preview links (active after the
|
📝 Documentation Team Review RequiredThis pull request requires approval from the @DataDog/documentation team before it can be merged. Please ensure your changes follow our documentation guidelines and wait for a team member to review and approve your changes. |
|
|
||
| Datadog recommends syncing your accounts on a daily basis. | ||
|
|
||
| <div class="alert alert-warning"> <strong>Note:</strong> The <code>datadog-sync-cli</code> tool is used to migrate resources across organizations, regardless of datacenter. It cannot, nor is it intended to, transfer any ingested data, such as logs, metrics etc. The source organization will not be modified, but the destination organization will have resources created and updated by the <code>sync</code> command.</div> |
There was a problem hiding this comment.
The resources can also be removed at the destination organization. If you delete a dashboard in your primary then it can be deleted in your secondary also.
| {{% /collapse-content %}} | ||
|
|
||
| {{% collapse-content title="List of supported API URLs" level="h5" expanded=true id="id-for-resources" %}} | ||
| These are the supported URLs for the source and destination API URLs when syncing your organization: `IS AP2 SUPPORTED?` AND `HOW DOES IT WORK EXACTLY WITH THE GOV SITE SINCE DATA IS SPECIFIC TO THAT SITE?` |
There was a problem hiding this comment.
AP2 should be supported, but I've admittedly not tested it.
Gov cloud is not yet supported and should be removed from the list below.
|
|
||
| 3. Invoke the CLI tool using `WHAT'S AN EXAMPLE TO ADD HERE FOR <command> <options>` | ||
| ```shell | ||
| datadog-sync <command> <options> |
There was a problem hiding this comment.
I think the migrate command is a good example.
datadog-sync migrate --config CONFIG_FILE --cleanup=true
|
|
||
| <div class="alert alert-warning"> <strong>Note:</strong> The sync-cli tool uses the <code>resources</code> directory as the source of truth for determining what resources need to be created and modified. This directory <strong>should not be removed or corrupted</strong>.</div> | ||
|
|
||
| ### Steps to sync your resources |
There was a problem hiding this comment.
You might just switch from describing import/sync and just focus on migrate since it does both.
| 1. Run the `import` command to read the specified resources from the source organization and store them locally into JSON files in the directory `resources/source`. | ||
|
|
||
| 2. Run the `sync` command to use the stored files from the previous `import` command (unless the `--force-missing-dependencies` flag is passed) to create or modify the resources on the destination organization. The pushed resources are saved in the directory `resources/destination`. | ||
| - (`WHAT DOES THE --force-missing-dependencies DO IN THIS CASE?`) |
There was a problem hiding this comment.
It creates any missing dependencies. For example if you do datadog-sync migrate --resources="dashboards" --force-missing-dependencies and there is a dashboard that relies on SLOs, then it will pull those SLOs from the source and create them at the destination even though you didn't specify SLOs in your list of resources.
| 3. The `migrate` command runs an `import` followed immediately by a `sync`. | ||
|
|
||
| 4. The `reset` command deletes resources at the destination; however, by default it backs up those resources first and fails if it cannot back them up. | ||
| - **NOT recommended:** The back-up step can be skipped using the `--do-not-backup` flag. |
There was a problem hiding this comment.
Maybe don't mention this at all?
|
|
||
| #### SubString and ExactMatch Deprecation | ||
|
|
||
| In future releases (`IN WHICH RELEASES IS THIS AVAILABLE?`) the `SubString` and `ExactMatch` Operator will be removed in favor of the `Value` key. This is because the `Value` key supports regex so both of these scenarios are covered by just writing the appropriate regex. |
There was a problem hiding this comment.
Maybe we should remove all references to deprecated values. We're writing new docs for usage going forward so I don't think it makes sense to include them in our recommended way of doing things. It only makes sense to document them for people already using the tool for other purposes, imo.
What does this PR do? What is the motivation?
This creates a documentation for the Datadog cli tool.
Merge instructions
Merge readiness:
For Datadog employees:
Merge queue is enabled in this repo. Your branch name MUST follow the
<name>/<description>convention and include the forward slash (/). Without this format, your pull request will not pass in CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.If your branch doesn't follow this format, rename it or create a new branch and PR.
To have your PR automatically merged after it receives the required reviews, add the following PR comment:
Additional notes