--- title: "PDC agent CLI reference | Grafana Cloud documentation" description: "Command-line flags and options for the PDC agent." --- # PDC agent CLI reference This document provides a reference for all command-line flags available when running the PDC agent. ## Usage Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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. Expand table | Flag | Description | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-token` | The token to authenticate with Grafana Cloud. It must have the `pdc-signing:write` scope. | | `-gcloud-hosted-grafana-id` | The ID of the Hosted Grafana instance to connect to. | | `-cluster` | The 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. Expand table | Flag | Default | Description | |-----------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-log.level` | `info` | The log level. Valid values: `debug`, `info`, `warn`, `error`. | | `-ssh-key-file` | `~/.ssh/grafana_pdc` | The path to the SSH key file. | | `-ssh-flag` | \- | Additional flags to pass to ssh. Can be set multiple times to pass multiple flags. | | `-connections` | `1` | The 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` | `:8090` | The HTTP server address to expose metrics on. | | `-parse-metrics` | `true` | Enable or disable parsing of metrics from the SSH logs. | | `-skip-ssh-validation` | `false` | Ignore OpenSSH minimum version constraints. Using this flag is not recommended for production environments. | | `-force-key-file-overwrite` | `false` | Force a new SSH key pair to be generated. | | `-cert-expiry-window` | `5m` | The time before the certificate expires to renew it. | | `-cert-check-expiry-period` | `1m` | How often to check certificate validity. Set to `0` to only check at startup. | | `-retrymax` | `4` | The maximum number of retries for HTTP requests to the PDC API. | | `-domain` | `grafana.net` | The 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-format` | `false` | Use 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. Expand table | Environment variable | Equivalent 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 ![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} ``` ### 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 ![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' ``` ### Enable debug logging Turn on debug logging to get more information about the PDC agent’s activity, including OpenSSH debug logs: 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 ``` ### Increase parallel connections Increase the number of parallel SSH connections to improve throughput: 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 ``` > 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](/docs/grafana-cloud/security-and-account-management/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 ![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 ConnectTimeout=5' ``` ### Use environment variables Instead of passing flags on the command line, set the required values as environment variables: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![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-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 ![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 \ -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 ![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} ``` Or use environment variables: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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)](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/configure-pdc/) for complete setup instructions, including creating secrets and deployment manifests. ## Related documentation - [Configure private data source connect (PDC)](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/configure-pdc/) - Setup and deployment instructions - [Troubleshoot PDC](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/troubleshooting/) - Common errors, log interpretation, and exit codes - [PDC agent metrics](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/pdc-agent-metrics/) - Available Prometheus metrics - [PDC scalability and security](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/scalability-and-security/) - Resource requirements and security considerations