Installing Kubernetes Monitoring

Beta

This is a Beta release of Stackdriver Kubernetes Monitoring. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

The page explains how to install the Beta release of Stackdriver Kubernetes Monitoring. This is an opt-in release that replaces the legacy Stackdriver support described in the GKE guides, Monitoring and Logging. This Beta release is intended only for Google Kubernetes Engine (GKE).

You can install this new release when you create a new GKE cluster, or you can upgrade an existing GKE cluster. If you do not opt into this release, then your new clusters use the present Stackdriver support, also called the GA legacy support.

Before you begin

Caution: If you intend to upgrade an existing cluster, read the information about incompatibilities.

• You must be an Owner of the project containing your cluster. The project must be monitored by a Workspace.

• You will be required to use Kubernetes version 1.10.6 or 1.11.2 (or later, if available).

Creating a new cluster

You must opt into this Beta release when you create a new cluster using the GKE console or the Cloud SDK's gcloud command-line tool.

CONSOLE

1. Go to the GKE Kubernetes Clusters page for your project. The following button takes you there:

   Visit the GKE Clusters page

2. Select Create Cluster at the top of the page.

3. In the dialog, specify the following fields in addition to whichever other properties you want in your cluster. For more information, see Creating a Cluster.

   • Cluster Version: 1.10.6 or later; or 1.11.2 or later

   • Try the new Beta Monitoring and Logging experience: CHECKED

     If you do not see this option, then you have not selected a cluster version of 1.10.6 or 1.11.2 (or later, if available). If you see the option but it is grayed out, then be sure that both the Stackdriver Logging and Stackdriver Monitoring options are Enabled (the default).

     This part of the option panel should look like the following:

     

4. Click Create to create the cluster. This may take some time.

GCLOUD

Use gcloud to create your cluster with Stackdriver Kubernetes Monitoring:

1. Open a terminal window with the Cloud SDK and gcloud beta installed.

   One way to do this is to use the Cloud Shell:

   1. Go to the Kubernetes Clusters page for your project:

      GO TO KUBERNETES CLUSTERS

   2. Click the Activate Cloud Shell icon at the top of the page.

2. Create your cluster using Kubernetes 1.10.6 or 1.11.2 (or later, if available) and the --enable-stackdriver-kubernetes option:

   Note: Only the flags relevant to Stackdriver support are shown below. For information on other flags and options you might want to use for your cluster, see Creating a Cluster.

   gcloud beta container clusters create [CLUSTER_NAME] \
     --zone=[ZONE] \
     --project=[PROJECT_ID] \
     --cluster-version=1.10 \
     --enable-stackdriver-kubernetes
   

Troubleshooting:

• If gcloud beta container does not recognize the flag --enable-stackdriver-kubernetes, then update your gcloud installation:

  gcloud components update
  

Next step: Go to Checking your installation on this page.

Upgrading an existing cluster

The following table tells you how to upgrade your cluster to the managed Beta release of Stackdriver Kubernetes Monitoring. There are differences depending on what previous Stackdriver support the cluster is running, which you can tell by clicking your cluster's name in the GKE console.

Current Stackdriver support	Listed Stackdriver status in console	How to upgrade
Beta managed release	Enabled v2(beta)	You only need to upgrade your Kubernetes version. Stackdriver is updated when Kubernetes is.
GA legacy	Enabled	Use the following Upgrade Instructions.
none	Disabled	Use the following Upgrade Instructions.
non-managed, manual Beta^1	Disabled, and the cluster contains a stackdriver-agents namespace	Delete the current agents:   kubectl delete ns stackdriver-agents Then use the following Upgrade Instructions.

Notes:
 ¹ Presently, this can only happen if you manually installed updated agents. Manual installation is no longer needed or recommended.

The following instructions upgrade your GKE cluster to the managed Beta release of Stackdriver Kubernetes Monitoring. Check the previous table that mentions some corner cases.

CONSOLE

1. Go to the GKE Kubernetes Clusters page for your project. The following button takes you there:

   Visit the GKE Clusters page

2. Upgrade your cluster to Kubernetes version 1.10.6 or 1.11.2 (or later, if available). For instructions, see Upgrading Clusters. Allow the upgrade to complete.

3. Click the Edit icon () for your cluster:

   

4. Scroll down to the Stackdriver section and check the box Try the new Beta Monitoring and Logging experience. You might have to enable the Stackdriver Monitoring and Logging choices also:

   

   If you have not upgraded to the required Kubernetes version, you will not see the Try the new Beta... option.

5. Click Save at the bottom of the page.

GCLOUD

1. Open a Cloud Shell window in the project containing your cluster. Alternatively, use your own terminal window with Cloud SDK installed.

2. If you have not done so, set up default values for your cluster in the Cloud SDK:

   gcloud config set project [PROJECT_ID]
   gcloud config set compute/zone [COMPUTE_ZONE]
   

3. Upgrade your cluster to Kubernetes version 1.10.6 or 1.11.2 (or later, if available). For instructions, see Upgrading Clusters in the GKE documentation.

   Wait for the upgrade to complete.

4. Opt into the managed Beta Stackdriver release:

   gcloud beta container clusters update [CLUSTER_ID] \
     --zone=[ZONE]  --region=[REGION]  \
     --logging-service="logging.googleapis.com/kubernetes" \
     --monitoring-service="monitoring.googleapis.com/kubernetes"
   

   In the preceding command, use --zone for zonal clusters and --region for regional clusters. Also, --logging-service and --monitoring-service must be present in the same gcloud command.

5. To check your installation, see Check your installation.

Next step: Go to Checking your installation on this page.

Checking your installation

To check that Stackdriver Monitoring is running properly, wait a few minutes and then examine your cluster. Use either the console or gcloud to see that the Stackdriver pods are running:

CONSOLE

1. From the GCP console, go to Stackdriver > Monitoring:

   Go to the Stackdriver Monitoring console

2. In Monitoring, go to Resources > Kubernetes BETA for the Workspace containing your GCP project.

   You can see all the clusters in your Workspace that are using Stackdriver Kubernetes Monitoring.

3. Select the Workload tab.

4. Expand your cluster and the kube-system namespace. You should see running pods in the kube-system namespace with the following names:

   • fluentd-gcp-...: the Stackdriver Logging agent.
   • heapster-...: the Monitoring agent.
   • metadata-... : the Stackdriver metadata agent.

GCLOUD

1. In GCP Console, with your project selected, open a Cloud Shell window. Alternatively, use your own terminal window with Cloud SDK installed.

2. Run the following command to connect to your cluster:

   gcloud container clusters get-credentials [CLUSTER_ID] --zone [ZONE] --project [PROJECT_ID]
   

3. Run the following command to query the Stackdriver Kubernetes Monitoring namespace:

   kubectl get pods --namespace=kube-system
   

4. You should see pods with the following names (among others):

   • fluentd-gcp-...: the Stackdriver Logging agent.
   • heapster-...: the Monitoring agent.
   • metadata-agent-... : the Stackdriver metadata agent.

Next steps

• You can deploy your application software to your cluster as usual. For more information, see Overview of Deploying Workloads.

• If you are familiar with the current Stackdriver support, then review the differences in Stackdriver Kubernetes Monitoring. For example, this release uses different monitored resource types for your Stackdriver logs, charts, metrics, and alerting policies.

• To use Prometheus with this Beta release of Stackdriver Kubernetes Monitoring, see Using Prometheus.