From 0869e01342c47a548ebc3d5487f70b0279a371c4 Mon Sep 17 00:00:00 2001 From: Eric Tune Date: Mon, 26 Oct 2015 16:16:12 -0700 Subject: [PATCH] Improve addons documentation. Longer description of Addons in Admin Guide to Cluster Components. Mention fluentd as node component in Admin Guide to Cluster Components. From docs/getting-started-guides/scratch.md add refs to setting up DNS, Logging, Monitoring, and GUI. Add TOCs to several pages that were referenced. Fixes #16235 --- docs/admin/cluster-components.md | 68 ++++++++++++++++--- docs/getting-started-guides/scratch.md | 35 ++++++---- .../connecting-to-applications-proxy.md | 8 +++ docs/user-guide/logging.md | 14 ++++ 4 files changed, 105 insertions(+), 20 deletions(-) diff --git a/docs/admin/cluster-components.md b/docs/admin/cluster-components.md index 7503af1b724..1e0a683f686 100644 --- a/docs/admin/cluster-components.md +++ b/docs/admin/cluster-components.md @@ -33,6 +33,31 @@ Documentation for other releases can be found at # Kubernetes Cluster Admin Guide: Cluster Components +**Table of Contents** + + + +- [Kubernetes Cluster Admin Guide: Cluster Components](#kubernetes-cluster-admin-guide-cluster-components) + - [Master Components](#master-components) + - [kube-apiserver](#kube-apiserver) + - [etcd](#etcd) + - [kube-controller-manager](#kube-controller-manager) + - [kube-scheduler](#kube-scheduler) + - [addons](#addons) + - [DNS](#dns) + - [User interface](#user-interface) + - [Container Resource Monitoring](#container-resource-monitoring) + - [Cluster-level Logging](#cluster-level-logging) + - [Node components](#node-components) + - [kubelet](#kubelet) + - [kube-proxy](#kube-proxy) + - [docker](#docker) + - [rkt](#rkt) + - [monit](#monit) + - [fluentd](#fluentd) + + + This document outlines the various binary components that need to run to deliver a functioning Kubernetes cluster. @@ -101,14 +126,38 @@ to create these pods and services does run on the master VM. See: Addon objects are created in the "kube-system" namespace. -Example addons are: -* [DNS](http://releases.k8s.io/HEAD/cluster/addons/dns/) provides cluster local DNS. -* [kube-ui](http://releases.k8s.io/HEAD/cluster/addons/kube-ui/) provides a graphical UI for the - cluster. -* [fluentd-elasticsearch](http://releases.k8s.io/HEAD/cluster/addons/fluentd-elasticsearch/) provides - log storage. Also see the [gcp version](http://releases.k8s.io/HEAD/cluster/addons/fluentd-gcp/). -* [cluster-monitoring](http://releases.k8s.io/HEAD/cluster/addons/cluster-monitoring/) provides - monitoring for the cluster. +#### DNS + +While the other addons are not strictly required, all Kubernetes +clusters should have [cluster DNS](dns.md), as many examples rely on it. + +Cluster DNS is a DNS server, in addition to the other DNS server(s) in your +environment, which serves DNS records for Kubernetes services. + +Containers started by Kubernetes automatically include this DNS server +in their DNS searches. + +#### User interface + +The kube-ui provides a read-only overview of the cluster state. Access +[the UI using kubectl proxy](../user-guide/connecting-to-applications-proxy.md#connecting-to-the-kube-ui-service-from-your-local-workstation) + +#### Container Resource Monitoring + +[Container Resource Monitoring](../user-guide/monitoring.md) records generic time-series metrics +about containers in a central database, and provides a UI for browsing that data. + +#### Cluster-level Logging + +[Container Logging](../user-guide/monitoring.md) saves container logs +to a central log store with search/browsing interface. There are two +implementations: + +* [Cluster-level logging to Google Cloud Logging]( +docs/user-guide/logging.md#cluster-level-logging-to-google-cloud-logging) + +* [Cluster-level Logging with Elasticsearch and Kibana]( +docs/user-guide/logging.md#cluster-level-logging-with-elasticsearch-and-kibana) ## Node components @@ -146,6 +195,9 @@ network rules on the host and performing connection forwarding. `monit` is a lightweight process babysitting system for keeping kubelet and docker running. +### fluentd + +`fluentd` is a daemon which helps provide [cluster-level logging](#cluster-level-logging). [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/admin/cluster-components.md?pixel)]() diff --git a/docs/getting-started-guides/scratch.md b/docs/getting-started-guides/scratch.md index b5e8d8ff83c..5fab3018875 100644 --- a/docs/getting-started-guides/scratch.md +++ b/docs/getting-started-guides/scratch.md @@ -77,9 +77,7 @@ steps that existing cluster setup scripts are making. - [Scheduler pod template](#scheduler-pod-template) - [Controller Manager Template](#controller-manager-template) - [Starting and Verifying Apiserver, Scheduler, and Controller Manager](#starting-and-verifying-apiserver-scheduler-and-controller-manager) - - [Logging](#logging) - - [Monitoring](#monitoring) - - [DNS](#dns) + - [Starting Cluster Services](#starting-cluster-services) - [Troubleshooting](#troubleshooting) - [Running validate-cluster](#running-validate-cluster) - [Inspect pods and services](#inspect-pods-and-services) @@ -433,7 +431,7 @@ Arguments to consider: - Otherwise, if taking the firewall-based security approach - `--api-servers=http://$MASTER_IP` - `--config=/etc/kubernetes/manifests` - - `--cluster-dns=` to the address of the DNS server you will setup (see [Starting Addons](#starting-addons).) + - `--cluster-dns=` to the address of the DNS server you will setup (see [Starting Cluster Services](#starting-cluster-services).) - `--cluster-domain=` to the dns domain prefix to use for cluster DNS addresses. - `--docker-root=` - `--root-dir=` @@ -836,17 +834,30 @@ If you have selected the `--register-node=true` option for kubelets, they will n You should soon be able to see all your nodes by running the `kubectl get nodes` command. Otherwise, you will need to manually create node objects. -### Logging +### Starting Cluster Services -**TODO** talk about starting Logging. +You will want to complete your Kubernetes clusters by adding cluster-wide +services. These are sometimes called *addons*, and [an overview +of their purpose is in the admin guide]( +../../docs/admin/cluster-components.md#addons). -### Monitoring +Notes for setting up each cluster service are given below: -**TODO** talk about starting Monitoring. - -### DNS - -**TODO** talk about starting DNS. +* Cluster DNS: + * required for many kubernetes examples + * [Setup instructions](http://releases.k8s.io/HEAD/cluster/addons/dns/) + * [Admin Guide](../admin/dns.md) +* Cluster-level Logging + * Multiple implementations with different storage backends and UIs. + * [Elasticsearch Backend Setup Instructions](http://releases.k8s.io/HEAD/cluster/addons/fluentd-elasticsearch/) + * [Google Cloud Logging Backend Setup Instructions](http://releases.k8s.io/HEAD/cluster/addons/fluentd-gcp/). + * Both require running fluentd on each node. + * [User Guide](../user-guide/logging.md) +* Container Resource Monitoring + * [Setup instructions](http://releases.k8s.io/HEAD/cluster/addons/cluster-monitoring/) +* GUI + * [Setup instructions](http://releases.k8s.io/HEAD/cluster/addons/kube-ui/) + cluster. ## Troubleshooting diff --git a/docs/user-guide/connecting-to-applications-proxy.md b/docs/user-guide/connecting-to-applications-proxy.md index a71a0b18f42..806168bff33 100644 --- a/docs/user-guide/connecting-to-applications-proxy.md +++ b/docs/user-guide/connecting-to-applications-proxy.md @@ -33,6 +33,14 @@ Documentation for other releases can be found at # Connecting to applications: kubectl proxy and apiserver proxy + + +- [Connecting to applications: kubectl proxy and apiserver proxy](#connecting-to-applications-kubectl-proxy-and-apiserver-proxy) + - [Getting the apiserver proxy URL of kube-ui](#getting-the-apiserver-proxy-url-of-kube-ui) + - [Connecting to the kube-ui service from your local workstation](#connecting-to-the-kube-ui-service-from-your-local-workstation) + + + You have seen the [basics](accessing-the-cluster.md) about `kubectl proxy` and `apiserver proxy`. This guide shows how to use them together to access a service([kube-ui](ui.md)) running on the Kubernetes cluster from your workstation. diff --git a/docs/user-guide/logging.md b/docs/user-guide/logging.md index 9ee65f3ac4c..6d3b0f72bad 100644 --- a/docs/user-guide/logging.md +++ b/docs/user-guide/logging.md @@ -33,6 +33,20 @@ Documentation for other releases can be found at # Logging +**Table of Contents** + + + +- [Logging](#logging) + - [Logging by Kubernetes Components](#logging-by-kubernetes-components) + - [Examining the logs of running containers](#examining-the-logs-of-running-containers) + - [Cluster level logging to Google Cloud Logging](#cluster-level-logging-to-google-cloud-logging) + - [Cluster level logging with Elasticsearch and Kibana](#cluster-level-logging-with-elasticsearch-and-kibana) + - [Ingesting Application Log Files](#ingesting-application-log-files) + - [Known issues](#known-issues) + + + ## Logging by Kubernetes Components Kubernetes components, such as kubelet and apiserver, use the [glog](https://godoc.org/github.com/golang/glog) logging library. Developer conventions for logging severity are described in [docs/devel/logging.md](../devel/logging.md).