Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Connect to data sourcesbreadcrumb arrow Private data source connect (PDC)breadcrumb arrow Configure private data source connect (PDC)
Grafana Cloud
Last reviewed: March 31, 2026

Configure Grafana private data source connect (PDC)

Private data source connect (PDC) enables you to securely connect your Grafana Cloud stack to data sources hosted on a private network.

Before you begin

Before you begin working with private data source connect (PDC), ensure the following:

  • You have the tools you need to deploy the PDC agent within your network. You can deploy it directly to a Linux or Windows server, or use a container management system like Docker or Kubernetes.

  • If you run the PDC agent binary directly on a host, the server must have OpenSSH version 9.2 or higher. The PDC agent Docker image includes a compatible OpenSSH version, so Docker and Kubernetes users can skip this requirement. For more details, refer to the PDC scalability and security page.

  • You know the local host name and port of the data source you want to connect to, for example loki:8080.

  • You have the proper credentials to access the data, for example, a username and password, or a token. Refer to the documentation for your data source to learn what credentials you need.

  • You have an administrator account for your Grafana Cloud organization. To learn more about Grafana Cloud permissions, refer to Grafana Cloud user roles and permissions.

Network requirements

To establish an SSH connection to Grafana Cloud, the PDC agent must run on a network that allows internet egress to the following endpoints:

  • private-datasource-connect-<cluster>.grafana.net:22 (SSH tunnel)
  • private-datasource-connect-api-<cluster>.grafana.net:443 (certificate signing)

You can find the <cluster> value in the Grafana UI under Connections > Private data source connections > Configuration Details.

The PDC agent uses the API endpoint (port 443) to sign short-lived SSH certificates for authentication with the SSH endpoint (port 22).

Note

If your data source uses AWS SigV4 (AWS Signature Version 4 Authentication), the network where the PDC agent runs must also allow internet egress to sts.<region>.amazonaws.com:443. Replace <region> with the AWS region you are querying. For more details, refer to the AWS documentation.

Set up a private data source connection

To set up a private data source connection, deploy the PDC agent, verify it connects, and then configure your data source to route queries through it.

Deploy the PDC agent

  1. In Grafana, go to Connections > Private data source connections. Either choose an existing PDC network or create a new one. Click the Configuration Details tab.

  2. Generate a token and note the following configuration values from the Configuration Details page. You can also follow the guided installation instructions on the screen.

    • GCLOUD_PDC_SIGNING_TOKEN: The API token you generated. It must have the pdc-signing:write scope. The Grafana UI labels this as token.
    • GCLOUD_HOSTED_GRAFANA_ID: Your Grafana Cloud instance ID. The Grafana UI labels this as gcloud-hosted-grafana-id.
    • GCLOUD_PDC_CLUSTER: Your PDC cluster. The Grafana UI labels this as cluster.

  3. Connect to Grafana Cloud using the PDC agent. Choose the installation option that matches your environment:

    • Kubernetes — Your data sources run on or are accessible from a Kubernetes cluster.
    • Docker — You have a Docker host with network access to your data sources.
    • Binary — You want to run the agent directly on a VM or bare-metal host.

Option 1 - Using Kubernetes

Create a Kubernetes secret with the API token, hosted Grafana ID, and PDC cluster values in your desired namespace:

Bash 
kubectl create secret generic grafana-pdc-agent \
  --from-literal="token=${GCLOUD_PDC_SIGNING_TOKEN}" \
  --from-literal="hosted-grafana-id=${GCLOUD_HOSTED_GRAFANA_ID}" \
  --from-literal="cluster=${GCLOUD_PDC_CLUSTER}"

Deploy the agent using the example deployment manifest from the pdc-agent repository:

Bash 
kubectl apply -f https://raw.githubusercontent.com/grafana/pdc-agent/main/production/kubernetes/pdc-agent-deployment.yaml

Option 2 - Using the pdc-agent Docker image

Bash 
docker run --name pdc-agent grafana/pdc-agent:latest \
  -token ${GCLOUD_PDC_SIGNING_TOKEN} \
  -cluster ${GCLOUD_PDC_CLUSTER} \
  -gcloud-hosted-grafana-id ${GCLOUD_HOSTED_GRAFANA_ID}

Option 3 - Use a pdc-agent binary

Download and extract the binary for your OS from the PDC Agent releases page.

Run the binary:

Bash 
./pdc -token ${GCLOUD_PDC_SIGNING_TOKEN} \
  -cluster ${GCLOUD_PDC_CLUSTER} \
  -gcloud-hosted-grafana-id ${GCLOUD_HOSTED_GRAFANA_ID}

Verify the connection

After the PDC agent connects to Grafana Cloud, you see the following message in the agent logs:

This is Grafana Private Data Source Connect!

If you don’t see this message, refer to Troubleshoot PDC for common connection errors and resolution steps.

Note

Updating the agent requires a restart of the PDC agent process, or a rolling update of the deployment when running in Kubernetes.

Configure a data source to use PDC

After you set up the PDC connection, configure a data source in Grafana to query your data.

Before adding a data source, verify that it supports PDC. Refer to Supported data sources for the full list.

  1. Follow the Add a data source instructions.

  2. Under the Private data source connection header, choose the connection to the network where you host your service.

  3. In the URL field, enter the internal hostname and port as you would from within your private network, for example postgres.internal.example.com:5432.

  4. Save, test, and query your data source as usual.

Secure and optimize your PDC setup

After completing the basic setup, consider the following options to harden security, improve throughput, and enable observability for your PDC deployment.

Restrict accessible endpoints

By default, the PDC agent allows Grafana Cloud to connect to any host and port reachable from the agent’s network. To restrict which endpoints Grafana Cloud can access, use the PermitRemoteOpen SSH option with the -ssh-flag flag:

Bash 
./pdc -token ${GCLOUD_PDC_SIGNING_TOKEN} \
  -cluster ${GCLOUD_PDC_CLUSTER} \
  -gcloud-hosted-grafana-id ${GCLOUD_HOSTED_GRAFANA_ID} \
  -ssh-flag='-o PermitRemoteOpen=mysql.example.com:3306 prometheus.example.com:443'

For more configuration options, refer to the PDC agent CLI reference.

High availability

PDC agents can disconnect during rolling updates, host maintenance, or unexpected failures. If you run a single agent, any disruption breaks connectivity to your private data sources until the agent recovers.

To avoid downtime, deploy multiple PDC agents with the same configuration. PDC automatically load balances across all connected agents and reroutes traffic when an agent disconnects.

Tip

For production environments, Grafana recommends running a minimum of 3 PDC agents. Deploy them to different regions, data centers, or availability zones for maximum resilience.

Increase throughput

By default, each PDC agent opens a single SSH connection. If you run high-frequency queries or transfer large volumes of data, that single connection can become a bottleneck. To increase the total bandwidth to your network, use the -connections flag to open multiple parallel SSH connections per agent:

Bash 
./pdc -token ${GCLOUD_PDC_SIGNING_TOKEN} \
  -cluster ${GCLOUD_PDC_CLUSTER} \
  -gcloud-hosted-grafana-id ${GCLOUD_HOSTED_GRAFANA_ID} \
  -connections=3

The total number of connections across all agents in a single PDC network is limited to 50. For more details, refer to the PDC agent CLI reference.

Enable debug logging

If you are troubleshooting connection failures or need to verify what the PDC agent is doing, enable debug logging. This outputs detailed information about the agent’s activity, including OpenSSH debug logs. Set the log level to debug:

Bash 
./pdc -token ${GCLOUD_PDC_SIGNING_TOKEN} \
  -cluster ${GCLOUD_PDC_CLUSTER} \
  -gcloud-hosted-grafana-id ${GCLOUD_HOSTED_GRAFANA_ID} \
  -log.level=debug

For more details, refer to the PDC agent CLI reference.

Resource requirements

For information on resource requirements for the PDC agent and recommendations for how many agents to run, refer to PDC scalability and security.

Cloud private networking

You can connect PDC agents to Grafana Cloud through your cloud provider’s private networking service instead of the public internet to reduce egress costs and improve security:

Connect additional networks

Your Grafana Cloud stack supports multiple PDC networks. Use a separate PDC network for each isolated private network in your infrastructure. PDC load balances requests across all agents connected to a given network.

Tip

If you have multiple data centers that are connected but have high latency or low bandwidth between them, consider using a separate PDC network for each data center. This allows you to choose the most suitable PDC network for each data source.

To add a new network:

  1. In Grafana, go to Connections > Private data source connections and click Add New. Choose a name for your connection and click Add.

  2. Follow the deployment steps to set up and deploy a PDC agent to the additional network.

  3. When you configure a data source, select the new connection in the Private data source connection section.

Monitor PDC activity

Monitoring helps you detect agent disconnections, spot latency increases, and identify failing queries before they affect dashboards or alerts.

Your stack’s grafanacloud-usage data source contains two metrics for tracking PDC activity:

  • grafanacloud_grafana_pdc_connected_agents shows how many PDC agents connect to Grafana Cloud infrastructure for each stack in your organization and each PDC network (using the tunnelID label). Use this metric to alert on unexpected drops in connected agents.

  • grafanacloud_grafana_pdc_datasource_request_duration_seconds_rate5m_p90 shows the p90 request duration for each data source in your stacks that uses PDC. The status_code label indicates whether requests succeeded or failed. Watch for rising latency or increasing error rates.