Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Connect to data sourcesbreadcrumb arrow Private data source connect (PDC)breadcrumb arrow PDC agent CLI reference
Grafana Cloud

PDC agent CLI reference

This document provides a reference for all command-line flags available when running the PDC agent.

Usage

Bash 
pdc [FLAGS]

Replace [FLAGS] with one or more of the flags described below.

Required flags

The following flags are required to connect the PDC agent to Grafana Cloud.

FlagDescription
-tokenThe token to authenticate with Grafana Cloud. It must have the pdc-signing:write scope.
-gcloud-hosted-grafana-idThe ID of the Hosted Grafana instance to connect to.
-clusterThe PDC cluster to connect to. This value is displayed in the Grafana UI under Connections > Private data source connections > Configuration Details.

Optional flags

The following flags are optional and can be used to customize the PDC agent behavior.

FlagDefaultDescription
-log.levelinfoThe log level. Valid values: debug, info, warn, error.
-ssh-key-file~/.ssh/grafana_pdcThe path to the SSH key file.
-ssh-flag-Additional flags to pass to ssh. Can be set multiple times to pass multiple flags.
-connections1The number of parallel SSH connections to open. Adding more connections increases total bandwidth to your network. The limit is 50 connections across all your agents.
-metrics-addr:8090The HTTP server address to expose metrics on.
-parse-metricstrueEnable or disable parsing of metrics from the SSH logs.
-skip-ssh-validationfalseIgnore OpenSSH minimum version constraints. Using this flag is not recommended for production environments.
-force-key-file-overwritefalseForce a new SSH key pair to be generated.
-cert-expiry-window5mThe time before the certificate expires to renew it.
-cert-check-expiry-period1mHow often to check certificate validity. Set to 0 to only check at startup.
-retrymax4The maximum number of retries for HTTP requests to the PDC API.
-domaingrafana.netThe domain of the PDC cluster.
-api-fqdn-FQDN for the PDC API. If set, takes precedence over the -cluster and -domain flags.
-gateway-fqdn-FQDN for the PDC Gateway. If set, takes precedence over the -cluster and -domain flags.
-region-formatfalseUse the new region format for API and Gateway URLs (private-datasource-connect-api.{cluster}.{domain} instead of private-datasource-connect-api-{cluster}.{domain}).

Environment variables

The required flags can also be set using environment variables. If both an environment variable and a flag are set, the flag takes precedence.

Environment variableEquivalent flag
GCLOUD_PDC_SIGNING_TOKEN-token
GCLOUD_HOSTED_GRAFANA_ID-gcloud-hosted-grafana-id
GCLOUD_PDC_CLUSTER-cluster

Examples

The following examples show common ways to run the PDC agent.

Basic usage

Run the PDC agent with the required flags:

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

Restrict accessible endpoints

Use the -ssh-flag option with the PermitRemoteOpen SSH option to restrict which hosts and ports the PDC agent can connect to:

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'

Enable debug logging

Turn on debug logging to get more information about the PDC agent’s activity, including OpenSSH debug logs:

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

Increase parallel connections

Increase the number of parallel SSH connections to improve throughput:

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

Note

The total number of connections across all PDC agents for a single PDC network is limited to 50. If you need more connections, contact Grafana Support to request an increase.

Increase connection timeout

If the PDC agent intermittently fails to connect to the PDC server, increase the SSH connection timeout:

Bash 
./pdc -token ${GCLOUD_PDC_SIGNING_TOKEN} \
  -cluster ${GCLOUD_PDC_CLUSTER} \
  -gcloud-hosted-grafana-id ${GCLOUD_HOSTED_GRAFANA_ID} \
  -ssh-flag='-o ConnectTimeout=5'

Use environment variables

Instead of passing flags on the command line, set the required values as environment variables:

Bash 
export GCLOUD_PDC_SIGNING_TOKEN="your-token"
export GCLOUD_HOSTED_GRAFANA_ID="your-instance-id"
export GCLOUD_PDC_CLUSTER="your-cluster"

./pdc

Use a custom SSH key file

Specify a custom location for the SSH key file:

Bash 
./pdc -token ${GCLOUD_PDC_SIGNING_TOKEN} \
  -cluster ${GCLOUD_PDC_CLUSTER} \
  -gcloud-hosted-grafana-id ${GCLOUD_HOSTED_GRAFANA_ID} \
  -ssh-key-file=/etc/pdc/keys/grafana_pdc

Production-ready configuration

Combine multiple flags for a production deployment with endpoint restrictions, multiple connections, and increased timeout:

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

Run with Docker

Pass the required flags when running 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}

Or use environment variables:

Bash 
docker run --name pdc-agent \
  -e GCLOUD_PDC_SIGNING_TOKEN=${GCLOUD_PDC_SIGNING_TOKEN} \
  -e GCLOUD_HOSTED_GRAFANA_ID=${GCLOUD_HOSTED_GRAFANA_ID} \
  -e GCLOUD_PDC_CLUSTER=${GCLOUD_PDC_CLUSTER} \
  grafana/pdc-agent:latest

Deploy on Kubernetes

For Kubernetes deployments, refer to Configure private data source connect (PDC) for complete setup instructions, including creating secrets and deployment manifests.