--- title: "Configure private data source connect (PDC) | Grafana Cloud documentation" description: "Learn how to set up, configure, and optimize private data source connect (PDC) for Grafana Cloud." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # 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](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/scalability-and-security/#openssh-92-requirement). - 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](/docs/grafana/latest/datasources/) 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](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/cloud-roles/). ### 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-.grafana.net:22` (SSH tunnel) - `private-datasource-connect-api-.grafana.net:443` (certificate signing) You can find the `` 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..amazonaws.com:443`. Replace `` with the AWS region you are querying. For more details, refer to the [AWS documentation](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). ## 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](https://github.com/grafana/pdc-agent/blob/main/production/kubernetes/pdc-agent-deployment.yaml): Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash kubectl apply -f https://raw.githubusercontent.com/grafana/pdc-agent/main/production/kubernetes/pdc-agent-deployment.yaml ``` #### Option 2 - Using the [pdc-agent](https://github.com/grafana/pdc-agent) Docker [image](https://hub.docker.com/r/grafana/pdc-agent/tags) Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](https://github.com/grafana/pdc-agent/releases/latest). Run the binary: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/troubleshooting/) 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](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/#supported-data-sources) for the full list. 1. Follow the [Add a data source](/docs/grafana/latest/administration/data-source-management/#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`](https://man.openbsd.org/ssh_config.5#PermitRemoteOpen) SSH option with the `-ssh-flag` flag: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/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](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/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: - [AWS PrivateLink](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/pdc-agent-aws-privatelink/) - [Azure Private Link](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/pdc-agent-azure-private-link/) - [GCP Private Service Connect](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/pdc-agent-gcp-psc/) ## 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](#deploy-the-pdc-agent) 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. ## Related documentation - [PDC agent CLI reference](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/pdc-agent-cli-reference/) - [PDC agent metrics](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/pdc-agent-metrics/) - [Optimize data source connections for PDC](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/optimize-data-source-connections/) - [PDC scalability and security](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/scalability-and-security/) - [Troubleshoot PDC](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/troubleshooting/)