Stay organized with collections
Save and categorize content based on your preferences.
This page contains an overview of the Distributed Cloud CLI, and
instructions on how to download and configure it for usage with
GDC Sandbox.
Overview of the gdcloud CLI
The gdcloud CLI is a set of tools to create and manage
Google Distributed Cloud (GDC) air-gapped resources.
It is available for Linux only.
Use these tools to perform common tasks from the
command line or through scripts and automation. The gdcloud CLI can be used to
bootstrap infrastructure, manage authentication, and customize local
configurations. Note that this is distinct from the gcloud CLI used to manage
Google Cloud.
This page contains simplified instructions that are specific to
GDC Sandbox. For more detail on the gdcloud CLI in general, including
configuration, upgrade, autocomplete, and accessibility, see the
GDC air-gapped gdcloud documentation.
Download the gdcloud CLI
Follow these instructions if you are connecting to the GDC Sandbox using
sshuttle. If you are connecting to your instance's gateway over remote desktop,
there is no need to download the tool, as gdcloud is pre-installed on the
gateway machine at the path /usr/share/gdcloud.
Download the gdcloud CLI bundle from the GDC console.
Add the gdcloud CLI to your PATH so that you don't have to specify
the location with every command. The following command assumes the CLI
bundle was downloaded and extracted to the user's Downloads directory, and
that the user's shell profile lives in ~/.bashrc.
The gdcloud requires authentication in order to perform commands. To use it
with GDC Sandbox, start by downloading a certificate from the
GDC Sandbox instance.
Retrieve the certificate to authorize sign in. The following command
downloads the certificate to the /tmp folder; you can choose
to download it wherever you prefer.
This command opens a browser window to the OIDC portal. Select
fake OIDC Provider, and Platform Admin again (or whatever user you
want to use for development, make sure you give the right access to the
role).
Repeat this authentication step as needed, when the session times out.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Set up the gdcloud CLI\n\nThis page contains an overview of the Distributed Cloud CLI, and\ninstructions on how to download and configure it for usage with\nGDC Sandbox.\n\nOverview of the gdcloud CLI\n---------------------------\n\nThe gdcloud CLI is a set of tools to create and manage\nGoogle Distributed Cloud (GDC) air-gapped resources.\nIt is available for Linux only.\nUse these tools to perform common tasks from the\ncommand line or through scripts and automation. The `gdcloud` CLI can be used to\nbootstrap infrastructure, manage authentication, and customize local\nconfigurations. Note that this is distinct from the `gcloud` CLI used to manage\nGoogle Cloud.\n\nThis page contains simplified instructions that are specific to\nGDC Sandbox. For more detail on the gdcloud CLI in general, including\nconfiguration, upgrade, autocomplete, and accessibility, see the\n[GDC air-gapped `gdcloud` documentation](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-overview).\n\nDownload the gdcloud CLI\n------------------------\n\nFollow these instructions if you are connecting to the GDC Sandbox using\n`sshuttle`. If you are connecting to your instance's gateway over remote desktop,\nthere is no need to download the tool, as `gdcloud` is pre-installed on the\ngateway machine at the path `/usr/share/gdcloud`.\n\n1. Download the gdcloud CLI bundle from the GDC console.\n 1. Navigate to your GDC console as described in [Connect to your instance](/distributed-cloud/sandbox/latest/connect).\n 2. Navigate to the **Connect with CLI** section.\n 3. Click **Download CLI Bundle**.\n2. In a terminal window, extract the CLI bundle:\n\n cd ~/Downloads\n tar -xf gdcloud_cli.tar.gz\n\n3. Add the `gdcloud` CLI to your PATH so that you don't have to specify\n the location with every command. The following command assumes the CLI\n bundle was downloaded and extracted to the user's `Downloads` directory, and\n that the user's shell profile lives in `~/.bashrc`.\n\n echo 'export PATH=$PATH:~/Downloads/google-distributed-cloud-hosted-cli/bin' \u003e\u003e ~/.bashrc\n source ~/.bashrc\n\n4. Open a new terminal and run `gdcloud version` to confirm the command\n worked.\n\n5. Install the `auth` plugin. This plugin is required for using the kubeconfigs generated through the CLI.\n\n gdcloud components install gdcloud-k8s-auth-plugin\n\nConfigure gdcloud\n-----------------\n\n1. Configure the CLI by setting the organization URL to the URL of the\n GDC console.\n\n gdcloud config set core/organization_console_url https://console.org-1.zone1.google.gdch.test\n\n### Download the certificate\n\nThe gdcloud requires authentication in order to perform commands. To use it\nwith GDC Sandbox, start by downloading a certificate from the\nGDC Sandbox instance.\n\n1. Retrieve the certificate to authorize sign in. The following command\n downloads the certificate to the `/tmp` folder; you can choose\n to download it wherever you prefer.\n\n echo -n | \\\n openssl s_client -showcerts -connect console.org-1.zone1.google.gdch.test:443 | \\\n sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' \u003e /tmp/org-1-web-tls-ca.cert\n\nAuthenticate with gdcloud\n-------------------------\n\n1. Sign in to the gdcloud CLI, using the downloaded certificate. The\n following example assumes that the cert was downloaded into the\n `/tmp` folder.\n\n gdcloud auth login --login-config-cert=/tmp/org-1-web-tls-ca.cert\n\n This command opens a browser window to the OIDC portal. Select\n **fake OIDC Provider** , and **Platform Admin** again (or whatever user you\n want to use for development, make sure you give the right access to the\n role).\n\n Repeat this authentication step as needed, when the session times out."]]
