Sign in to projects

Access your workloads through the GDCH console or the gdcloud CLI.

To sign in to the GDCH console or a cluster, work through the following steps:


Open the following URL in a new browser tab to access the Distributed Cloud Hosted user interface (UI):


Replace GDCH_URL with the domain name you use to access Distributed Cloud Hosted that the Infrastructure Operator (IO) provides. When opening any URL for the first time, GDCH redirects you to your identity provider login page if the Infrastructure Operator (IO) configured the page.

For example, the following image signs in to the console UI for an organization named org-1:

Console UI showing welcome screen for org-1 project.


You can sign in to any cluster that you have permission to access. The CLI login process for all clusters is the same. You must only provide the cluster name and its related kubeconfig file, and log in separately to each cluster.

Before you sign in, ensure you do the following:

  • Download the gdcloud CLI binary and install it in your system. For more information, see Download the gdcloud CLI.
  • Set up and initialize the gdcloud CLI default configuration. Make sure to set the correct organization URL, which is used to fetch the login config endpoint. For more information, see gdcloud CLI installation.

To sign in to a cluster, complete the following steps:

  1. Authenticate your gdcloud CLI instance to log in. There are two ways to authenticate:

    • Standard browser login: Use this authentication flow when you have a browser available on your device.

      gdcloud auth login
    • Secondary device login: Use this authentication flow if your primary device does not have a browser available. This flow starts the login on the primary device with no browser access and continues the login with the secondary device that has browser access.

      1. Initiate the login on your primary device with no browser:

        gdcloud auth login --no-browser

        The command in the primary device prints another gdcloud command that you must run on the secondary device in step c.

      2. Complete the login on the secondary device by entering the command printed on the primary device in step a.

    This action opens a browser to log in to the configured identity provider (IdP). Provide the user and password that you set during the initial gdcloud CLI setup to log in.

  2. Export your user identity kubeconfig file as a variable:

    export KUBECONFIG=/tmp/admin-kubeconfig-with-user-identity.yaml
  3. Generate a kubeconfig file with your user identity:

    gdcloud clusters get-credentials CLUSTER_NAME

    A kubeconfig file is generated with your user identity. The following YAML file shows an example:

    apiVersion: v1
    - cluster:
        certificate-authority-data: <REDACTED>
      name: cluster-name
    - context:
        cluster: cluster-name
        user: cluster-name-anthos-default-user
      name: cluster-name-cluster-name-anthos-default-user
    current-context: cluster-name-cluster-name-anthos-default-user
    kind: Config
    preferences: {}
    - name: cluster-name-anthos-default-user
        token: <REDACTED>
  4. To verify that you can access the cluster, log in with the generated kubeconfig file with a user identity:

    kubectl --kubeconfig /tmp/admin-kubeconfig-with-user-identity.yaml version

Sign out

To sign out of the GDCH console, do the following:


Click Logout in the menu bar.


Log out from the CLI:

gdcloud auth revoke

Session inactivity logout

After fifteen or more minutes of inactivity in a session, the GDCH console and gdcloud CLI logs you out. GDCH considers session inactivity as a period during an open session with no active engagement from you, such as no cursor or keyboard movement. An active session lasts up to twelve hours with user activity.


For session inactivity, the GDCH console logs you out. Two minutes before the GDCH console logs you out for inactivity, you receive a dialog that cautions you of the logout:

Console UI showing dialog with a timer of 99 seconds before logging out user for inactivity.

After logging you out for inactivity, you see the following screen:

Console UI showing login screen with a banner containing text on the session log out: 'You have been logged out of the system because your session was inactive for too long. Please log in again or reach out to your administrator for assistance.'

To log back in to the GDCH console, select your identity provider and add your login credentials. If you use a service, such as the monitoring dashboard, and the GDCH console logs you out for inactivity, log back in to gain access.


For session inactivity, the gdcloud CLI logs you out. After the gdcloud CLI logs you out, and you attempt to run a command, you receive an authorization error:

Error: error when creating kube client: unable to create k8sclient: Unauthorized

To log back in to the gdcloud CLI, follow the CLI steps in Sign in.


The gdcloud CLI expires your kubeconfig files after session inactivity. If you attempt to run a kubectl command after inactivity, you receive an authorization error:

error: You must be logged in to the server (Unauthorized)

To log back in and use your kubeconfig file, follow the CLI steps in Sign in. For every session timeout, you must regenerate your kubeconfig files.