Console
    Contact Us Start free

    Google Distributed Cloud quickstart

    Introduction to Google Distributed Cloud

    With Google Distributed Cloud, you can define four types of clusters:

    • admin- A cluster used to manage user clusters.
    • user- A cluster used to run workloads.
    • standalone- A single cluster that can administer itself, and that can also run workloads, but can't create or manage other user clusters.
    • hybrid- A single cluster for both admin and workloads, that can also manage user clusters.

    In this quickstart, you deploy a two-node hybrid clusterwith Google Distributed Cloud. You learn how to create a cluster, and how to monitor the cluster creation process.

    This quickstart assumes you have a basic understanding of Kubernetes .

    Prepare for Google Distributed Cloud

    Before creating a cluster in Google Distributed Cloud, you must do the following:

    1. Create a Google Cloud project .
    2. Install Google Cloud CLI .
    3. Configure a Linux admin workstation .
    4. Install the bmctl tool .

    Create a Google Cloud project

    For this quickstart, create a new Google Cloud project that organizes all your Google Cloud resources. To create a cluster in Google Distributed Cloud, you need a Google Cloud project where your account has either of the following roles:

    • Editor
    • Owner

    See Create and manage projects for details.

    Install Google Cloud CLI

    This quickstart uses the kubectl and bmctl tools to create and set up clusters. To install these tools, you need gcloud . Google Cloud CLI includes the gcloud and kubectl command-line tools.

    To install the required tools, complete the following steps:

    1. On your admin workstation, install and initialize Google Cloud CLI using these instructions . This process installs gcloud .
    2. Update Google Cloud CLI: 
      gcloud components update

    3. Log in with your Google account to manage your services and service accounts:

      gcloud auth login --update-adc

      A new browser tab opens and you are prompted to choose an account.

    4. Use gcloud to install kubectl :

      gcloud components install kubectl

    Configure a Linux admin workstation

    After you install gcloud and kubectl , configure a Linux admin workstation. Do not use Cloud Shell as your admin workstation.

    1. Install Docker version 19.03 or later. To learn how to configure Docker, go to the page corresponding to your Linux distribution:
    2. To use root access, set up SSH on both the admin workstation and the remote cluster node machines. Initially, you need root SSH password authentication enabled on the remote cluster node machines to share keys from the admin workstation. Once the keys are in place, you can disable SSH password authentication.
    3. Generate a private/public key pair on the admin workstation. Don't set a passphrase for the keys. You need the keys to use SSH for secure, passwordless connections between the admin workstation and the cluster node machines. Generate the keys with the following command: 
      ssh-keygen -t rsa

      You can also use SUDO user access to the cluster node machines to set up SSH, but for passwordless, non-root user connections you need to update the cluster configuration file with the appropriate credentials. For more information, go to the #Node access configuration section in the sample cluster config file .

    4. Add the generated public key to the cluster node machines. By default, the public keys are stored in the id_rsa.pub identity file. 
      ssh-copy-id -i ~/.ssh/ identity_file 
root@ cluster_node_ip
    5. Disable SSH password authentication on the cluster node machines and use the following command on the admin workstation to verify the public key authentication works between the admin workstation and the cluster node machines. 
      ssh -o IdentitiesOnly=yes -i identity_file 
root@ cluster_node_ip

    Download and install the bmctl tool

    You use the bmctl command-line tool to create clusters in Google Distributed Cloud. The bmctl command automatically sets up the Google service accounts and enables the APIs you need to use Google Distributed Cloud in your specified project.

    If you want to create your own service accounts or do other manual project setup yourself instead, see Enabling Google services and service accounts before you create clusters with bmctl .

    To download and install the bmctl tool:

    1. Create a new directory for bmctl : 
      cd ~ mkdir baremetal 
 cd baremetal
    2. Download bmctl from the Cloud Storage bucket: 
      gcloud storage cp gs://anthos-baremetal-release/bmctl/1.9.8/linux-amd64/bmctl bmctl chmod a+x bmctl
    3. Ensure that bmctl is installed correctly by viewing the help information: 
      ./bmctl -h

    Create your cluster nodes

    Create two machines to serve as nodes for your cluster:

    • One machine functions as the control plane node.
    • One machine functions as the worker node.

    Go to hardware and operating system requirements ( Centos , RHEL , and Ubuntu ) to learn more about the requirements for the cluster nodes.

    Create a cluster

    To create a cluster:

    1. Use bmctl to create a config file.
    2. Edit the config file to customize it for your cluster and network.
    3. Use bmctl to create the cluster from the config file.

    Create a config file

    To create a config file, and enable service accounts and APIs automatically, make sure you are in the baremetal directory, and issue the bmctl command with the following flags: 

    ./bmctl create config -c CLUSTER_NAME 
\
  --enable-apis --create-service-accounts --project-id= PROJECT_ID

    CLUSTER_NAME is the name of your cluster. PROJECT_ID is the project you created in Create a Google Cloud project .

    The command above creates a config file under the baremetal directory at the following path: bmctl-workspace/cluster1/cluster1.yaml

    Edit the config file

    To edit the config file:

    1. Open the bmctl-workspace/cluster1/cluster1.yaml config file in an editor.
    2. Edit the file with your specific node and network requirements. Use the sample config file below for reference. This quickstart doesn't use or include information on OpenID Connect (OIDC).
      # gcrKeyPath:  < to GCR service account key> 
 gcrKeyPath 
 : 
  
 baremetal/gcr.json 
 # sshPrivateKeyPath:  < to SSH private key, used for node access> 
 sshPrivateKeyPath 
 : 
  
 .ssh/id_rsa 
 # gkeConnectAgentServiceAccountKeyPath:  < to Connect agent service account key> 
 gkeConnectAgentServiceAccountKeyPath 
 : 
  
 baremetal/connect-agent.json 
 # gkeConnectRegisterServiceAccountKeyPath:  < to Hub registration service account key> 
 gkeConnectRegisterServiceAccountKeyPath 
 : 
  
 baremetal/connect-register.json 
 # cloudOperationsServiceAccountKeyPath:  < to Cloud Operations service account key> 
 cloudOperationsServiceAccountKeyPath 
 : 
  
 baremetal/cloud-ops.json 
 --- 
 apiVersion 
 : 
  
 v1 
 kind 
 : 
  
 Namespace 
 metadata 
 : 
  
 name 
 : 
  
 cluster-cluster1 
 --- 
 apiVersion 
 : 
  
 baremetal.cluster.gke.io/v1 
 kind 
 : 
  
 Cluster 
 metadata 
 : 
  
 name 
 : 
  
 cluster1 
  
 namespace 
 : 
  
 cluster-cluster1 
 spec 
 : 
  
 # Cluster type. This can be: 
  
 #   1) admin:  to create an admin cluster. This can later be used to create user clusters. 
  
 #   2) user:   to create a user cluster. Requires an existing admin cluster. 
  
 #   3) hybrid: to create a hybrid cluster that runs admin cluster components and user workloads. 
  
 #   4) standalone: to create a cluster that manages itself, runs user workloads, but does not manage other clusters. 
  
 type 
 : 
  
 hybrid 
  
 # Anthos cluster version. 
  
 anthosBareMetalVersion 
 : 
  
 1.9.8 
  
 # GKE connect configuration 
  
 gkeConnect 
 : 
  
 projectID 
 : 
  
  PROJECT_ID 
 
  
 # Control plane configuration 
  
 controlPlane 
 : 
  
 nodePoolSpec 
 : 
  
 nodes 
 : 
  
 # Control plane node pools. Typically, this is either a single machine 
  
 # or 3 machines if using a high availability deployment. 
  
 - 
  
 address 
 : 
  
  CONTROL_PLANE_NODE_IP 
 
  
 # Cluster networking configuration 
  
 clusterNetwork 
 : 
  
 # Pods specify the IP ranges from which pod networks are allocated. 
  
 pods 
 : 
  
 cidrBlocks 
 : 
  
 - 
  
 192.168.0.0/16 
  
 # Services specify the network ranges from which service virtual IPs are allocated. 
  
 # This can be any RFC 1918 range that does not conflict with any other IP range 
  
 # in the cluster and node pool resources. 
  
 services 
 : 
  
 cidrBlocks 
 : 
  
 - 
  
 172.26.232.0/24 
  
 # Load balancer configuration 
  
 loadBalancer 
 : 
  
 # Load balancer mode can be either 'bundled' or 'manual'. 
  
 # In 'bundled' mode a load balancer will be installed on load balancer nodes during cluster creation. 
  
 # In 'manual' mode the cluster relies on a manually-configured external load balancer. 
  
 mode 
 : 
  
 bundled 
  
 # Load balancer port configuration 
  
 ports 
 : 
  
 # Specifies the port the load balancer serves the Kubernetes control plane on. 
  
 # In 'manual' mode the external load balancer must be listening on this port. 
  
 controlPlaneLBPort 
 : 
  
 443 
  
 # There are two load balancer virtual IP (VIP) addresses: one for the control plane 
  
 # and one for the L7 Ingress service. The VIPs must be in the same subnet as the load balancer nodes. 
  
 # These IP addresses do not correspond to physical network interfaces. 
  
 vips 
 : 
  
 # ControlPlaneVIP specifies the VIP to connect to the Kubernetes API server. 
  
 # This address must not be in the address pools below. 
  
 controlPlaneVIP 
 : 
  
  CONTROL_PLANE_VIP 
 
  
 # IngressVIP specifies the VIP shared by all services for ingress traffic. 
  
 # Allowed only in non-admin clusters. 
  
 # This address must be in the address pools below. 
  
 ingressVIP 
 : 
  
  INGRESS_VIP 
 
  
 # AddressPools is a list of non-overlapping IP ranges for the data plane load balancer. 
  
 # All addresses must be in the same subnet as the load balancer nodes. 
  
 # Address pool configuration is only valid for 'bundled' LB mode in non-admin clusters. 
  
 # addressPools: 
  
 # - name: pool1 
  
 #   addresses: 
  
 #   # Each address must be either in the CIDR form (1.2.3.0/24) 
  
 #   # or range form (1.2.3.1-1.2.3.5). 
  
 #   - LOAD_BALANCER_ADDRESS_POOL 
- 
  
 # A load balancer nodepool can be configured to specify nodes used for load balancing. 
  
 # These nodes are part of the kubernetes cluster and run regular workloads as well as load balancers. 
  
 # If the node pool config is absent then the control plane nodes are used. 
  
 # Node pool configuration is only valid for 'bundled' LB mode. 
  
 # nodePoolSpec: 
  
 #   nodes: 
  
 #   - address: LOAD_BALANCER_NODE_IP 
; 
  
 # Proxy configuration 
  
 # proxy: 
  
 #   url: http://[username:password@]domain 
  
 #   # A list of IPs, hostnames or domains that should not be proxied. 
  
 #   noProxy: 
  
 #   - 127.0.0.1 
  
 #   - localhost 
  
 # Logging and Monitoring 
  
 clusterOperations 
 : 
  
 # Cloud project for logs and metrics. 
  
 projectID 
 : 
  
  PROJECT_ID 
 
  
 # Cloud location for logs and metrics. 
  
 location 
 : 
  
 us-central1 
  
 # Whether collection of application logs/metrics should be enabled (in addition to 
  
 # collection of system logs/metrics which correspond to system components such as 
  
 # Kubernetes control plane or cluster management agents). 
  
 # enableApplication: false 
  
 # Storage configuration 
  
 storage 
 : 
  
 # lvpNodeMounts specifies the config for local PersistentVolumes backed by mounted disks. 
  
 # These disks need to be formatted and mounted by the user, which can be done before or after 
  
 # cluster creation. 
  
 lvpNodeMounts 
 : 
  
 # path specifies the host machine path where mounted disks will be discovered and a local PV 
  
 # will be created for each mount. 
  
 path 
 : 
  
 /mnt/localpv-disk 
  
 # storageClassName specifies the StorageClass that PVs will be created with. The StorageClass 
  
 # is created during cluster creation. 
  
 storageClassName 
 : 
  
 local-disks 
  
 # lvpShare specifies the config for local PersistentVolumes backed by subdirectories in a shared filesystem. 
  
 # These subdirectories are automatically created during cluster creation. 
  
 lvpShare 
 : 
  
 # path specifies the host machine path where subdirectories will be created on each host. A local PV 
  
 # will be created for each subdirectory. 
  
 path 
 : 
  
 /mnt/localpv-share 
  
 # storageClassName specifies the StorageClass that PVs will be created with. The StorageClass 
  
 # is created during cluster creation. 
  
 storageClassName 
 : 
  
 local-shared 
  
 # numPVUnderSharedPath specifies the number of subdirectories to create under path. 
  
 numPVUnderSharedPath 
 : 
  
 5 
  
 # NodeConfig specifies the configuration that applies to all nodes in the cluster. 
  
 nodeConfig 
 : 
  
 # podDensity specifies the pod density configuration. 
  
 podDensity 
 : 
  
 # maxPodsPerNode specifies the maximum number of pods allowed on a single node. 
  
 maxPodsPerNode 
 : 
  
 250 
  
 # containerRuntime specifies which container runtime to use for scheduling containers on nodes. 
  
 # containerd and docker are supported. 
  
 containerRuntime 
 : 
  
 containerd 
 --- 
 # Node pools for worker nodes 
 apiVersion 
 : 
  
 baremetal.cluster.gke.io/v1 
 kind 
 : 
  
 NodePool 
 metadata 
 : 
  
 name 
 : 
  
 node-pool-1 
  
 namespace 
 : 
  
 cluster-cluster1 
 spec 
 : 
  
 clusterName 
 : 
  
 cluster1 
  
 nodes 
 : 
  
 - 
  
 address 
 : 
  
  WORKER_NODE_1_IP 
 
  
 - 
  
 address 
 : 
  
  WORKER_NODE_2_IP

    Run preflight checks and create the cluster

    The bmctl command runs preflight checks on your cluster config file before it creates a cluster. If the checks are successful, bmctl creates the cluster.

    To run preflight checks and create the cluster:

    1. Ensure that you are in the baremetal directory.
    2. Use the following command to create the cluster:
      3. ./bmctl create cluster -c CLUSTER_NAME
      For example: 
      ./bmctl create cluster -c cluster1

      The bmctl command monitors the preflight checks and cluster creation, displays output to the screen, and writes verbose information to the bmctl logs.

    You can find the bmctl , preflight checks, and node installation logs in the following directory: baremetal/bmctl-workspace/ CLUSTER_NAME /log

    The bmctl preflight checks the proposed cluster installation for the following conditions:

    • The Linux distribution and version are supported.
    • SELinux is not in "enforcing" mode.
    • On Ubuntu, Uncomplicated Firewall (UFW) is not active.
    • Google Container Registry is reachable.
    • The VIPs are available.
    • The cluster machines have connectivity to each other.
    • Load balancer machines are on the same Layer 2 subnet.

    Cluster creation can take several minutes to finish.

    Get information about your cluster

    After you successfully create a cluster, use the kubectl command to show information about the new cluster. During cluster creation, the bmctl command writes a kubeconfig file for the cluster that you can query with kubectl . The kubeconfig file is written to bmctl-workspace/ CLUSTER_NAME/CLUSTER_NAME -kubeconfig .

    For example: 

    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig get nodes

    This command returns: 

    NAME      STATUS   ROLES    AGE   VERSION
node-01   Ready    master   16h   v1.17.8-gke.16
node-02   Ready    <none>   16h   v1.17.8-gke.16

    If your cluster creation fails preflight checks, then check the preflight check logs for errors, and correct them in the cluster config file. The preflight check logs are located in the /log directory at 

    ~/baremetal/bmctl-workspace/ CLUSTER_NAME 
/log

    The preflight check logs for each machine in the cluster are in the CLUSTER_NAME directory, and are organized by IP address. For example: 

    bmctl-workspace/cluster1/log
└── preflight-20201007-034844
    ├── 172.17.0.3
    ├── 172.17.0.4
    ├── 172.17.0.5
    ├── 172.17.0.6
    ├── 172.17.0.7
    └── node-network

    Ignore pre-flight check errors

    If your cluster creation fails after pre-flight checks, you can try to re-install the cluster using the --force flag in the bmctl command.

    The --force flag installs over an existing cluster, but ignores the results from any preflight check failure due to already allocated server ports.

    1. Ensure that you are in the baremetal directory.
    2. Use the following command with the --force flag to re-create the cluster:
      3. ./bmctl create cluster -c CLUSTER_NAME 
--force
       For example: 
      ./bmctl create cluster -c cluster1 --force

    Create a Deployment and a Service

    Here's a manifest for a Deployment: 

     apiVersion 
 : 
  
 apps 
 / 
 v1 
 kind 
 : 
  
 Deployment 
 metadata 
 : 
  
 name 
 : 
  
 my 
 - 
 deployment 
 spec 
 : 
  
 selector 
 : 
  
 matchLabels 
 : 
  
 app 
 : 
  
 metrics 
  
 department 
 : 
  
 sales 
  
 replicas 
 : 
  
 3 
  
 template 
 : 
  
 metadata 
 : 
  
 labels 
 : 
  
 app 
 : 
  
 metrics 
  
 department 
 : 
  
 sales 
  
 spec 
 : 
  
 containers 
 : 
  
 - 
  
 name 
 : 
  
 hello 
  
 image 
 : 
  
 "gcr.io/google-samples/hello-app:2.0"

    Save the manifest as my-deployment.yaml .

    Create the Deployment with the following command: 

    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig create -f my-deployment.yaml

    View the Deployment: 

    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig get deployments

    The output shows that the Deployment has three available and ready Pods: 

    NAME               READY   UP-TO-DATE   AVAILABLE   AGE
my-deployment      3/3     3            3           16s

    The following manifest defines a Service of type LoadBalancer: 

     apiVersion 
 : 
  
 v1 
 kind 
 : 
  
 Service 
 metadata 
 : 
  
 name 
 : 
  
 my 
 - 
 service 
 spec 
 : 
  
 selector 
 : 
  
 app 
 : 
  
 metrics 
  
 department 
 : 
  
 sales 
  
 type 
 : 
  
 LoadBalancer 
  
 ports 
 : 
  
 - 
  
 port 
 : 
  
 80 
  
 targetPort 
 : 
  
 8080

    Save the manifest as my-service.yaml .

    Create the Service with the following command: 

    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig create -f my-service.yaml

    View the Service: 

    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig get service my-service

    Output: 

    NAME         TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S
my-service   LoadBalancer   172.26.232.2   172.16.1.21   80:30060/TCP

    Google Distributed Cloud gives the service an external IP address. Use the external IP address to call the service:

    curl 172.16.1.21

    The output is a hello world message:

    Hello, world!
Version: 2.0.0
Hostname: my-deployment-75d45b64f9-6clxj

    Create a high availability control plane

    The quickstart created a simple two-node hybrid cluster. If you want to create a high availability control plane, create a cluster that has three control plane nodes.

    For example, edit the config file to add two additional nodes to the control plane:

     controlPlane 
 : 
  
 nodePoolSpec 
 : 
  
 clusterName 
 : 
  
 cluster1 
  
 nodes 
 : 
  
 # 
  
 Control 
  
 Plane 
  
 node 
  
 pools 
 . 
  
 Typically 
 , 
  
 this 
  
 is 
  
 either 
  
 a 
  
 single 
  
 machine 
  
 # 
  
 or 
  
 3 
  
 machines 
  
 if 
  
 using 
  
 a 
  
 high 
  
 availability 
  
 deployment 
 . 
  
 - 
  
 address 
 : 
  
< Machine 
  
 1 
  
 IP 
 > 
  
 - 
  
 address 
 : 
  
< Machine 
  
 2 
  
 IP 
 > 
  
 - 
  
 address 
 : 
  
< Machine 
  
 3 
  
 IP 
 >

    Run the load balancer in its own node pool

    The quickstart created a simple two-node hybrid cluster. Thus, the load balancer runs on the same node that runs the control plane.

    If you want the load balancer to run in its own node pool, edit the nodePoolSpec values of the loadBalancer section of your config file :

      
 loadBalancer 
 : 
  
 nodePoolSpec 
 : 
  
 clusterName 
 : 
  
 "cluster1" 
  
 nodes 
 : 
  
 - 
  
 address 
 : 
  
< LB 
  
 Machine 
  
 1 
  
 IP 
 > 
  
 - 
  
 address 
 : 
  
< LB 
  
 Machine 
  
 2 
  
 IP 
 >
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: