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}).
-use-gosshfalseUse the new Go implementation of SSH.

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.

Note

-connections does not work when using -use-gossh.

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'

Note

Use -connect-timeout in conjunction with -use-gossh.

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.