mirror of
https://github.com/Unleash/unleash.git
synced 2025-09-24 17:51:14 +02:00
Add Prometheus clarificationa and troubleshooting
This commit is contained in:
melindafekete
parent
12a748c55d
commit
262184d4ec
@ -4,25 +4,42 @@ title: 'How to synchronize Unleash instances'
|
||||
|
||||
:::note
|
||||
|
||||
This is an experimental feature
|
||||
This is an experimental feature.
|
||||
|
||||
:::
|
||||
|
||||
# Unleash Instance Synchronization Script
|
||||
# Unleash instance synchronization script
|
||||
|
||||
This script allows you to synchronize feature flags between two Unleash instances using the export and import APIs provided by Unleash. The script exports feature flags from the source instance and imports them into the target instance.
|
||||
|
||||
For one-off full instance migrations, we recommend a [database dump/restore](/using-unleash/deploy/configuring-unleash#back-up-and-restore-the-database) (`pg_dump` / `pg_restore`) instead.
|
||||
|
||||
You can find this script in the following location within the project:
|
||||
|
||||
`scripts/promote.sh`
|
||||
|
||||
This script can also be integrated into a continuous deployment pipeline, allowing you to automatically synchronize feature flags between instances at a frequency determined by your pipeline configuration.
|
||||
|
||||
:::warning
|
||||
If you have any segments or custom strategies defined, you must first manually create these in the target instance.
|
||||
:::
|
||||
|
||||
Feature flags are imported with full configuration, including:
|
||||
- [Activation strategies](/reference/activation-strategies)
|
||||
- [Context fields](/reference/unleash-context)
|
||||
- [Strategy variants](/reference/strategy-variants)
|
||||
- [Tags](/reference/feature-toggles#tags)
|
||||
- [Feature flag state](/reference/feature-toggles#feature-flag-state)
|
||||
- [Feature dependencies](/reference/feature-toggles#feature-flag-dependencies)
|
||||
- [Feature flag links](/reference/feature-toggles#external-links)
|
||||
|
||||
If a feature flag already exists in your target instance, it will be overwritten.
|
||||
|
||||
## Configuration
|
||||
|
||||
To synchronize two Unleash instances, you need to configure each instance with the required settings. The script requires the following configuration:
|
||||
|
||||
### Source Unleash Instance
|
||||
### Source Unleash instance
|
||||
|
||||
- `SOURCE_URL`: The URL of the source Unleash API.
|
||||
Example: `SOURCE_URL="http://localhost:4242/api/admin/features-batch/export"`
|
||||
@ -31,7 +48,7 @@ To synchronize two Unleash instances, you need to configure each instance with t
|
||||
- `SOURCE_ENV`: The environment name for the source instance. Only feature flags matching this environment will be exported.
|
||||
- `SOURCE_TAG`: The tag to filter feature flags for export.
|
||||
|
||||
### Target Unleash Instance
|
||||
### Target Unleash instance
|
||||
|
||||
- `TARGET_URL`: The URL of the target Unleash API.
|
||||
Example: `TARGET_URL="http://localhost:4242/api/admin/features-batch/import"`
|
||||
@ -55,16 +72,9 @@ The script prints each step of the export and import process, providing feedback
|
||||
|
||||
Here are some common issues you might encounter and how to resolve them:
|
||||
|
||||
1. Make sure you use the correct URLs for the source and target instances.
|
||||
2. Ensure that the API tokens have the necessary permissions to perform export and import operations.
|
||||
3. Verify that the specified source and target environments exist.
|
||||
4. Check that the target project exists.
|
||||
5. If you have change requests enabled in the target project, ensure that there are no pending change requests for the same API token.
|
||||
|
||||
:::info Feedback wanted
|
||||
|
||||
If you would like to give feedback on this feature, experience issues or have questions, please feel free to open an issue on [GitHub](https://github.com/Unleash/unleash/).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
- Check that you use the correct URLs for the source and target instances.
|
||||
- Ensure that the API tokens have the necessary permissions to perform export and import operations.
|
||||
- Verify that the specified source and target environments exist.
|
||||
- Check that the target project exists.
|
||||
- If you have change requests enabled in the target project, ensure that there are no pending change requests for the same API token.
|
||||
- Check that any custom strategies or segments have been migrated manually.
|
||||
|
||||
@ -54,19 +54,32 @@ You can also compare your usage in previous months with the current month.
|
||||
|
||||
## Configure a data source
|
||||
|
||||
To populate the **Network** dashboard with data, you can integrate with [Prometheus](https://prometheus.io/), or similar tools.
|
||||
To populate the Network dashboards, Unleash needs to read metrics from a Prometheus-compatible HTTP API (for example, Prometheus or VictoriaMetrics).
|
||||
|
||||
The network view relies on an external Prometheus-compatible API for generating diagrams. You must set the `PROMETHEUS_API` environment variable to the base path of the Prometheus installation.
|
||||
For this, you need to set up a two-way flow between Unleash and a Prometheus-compatible monitoring system:
|
||||
- Prometheus scrapes Unleash at /internal-backstage/prometheus.
|
||||
- Unleash queries Prometheus (via `PROMETHEUS_API`) to render the dashboards.
|
||||
|
||||
### Configure Prometheus to scrape metrics from Unleash
|
||||
|
||||
First, you must configure your Prometheus instance to pull metrics from Unleash's backstage API endpoint.
|
||||
|
||||
Add the following scrape job to your Prometheus configuration file (for example, `prometheus.yml`). Replace 'your-unleash-url' with the base URL of your Unleash instance.
|
||||
|
||||
```yaml
|
||||
- job_name: unleash_internal_metrics
|
||||
metrics_path: /internal-backstage/prometheus
|
||||
static_configs:
|
||||
- targets: ['unleash-url']
|
||||
- job_name: unleash_internal_metrics
|
||||
metrics_path: /internal-backstage/prometheus
|
||||
static_configs:
|
||||
- targets: ['your-unleash-url']
|
||||
```
|
||||
|
||||
You can configure Prometheus to retrieve data from the Unleash [internal backstage API](api/legacy/unleash/internal/prometheus), such as through a scraping job.
|
||||
|
||||
This setup creates a mutual dependency where Prometheus fetches data from Unleash's backstage API, and Unleash retrieves the data from Prometheus and displays it in the **Network** dashboards.
|
||||
This job tells Prometheus to periodically fetch metrics from the `/internal-backstage/prometheus` path on your Unleash server.
|
||||
|
||||
|
||||
### Configure Unleash to query data from Prometheus
|
||||
|
||||
Set the `PROMETHEUS_API` environment variable in your Unleash instance to the base URL of your Prometheus-compatible query API. This URL must be network-accessible from your Unleash instance. It can be an internal service name (such as `http://prometheus.monitoring.svc.cluster.local`) or a public URL.
|
||||
|
||||
```bash
|
||||
PROMETHEUS_API=http://vmselect-unleash-vm.victoriametrics:8481/select/0:0/prometheus
|
||||
```
|
||||
|
||||
@ -164,4 +164,12 @@ This ensures that the user's permissions are managed solely within Unleash and w
|
||||
|
||||
### What if I'm already locked out?
|
||||
|
||||
If you've already enabled SCIM and lost all admin access, please contact our support team. We can create a temporary admin user for you while you correct your SCIM configuration.
|
||||
If you've already enabled SCIM and lost all admin access, please contact our support team. We can create a temporary admin user for you while you correct your SCIM configuration.
|
||||
|
||||
## My Network Tab is empty, and I don't see any data.
|
||||
|
||||
[This issue](/reference/network-view/configure-a-data-source) is most commonly caused by an incorrect `PROMETHEUS_API` URL:
|
||||
|
||||
- Verify the `PROMETHEUS_API` environment variable: Ensure it points to your Prometheus server and not to your Unleash URL. Pointing it back to Unleash (e.g., https://unleash.example.com/internal-backstage/prometheus) is incorrect and will result in an empty dashboard.
|
||||
|
||||
- Check network connectivity: Confirm that your Unleash instance can reach the Prometheus server URL you provided. You can test this by running a curl command from within the Unleash container or a pod on the same network.
|
||||
@ -132,6 +132,13 @@ It is highly recommended to back up your Unleash database, especially before [up
|
||||
docker exec -i <your_postgres_container_name> psql -U <your_db_user> -d <your_db_name> < <your_backup_file.dump>
|
||||
```
|
||||
|
||||
### Migrate an instance
|
||||
|
||||
If you are moving an instance (for example, to a new cloud provider or cluster) and need full fidelity, use a database [dump and restore](#back-up-and-restore-the-database) instead of API export/import.
|
||||
|
||||
This is the safest way to keep data parity. Use export/import primarily for ongoing synchronization of feature flags, not full migrations.
|
||||
|
||||
|
||||
### Enable self-signed certificates
|
||||
|
||||
To connect to a PostgreSQL database using a self-signed certificate, you need to:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user