In this quickstart, you deploy a sample web servercontainerized application to a Google Kubernetes Engine (GKE) cluster. You learn how to create a cluster,and how to deploy the application to the cluster so that it can be accessed byusers.

This page is for Operators and Developers whoprovision and configure cloud resources and deploy apps and services. To learnmore about common roles and example tasks that we reference in Google Cloudcontent, seeCommon GKE user roles and tasks.

Before reading this page, ensure that you're familiar withKubernetes.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry and Google Kubernetes Engine APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry and Google Kubernetes Engine APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Required roles

Grant roles to your user account. Run the following command once for each of the following IAM roles:roles/container.admin

gcloudprojectsadd-iam-policy-bindingPROJECT_ID--member="user:USER_IDENTIFIER"--role=ROLE

Replace the following:

• PROJECT_ID: Your project ID.
• USER_IDENTIFIER: The identifier for your user account. For example,myemail@example.com.
• ROLE: The IAM role that you grant to your user account.

Launch Cloud Shell

In this tutorial you will useCloud Shell,which is a shell environment for managing resources hosted onGoogle Cloud.

Cloud Shell comes preinstalled with theGoogle Cloud CLI andkubectl command-line tool. The gcloud CLI provides the primary command-lineinterface for Google Cloud, andkubectl provides the primary command-lineinterface for running commands against Kubernetes clusters.

Launch Cloud Shell:

1. Go to the Google Cloud console.

   Google Cloud console

2. From the upper-right corner of the console, click theActivate Cloud Shell button:

A Cloud Shell session opens inside a frame lower on the console.You use this shell to rungcloud andkubectl commands.Before you run commands, set your default project in the Google Cloud CLIusing the following command:

gcloudconfigsetprojectPROJECT_ID

ReplacePROJECT_ID with yourproject ID.

Create a GKE cluster

Acluster consists of at least onecluster control plane machine and multipleworker machines callednodes. Nodes areCompute Engine virtual machine (VM) instances that run the Kubernetes processes necessary to makethem part of the cluster. You deploy applications to clusters, and theapplications run on the nodes.

This section shows you how to create a cluster inAutopilot mode,which is the recommended cluster mode for most production use cases. You couldalternatively use aGKE Standard mode clusterto do these steps.

Create an Autopilot cluster namedhello-cluster:

gcloudcontainerclusterscreate-autohello-cluster\--location=us-central1

It might take several minutes to finish creating the cluster.

Get authentication credentials for the cluster

After creating your cluster, you need to get authentication credentials tointeract with the cluster:

gcloudcontainerclustersget-credentialshello-cluster\--locationus-central1

This command configureskubectl to use the cluster you created.

Deploy an application to the cluster

Now that you have created a cluster, you can deploy acontainerized application to it. For this quickstart, you can deploy our example webapplication,hello-app.

GKE uses Kubernetes objects to create and manage yourcluster's resources. Kubernetes provides theDeployment object for deploying stateless applications like web servers.Service objects define rules and load balancing for accessing your applicationfrom the internet.

Create the Deployment

To runhello-app in your cluster, you need to deploy the application byrunning the following command:

kubectlcreatedeploymenthello-server\--image=us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

This Kubernetes command,kubectl create deployment,creates a Deployment namedhello-server. The Deployment'sPod runs thehello-app container image.

In this command:

• --image specifies a container image to deploy. In this case, thecommand pulls the example image from anArtifact Registry repository,us-docker.pkg.dev/google-samples/containers/gke/hello-app.:1.0 indicates the specific image version to pull. If you don't specify aversion, the image with the defaultlatest tag is used.

Expose the Deployment

After deploying the application, you need to expose it to the internet so thatusers can access it. You can expose your application by creating a Service, aKubernetes resource that exposes your application to external traffic.

To expose your application, run the followingkubectl expose command:

kubectlexposedeploymenthello-server\--typeLoadBalancer\--port80\--target-port8080

Passing in the--type LoadBalancer flag creates a Compute Engineload balancer for your container. The--port flag initializes publicport 80 to the internet and the--target-port flag routes the traffic toport 8080 of the application.

Load balancers are billed per Compute Engine'sload balancer pricing.

Inspect and view the application

1. Inspect the running Pods by usingkubectl get pods:

   kubectlgetpods

   You should see onehello-server Pod running on your cluster.

2. Inspect thehello-server Service by usingkubectl get service:

   kubectlgetservicehello-server

   From this command's output, copy the Service's external IP address from theEXTERNAL-IP column.

   Note: You might need to wait several minutes before the Service'sexternal IP address populates. If the application's external IP is<pending>, runkubectl get again.

3. View the application from your web browser by using the external IP addresswith the exposed port:

   http://EXTERNAL_IP

You have just deployed a containerized web application toGKE.

To track and organize your GKE resources in an application-centricway, you can add your resources as Services and workloads toApp Hubapplications.

For more information on resources that App Hub supports, seeSupported resources.

To learn how to set up App Hub on your project, seeSet up App Hub.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, delete the Google Cloud project with the resources.

1. Delete the application's Service by runningkubectl delete:

   kubectldeleteservicehello-server

   This command deletes the Compute Engine load balancer that youcreated when you exposed the Deployment.

2. Delete your cluster by runninggcloud container clusters delete:

   gcloudcontainerclustersdeletehello-cluster\--locationus-central1

Optional:hello-app code review

hello-app is a web server application that consists of two files:main.go and aDockerfile.

hello-app is packaged as aDocker container image. Container images are stored in any Docker image registry,such as Artifact Registry. We hosthello-app in a Artifact Registry repository atus-docker.pkg.dev/google-samples/containers/gke/hello-app.

packagemainimport("fmt""log""net/http""os")funcmain(){// register hello function to handle all requestsmux:=http.NewServeMux()mux.HandleFunc("/",hello)// use PORT environment variable, or default to 8080port:=os.Getenv("PORT")ifport==""{port="8080"}// start the web server on port and accept requestslog.Printf("Server listening on port %s",port)log.Fatal(http.ListenAndServe(":"+port,mux))}// hello responds to the request with a plain-text "Hello, world" message.funchello(whttp.ResponseWriter,r*http.Request){log.Printf("Serving request: %s",r.URL.Path)host,_:=os.Hostname()fmt.Fprintf(w,"Hello, world!\n")fmt.Fprintf(w,"Version: 1.0.0\n")fmt.Fprintf(w,"Hostname: %s\n",host)}

FROMgolang:1.24.3asbuilderWORKDIR/appRUNgomodinithello-appCOPY*.go./RUNCGO_ENABLED=0GOOS=linuxgobuild-o/hello-appFROMgcr.io/distroless/base-debian11WORKDIR/COPY--from=builder/hello-app/hello-appENVPORT8080USERnonroot:nonrootCMD["/hello-app"]

What's next

• Learn more aboutcreating clusters.
• Learn more aboutKubernetes.
• Learn how topackage, host, and deploy a simple web server application.
• Deploy a Kubernetes application with Cloud Code for VS Code orCloud Code for IntelliJ.
• Learn how toReplatform Linux applications to containers.