Version 1.10. This version is no longer supported. For information about how to upgrade to version 1.11, seeUpgrading Anthos on bare metalin the 1.11 documentation. For more information about supported and unsupported versions, see theVersion historypage in the latest documentation.
Ensure you have all the necessary credentials before attempting to install Google Distributed Cloud.
Logging into gcloud
Login to gcloud as a user usinggcloud auth application-defaultlogin:
gcloud auth application-default login
You need to have a Project Owner/Editor role to use the automatic API
enablement and Service Account creation features, described below.
You can also add the following IAM roles to the user:
Service Account Admin
Service Account Key Admin
Project IAM Admin
Compute Viewer
Service Usage Admin
Alternatively, if you already have a service account with those roles, run:
Layer 3 connectivity to all cluster node machines.
Access to all cluster node machines through SSH via private keys with passwordless root access. Access can be either direct or through sudo.
Access the control plane VIP.
Node machine prerequisites
The node machines have the following prerequisites:
Their operating system is one of the supported Linux distributions.
The Linux kernel version is 4.17.0 or newer. Ubuntu 18.04 and 18.04.1 are on
Linux kernel version 4.15 and therefore incompatible.
Meet the minimum hardware requirements.
Internet access.
Layer 3 connectivity to all other node machines.
Access the control plane VIP.
Properly configured DNS nameservers.
No duplicate host names.
One of the following NTP services is enabled and working:
chrony
ntp
ntpdate
systemd-timesyncd
A working package manager: apt, dnf, etc.
On Ubuntu, you must disable Uncomplicated Firewall (UFW).
Runsystemctl stop ufwto disable UFW.
On Ubuntu and starting with Google Distributed Cloud 1.8.2, you aren't required
to disable AppArmor. If you deploy clusters using earlier releases of
Google Distributed Cloud disable AppArmor with the following command:systemctl stop apparmor
If you choose Docker as your container runtime, you may use Docker
version 19.03 or later installed. If you don't have Docker installed on your node machines or have an older
version installed, Anthos on bare metal installs Docker 19.03.13 or later
when you create clusters.
If you use the default container runtime, containerd, you don't need Docker,
and installing Docker can cause issues. For more information, see theknown issues.
Prerequisites for disk space depend on the version of clusters
you deploy:
Version 1.10.1 and earlier clusters
Whenever you install Google Distributed Cloud release 1.10.1 or earlier,
ensure that the file systems backing the following directories have the
required capacity and meet the following requirements:
The directories have at least 128 GiB of free storage capacity and
the underlying partitions for the directories have following capacity:
/: 20 GiB (21,474,836,480 bytes)
/var/lib/dockeror/var/lib/containerd, depending on the container
runtime: 30 GiB (32,212,254,720 bytes)
/var/lib/kubelet: 10 GiB (10,737,418,240 bytes)
/mnt/anthos-system: 25 GiB (26,843,545,600 bytes)
/var/lib/etcd: 20 GiB (21,474,836,480 bytes, applicable to control plane nodes only)
The overall disk space is less than 90% utilization.
Version 1.10.2 and later clusters
Starting with release 1.10.2, cluster creation only checks for the required
free space for the Google Distributed Cloud system components. This change
gives you more control on the space you allocate for application workloads.
Whenever you install Google Distributed Cloud release 1.10.2 or later, ensure
that the file systems backing the following directories have the required
capacity and meet the following requirements:
/: 17 GiB (18,253,611,008 bytes).
/var/lib/dockeror/var/lib/containerd, depending on the container
runtime:
30 GiB (32,212,254,720 bytes) for control plane nodes.
10 GiB (10,485,760 bytes) for worker nodes.
/var/lib/kubelet: 500 MiB (524,288,000 bytes).
/var/lib/etcd: 20 GiB (21,474,836,480 bytes, applicable to control plane nodes only).
Regardless of cluster version, the preceding lists of directories can be on
the same or different partitions. If they are on the same underlying
partition, then the space requirement is the sum of the space
required for each individual directory on that partition. For all release
versions, the cluster creation process creates the directories, if needed.
/var/lib/etcdand/etc/kubernetesdirectories are either non-existent or
empty.
In addition to the prerequisites for installing and running Google Distributed Cloud,
customers are expected to comply with relevant standards governing their industry
or business segment, such as PCI DSS requirements for businesses that process
credit cards or Security Technical Implementation Guides (STIGs) for businesses
in the defense industry.
Load balancer machines prerequisites
When your deployment doesn't have a specialized load balancer node pool, you can have worker nodes or control plane nodes build a load balancer node pool. In that case, they have additional prerequisites:
Machines are in the same Layer 2 subnet.
All VIPs are in the load balancer nodes subnet and routable from the gateway of the subnet.
The gateway of the load balancer subnet should listen to gratuitous ARPs to forward packets to the master load balancer.
Google Cloud project prerequisites
Before you install Google Distributed Cloud, enable the following services for your associated GCP project:
anthos.googleapis.com
anthosaudit.googleapis.com
anthosgke.googleapis.com
cloudresourcemanager.googleapis.com
container.googleapis.com
gkeconnect.googleapis.com
gkehub.googleapis.com
iam.googleapis.com
logging.googleapis.com
monitoring.googleapis.com
opsconfigmonitoring.googleapis.com
serviceusage.googleapis.com
stackdriver.googleapis.com
You can also use thebmctltool to enable these services.
Service accounts prerequisites
In production environments, you should create separate service accounts for
different purposes. Google Distributed Cloud needs the following different types
of Google Cloud service accounts depending on their purpose:
To access Container Registry (gcr.io), no special role is required.
To register a cluster in a fleet, grant theroles/gkehub.adminIAM role to
the service account on your Google Cloud project.
To connect to fleets, grant theroles/gkehub.connectIAM role to the
service account on your Google Cloud project.
To send logs and metrics to Google Cloud Observability, grant the following IAM
roles to the service account on your Google Cloud project:
roles/logging.logWriter
roles/monitoring.metricWriter
roles/stackdriver.resourceMetadata.writer
roles/monitoring.dashboardEditor
roles/opsconfigmonitoring.resourceMetadata.writer
You can also use thebmctltool to create these service accounts.
[[["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."],[[["\u003cp\u003eGoogle Distributed Cloud requires specific prerequisites for the workstation running \u003ccode\u003ebmctl\u003c/code\u003e, the node machines, load balancer machines, the Google Cloud project, and service accounts.\u003c/p\u003e\n"],["\u003cp\u003eBefore installation, gather necessary credentials, including private SSH keys for node access, the node machine login name if not using \u003ccode\u003eroot\u003c/code\u003e, and Google Cloud service account keys.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003ebmctl\u003c/code\u003e workstation and node machines need specific operating systems, Docker versions, disk space, network connectivity, and specific software packages, with Ubuntu requiring UFW and potentially AppArmor to be disabled.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Distributed Cloud deployments need to enable several Google Cloud services, such as \u003ccode\u003eanthos.googleapis.com\u003c/code\u003e, \u003ccode\u003econtainer.googleapis.com\u003c/code\u003e, and \u003ccode\u003elogging.googleapis.com\u003c/code\u003e, among others, which can be done manually or using the \u003ccode\u003ebmctl\u003c/code\u003e tool.\u003c/p\u003e\n"],["\u003cp\u003eService accounts for Google Distributed Cloud have specific IAM role requirements depending on their purpose, including accessing Container Registry, registering clusters in a fleet, connecting to fleets, and sending logs and metrics to Google Cloud Observability.\u003c/p\u003e\n"]]],[],null,["# Installation prerequisites overview\n\n\u003cbr /\u003e\n\nGoogle Distributed Cloud has the following sets of installation prerequisites:\n\n- [The prerequisites for the workstation machine running the `bmctl` tool.](#workstation_prerequisites)\n- [The prerequisites for the node machines that are part of the Google Distributed Cloud deployment.](#node_machine_prerequisites)\n- [The prerequisites for the load balancer machines.](#load_balancer_machines_prerequisites)\n- [The prerequisites for the Google Cloud project.](#project_prerequisites)\n- [The prerequisites for your service accounts.](#service_accounts_prerequisites)\n\nIf you use the workstation machine as a cluster node machine, it must meet the prerequisites for both.\n\nBefore you begin\n----------------\n\nDuring installation, you must provide the following credentials:\n\n- The private SSH keys needed to access cluster node machines.\n- If you are not using `root`, the cluster node machine login name.\n- The Google Cloud service account keys. Go to [Creating and managing service account keys](/iam/docs/creating-managing-service-account-keys) to learn more.\n\nEnsure you have all the necessary credentials before attempting to install Google Distributed Cloud.\n\nLogging into gcloud\n-------------------\n\n1. Login to gcloud as a user using `gcloud auth application-default` login: \n\n```\ngcloud auth application-default login\n```\nYou need to have a Project Owner/Editor role to use the automatic API enablement and Service Account creation features, described below. You can also add the following IAM roles to the user:\n - Service Account Admin\n - Service Account Key Admin\n - Project IAM Admin\n - Compute Viewer\n - Service Usage Admin\nAlternatively, if you already have a service account with those roles, run: \n\n```\nexport GOOGLE_APPLICATION_CREDENTIALS=JSON_KEY_FILE\n```\n\u003cvar translate=\"no\"\u003eJSON_KEY_FILE\u003c/var\u003e specifies the path to your service account JSON key file.\n2. Get your Google Cloud project ID to use with cluster creation: \n\n```\nexport CLOUD_PROJECT_ID=$(gcloud config get-value project)\n```\n\nWorkstation prerequisites\n-------------------------\n\nThe `bmctl` workstation must meet the following prerequisites:\n\n- Operating system is the same supported Linux distribution running on the cluster node machines.\n- Docker version 19.03 or later installed.\n- Non-root user is member of`docker` group (for instructions, go to [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)).\n- gcloud installed.\n- More than 50 GiB of free disk space.\n- Layer 3 connectivity to all cluster node machines.\n- Access to all cluster node machines through SSH via private keys with passwordless root access. Access can be either direct or through sudo.\n- Access the control plane VIP.\n\nNode machine prerequisites\n--------------------------\n\nThe node machines have the following prerequisites:\n\n- Their operating system is one of the supported Linux distributions.\n- The Linux kernel version is 4.17.0 or newer. Ubuntu 18.04 and 18.04.1 are on Linux kernel version 4.15 and therefore incompatible.\n- Meet the minimum hardware requirements.\n- Internet access.\n- Layer 3 connectivity to all other node machines.\n- Access the control plane VIP.\n- Properly configured DNS nameservers.\n- No duplicate host names.\n- One of the following NTP services is enabled and working:\n - chrony\n - ntp\n - ntpdate\n - systemd-timesyncd\n- A working package manager: apt, dnf, etc.\n- On Ubuntu, you must disable Uncomplicated Firewall (UFW). Run `systemctl stop ufw` to disable UFW.\n- On Ubuntu and starting with Google Distributed Cloud 1.8.2, you aren't required to disable AppArmor. If you deploy clusters using earlier releases of Google Distributed Cloud disable AppArmor with the following command: `systemctl stop apparmor`\n- If you choose Docker as your container runtime, you may use Docker version 19.03 or later installed. If you don't have Docker installed on your node machines or have an older version installed, Anthos on bare metal installs Docker 19.03.13 or later when you create clusters.\n- If you use the default container runtime, containerd, you don't need Docker,\n and installing Docker can cause issues. For more information, see the\n [known issues](/anthos/clusters/docs/bare-metal/1.10/troubleshooting/known-issues#docker_service).\n\n- Prerequisites for disk space depend on the version of clusters\n you deploy:\n\n **Version 1.10.1 and earlier clusters**\n\n Whenever you install Google Distributed Cloud release 1.10.1 or earlier,\n ensure that the file systems backing the following directories have the\n required capacity and meet the following requirements:\n - The directories have at least 128 GiB of free storage capacity and the underlying partitions for the directories have following capacity:\n - `/`: 20 GiB (21,474,836,480 bytes)\n - `/var/lib/docker` or `/var/lib/containerd`, depending on the container runtime: 30 GiB (32,212,254,720 bytes)\n - `/var/lib/kubelet`: 10 GiB (10,737,418,240 bytes)\n - `/mnt/anthos-system`: 25 GiB (26,843,545,600 bytes)\n - `/var/lib/etcd`: 20 GiB (21,474,836,480 bytes, applicable to control plane nodes only)\n - The overall disk space is less than 90% utilization.\n\n **Version 1.10.2 and later clusters**\n\n Starting with release 1.10.2, cluster creation only checks for the required\n free space for the Google Distributed Cloud system components. This change\n gives you more control on the space you allocate for application workloads.\n Whenever you install Google Distributed Cloud release 1.10.2 or later, ensure\n that the file systems backing the following directories have the required\n capacity and meet the following requirements:\n - `/`: 17 GiB (18,253,611,008 bytes).\n - `/var/lib/docker` or `/var/lib/containerd`, depending on the container runtime:\n - 30 GiB (32,212,254,720 bytes) for control plane nodes.\n - 10 GiB (10,485,760 bytes) for worker nodes.\n - `/var/lib/kubelet`: 500 MiB (524,288,000 bytes).\n - `/var/lib/etcd`: 20 GiB (21,474,836,480 bytes, applicable to control plane nodes only).\n\n | **Note:** The preceding storage/space requirements are for system components only. You may require additional storage depending on the workloads that you plan to deploy.\n\n Regardless of cluster version, the preceding lists of directories can be on\n the same or different partitions. If they are on the same underlying\n partition, then the space requirement is the sum of the space\n required for each individual directory on that partition. For all release\n versions, the cluster creation process creates the directories, if needed.\n- `/var/lib/etcd` and `/etc/kubernetes` directories are either non-existent or\n empty.\n\nIn addition to the prerequisites for installing and running Google Distributed Cloud,\ncustomers are expected to comply with relevant standards governing their industry\nor business segment, such as PCI DSS requirements for businesses that process\ncredit cards or Security Technical Implementation Guides (STIGs) for businesses\nin the defense industry.\n\nLoad balancer machines prerequisites\n------------------------------------\n\nWhen your deployment doesn't have a specialized load balancer node pool, you can have worker nodes or control plane nodes build a load balancer node pool. In that case, they have additional prerequisites:\n\n- Machines are in the same Layer 2 subnet.\n- All VIPs are in the load balancer nodes subnet and routable from the gateway of the subnet.\n- The gateway of the load balancer subnet should listen to gratuitous ARPs to forward packets to the master load balancer.\n\nGoogle Cloud project prerequisites\n----------------------------------\n\nBefore you install Google Distributed Cloud, enable the following services for your associated GCP project:\n\n- `anthos.googleapis.com`\n- `anthosaudit.googleapis.com`\n- `anthosgke.googleapis.com`\n- `cloudresourcemanager.googleapis.com`\n- `container.googleapis.com`\n- `gkeconnect.googleapis.com`\n- `gkehub.googleapis.com`\n- `iam.googleapis.com`\n- `logging.googleapis.com`\n- `monitoring.googleapis.com`\n- `opsconfigmonitoring.googleapis.com`\n- `serviceusage.googleapis.com`\n- `stackdriver.googleapis.com`\n\nYou can also use the `bmctl` tool to enable these services.\n\nService accounts prerequisites\n------------------------------\n\nIn production environments, you should create separate service accounts for\ndifferent purposes. Google Distributed Cloud needs the following different types\nof Google Cloud service accounts depending on their purpose:\n\n- To access Container Registry (`gcr.io`), no special role is required.\n- To register a cluster in a fleet, grant the `roles/gkehub.admin` IAM role to the service account on your Google Cloud project.\n- To connect to fleets, grant the `roles/gkehub.connect` IAM role to the service account on your Google Cloud project.\n- To send logs and metrics to Google Cloud Observability, grant the following IAM\n roles to the service account on your Google Cloud project:\n\n - `roles/logging.logWriter`\n - `roles/monitoring.metricWriter`\n - `roles/stackdriver.resourceMetadata.writer`\n - `roles/monitoring.dashboardEditor`\n - `roles/opsconfigmonitoring.resourceMetadata.writer`\n\nYou can also use the `bmctl` tool to create these service accounts."]]
