Service Instance Migration

This document describes how to transition from an a9s Prometheus 2 Service Instance to an a9s Prometheus 3 Service Instance. For information about migrating between a9s Prometheus 2 Service Instances, refer to Migration within a9s Prometheus 2 Service Instances.

No In-Place Upgrade

a9s Prometheus 3 is a new version of the a9s Prometheus Data Service. There is no supported migration path or in-place upgrade from a9s Prometheus 2 to a9s Prometheus 3. You must provision a new a9s Prometheus 3 Service Instance independently.

Data and Configuration Migration

• Historical metrics data (the Prometheus TSDB) is not carried over. The new Service Instance starts with an empty time-series database. Metrics previously stored in the a9s Prometheus 2 Service Instance will not be migrated to the a9s Prometheus 3 Service Instance.
• Custom Grafana dashboards from the old Service Instance must be migrated manually to the new Service Instance. Default dashboards that have not been modified do not require migration.
• Custom Grafana alerts, including alert rules, contact points, notification policies, silences, and groups cannot be imported directly into the new Service Instance. Refer to the official Grafana Alerting documentation to manually migrate your custom alerts.
• Several Grafana plugins that were previously available in a9s Prometheus 2 are no longer available in a9s Prometheus 3. Dashboards that rely on any of these plugins must be updated during migration. The removed plugins are:
  • Grafana Status Panel
  • Clock Panel
  • Diagram Panel
  • Worldmap Panel
  • Worldping App
  • Histogram Panel

See Migrate Grafana Dashboards for the dashboard migration steps.

Prerequisites

• Access to the Cloud Foundry CLI.
• Access to the Grafana UI of both the origin and destination a9s Prometheus Service Instances.
• Review the Known Issues page before proceeding.

tip

For a full list of changes in Prometheus 3, refer to the Prometheus 3.0 migration guide.

Existing custom properties (for example, custom scrape configurations) are not automatically transferred to the new Service Instance. You must retrieve the custom parameters set on your a9s Prometheus 2 Service Instance and re-apply them to the new a9s Prometheus 3 Service Instance.

Custom Properties May Require Changes

Prometheus 3 introduces behavioral changes that may affect your existing custom configurations, such as the requirement for scrape_protocol and limitations in credential forwarding on HTTP redirects. Therefore, before re-applying your custom parameters, review the Prometheus 3 Caveats section on the Custom Parameters page.

To retrieve the custom parameters of your existing Service Instance, see Getting a Custom Parameter for a Service Instance. Once retrieved, pass them directly when creating your new Service Instance using cf create-service -c (see Create a New a9s Prometheus 3 Destination Instance).

Before Migrating

There are some preliminary steps required before the migration can take place.

Export Grafana Dashboards from the Origin Instance

Before decommissioning your a9s Prometheus 2 Service Instance, export any custom Grafana dashboards you want to keep.

1. Open the Grafana UI of your a9s Prometheus 2 Service Instance (see Accessing the Dashboards).
2. Navigate to the dashboard you want to export.
3. Click the Share icon (or go to Dashboard Settings).
4. Select Export and choose Save to file to download the dashboard JSON.
5. Repeat for each custom dashboard.

tip

Only dashboards you created or modified need to be exported. The anynines-provided dashboard templates will be available on the new Service Instance as well.

Create a New a9s Prometheus 3 Destination Instance

Create a new a9s Prometheus 3 Service Instance that will be the target for the migration:

cf create-service a9s-prometheus <prometheus3-plan-name> <new-service-instance-name> -c '<custom-parameters-json>'

If no custom parameters need to be applied, omit the -c flag:

cf create-service a9s-prometheus <prometheus3-plan-name> <new-service-instance-name>

Wait for the Service Instance to be created. You can check the status of your Service Instance via the following command:

cf service <new-service-instance-name>

note

• Do not make configuration changes to the new Service Instance before the dashboard import is complete.
• Create a Service Instance with at least the same capabilities (plan size) as the origin.

Migrate Grafana Dashboards

Import the previously exported Grafana dashboards into the new a9s Prometheus 3 Service Instance:

1. Open the Grafana UI of the new a9s Prometheus 3 Service Instance.
2. Click Dashboards in the side menu and select Import.
3. Upload the dashboard JSON files exported in the previous step.
4. Verify that the imported dashboards render correctly.

note

Since the new Service Instance starts with no historical data, dashboards will initially show data only from the point the new Service Instance began scraping.

Rebind Applications

If you have applications bound to the old a9s Prometheus 2 Service Instance, unbind them and bind to the new Service Instance:

cf unbind-service <app-name> <old-service-instance-name>
cf bind-service <app-name> <new-service-instance-name>
cf restage <app-name>

Verify the Migration

1. Verify the Service Instance is running: Check that the new Service Instance status is create succeeded.

   cf service <new-service-instance-name>

2. Verify metrics collection: Confirm that the a9s Prometheus 3 Service Instance is scraping targets and collecting metrics as expected. You can check this through the Prometheus UI or by querying the up metric.

3. Verify alert rules: Confirm that alert rules are evaluated correctly. Check the Prometheus UI under "Alerts" to see the status of alerting rules.

4. Verify Grafana dashboards: Confirm that the imported dashboards display data correctly.

Decommission the Old Instance

Once you have confirmed that the new Service Instance is working correctly and all dashboards have been migrated, delete the old a9s Prometheus 2 Service Instance:

cf delete-service <old-service-instance-name>

Placeholder Values

Placeholder	Description
<prometheus3-plan-name>	The name of the target a9s Prometheus 3 service plan.
<new-service-instance-name>	The name for the new a9s Prometheus 3 Service Instance.
<custom-parameters-json>	A JSON string with the custom parameters retrieved from the origin Service Instance.
<old-service-instance-name>	The name of the existing a9s Prometheus 2 Service Instance.
<app-name>	The name of an application bound to the origin Service Instance.

Migration within a9s Prometheus 2 Service Instances

Plan compatibility when migrating between a9s Prometheus 2 Service Instances

When migrating your a9s Prometheus 2 Service Instances, you can only use a destination service plan that has the exact same resources as the origin service plan (e.g. from a -small plan to another -small plan).