From a7d76d7f806b6d66940f45a4964b4b0841007c7e Mon Sep 17 00:00:00 2001 From: Joseph Heck Date: Fri, 2 Feb 2018 16:33:08 -0500 Subject: [PATCH] content updates from Steve's review (#7217) * content updates from Steve's review * catching that missed 'k'->'K' * two more changes based on feedback --- .../users/cluster-operator/foundational.md | 25 +++++++++++-------- .../users/cluster-operator/intermediate.md | 20 +++++++-------- 2 files changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/user-journeys/users/cluster-operator/foundational.md b/docs/user-journeys/users/cluster-operator/foundational.md index 7804bd0387..7d44ecc6ac 100644 --- a/docs/user-journeys/users/cluster-operator/foundational.md +++ b/docs/user-journeys/users/cluster-operator/foundational.md @@ -27,21 +27,24 @@ Metrics If you have not already done so, start your understanding by reading through [What is Kubernetes?](/docs/concepts/overview/what-is-kubernetes/), which introduces a number of basic concepts and terms. -Kubernetes is quite flexible, and can a cluster can be run in a wide variety of places. You can interact with Kubernetes entirely on your own laptop or local development machine with it running within a virtual machine. Kubernetes can also run on virtual machines hosted either locally or in a cloud provider, and you can run a kubernetes cluster on bare metal. +Kubernetes is quite flexible, and a cluster can be run in a wide variety of places. You can interact with Kubernetes entirely on your own laptop or local development machine with it running within a virtual machine. Kubernetes can also run on virtual machines hosted either locally or in a cloud provider, and you can run a Kubernetes cluster on bare metal. + +A cluster is made up of one or more [Nodes](/docs/concepts/architecture/nodes/); where a node is a physical or virtual machine. +If there is more than one node in your cluster then the nodes are connected with a [cluster network](/docs/concepts/cluster-administration/networking/). +Regardless of how many nodes, all Kubernetes clusters generally have the same components, which are described in [Kubernetes Components](/docs/concepts/overview/components). -A cluster is made up of one or more [Nodes](/docs/concepts/architecture/nodes/); where a node is a physical or virtual machine. If there are more than one node in your cluster, then each of the nodes are connected with a [cluster network](/docs/concepts/cluster-administration/networking/). Regardless of how many nodes, all Kubernetes clusters will generally have the same components, which are described in [Kubernetes Components](/docs/concepts/overview/components). ## Learn about Kubernetes basics -A good way to become familiar with how to manage and operate a Kubernetes cluster is by setting them up. +A good way to become familiar with how to manage and operate a Kubernetes cluster is by setting one up. One of the most compact ways to experiment with a cluster is [Installing and using Minikube](/docs/tasks/tools/install-minikube/). Minikube is a command line tool for setting up and running a single-node cluster within a virtual machine on your local laptop or development computer. Minikube is even available through your browser at the [Katacoda Kubernetes Playground](https://www.katacoda.com/courses/kubernetes/playground). -Katacoda provides a browser-based connection to a single-node cluster, using minikube behind the scenes, to support a number of tutorials to explore Kubernetes. You can also leverage the web-based [Play with Kubernetes](http://labs.play-with-k8s.com/) to the same ends - a temporary cluster to play with in on the web. +Katacoda provides a browser-based connection to a single-node cluster, using minikube behind the scenes, to support a number of tutorials to explore Kubernetes. You can also leverage the web-based [Play with Kubernetes](http://labs.play-with-k8s.com/) to the same ends - a temporary cluster to play with on the web. You interact with Kubernetes either through a dashboard, an API, or using a command-line tool (such as `kubectl`) that interacts with the Kubernetes API. -Be familiar with how to [Organizing Cluster Access](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) with configuration files. +Be familiar with [Organizing Cluster Access](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) by using configuration files. The Kubernetes API exposes a number of resources that provide the building blocks and abstractions that are used to run software on Kubernetes. -Learn more about these resources at [Understanding Kubernetes Objects](/docs/concepts/overview/kubernetes-objects) +Learn more about these resources at [Understanding Kubernetes Objects](/docs/concepts/overview/kubernetes-objects). These resources are covered in a number of articles within the Kubernetes documentation. * [Pod Overview](/docs/concepts/workloads/pods/pod-overview/) @@ -59,15 +62,15 @@ These resources are covered in a number of articles within the Kubernetes docume * [ConfigMaps](/docs/tasks/configure-pod-container/configure-pod-configmap/) * [Secrets](/docs/concepts/configuration/secret/) -As a cluster operator you may not need to use all these resources although you should be familiar with them to understand how the cluster is working and being used. +As a cluster operator you may not need to use all these resources, although you should be familiar with them to understand how the cluster is being used. There are a number of additional resources that you should be aware of, some listed under [Intermediate Resources](/docs/user-journeys/users/cluster-operator/intermediate#section-1). You should also be familiar with [how to manage kubernetes resources](/docs/concepts/cluster-administration/manage-deployment/). -## Get information about my cluster +## Get information about your cluster -You can [access clusters using the cluster API](/docs/tasks/administer-cluster/access-cluster-api/). -If you are not already familiar, run through the tutorial to [view your cluster's Pods and Nodes](/docs/tutorials/kubernetes-basics/explore-intro/). -Using kubectl, you can retrieve information very quickly. +You can [access clusters using the Kubernetes API](/docs/tasks/administer-cluster/access-cluster-api/). +If you are not already familiar with how to do this, you can review the [introductory tutorial](/docs/tutorials/kubernetes-basics/explore-intro/). +Using `kubectl`, you can retrieve information about your Kubernetes cluster very quickly. To get basic information about the nodes in your cluster run the command `kubectl get nodes`. You can get more detailed information for the same nodes with the command `kubectl describe nodes`. You can see the status of the core of kubernetes with the command `kubectl get componentstatuses`. diff --git a/docs/user-journeys/users/cluster-operator/intermediate.md b/docs/user-journeys/users/cluster-operator/intermediate.md index 1c7a93eee3..fc56c41e31 100644 --- a/docs/user-journeys/users/cluster-operator/intermediate.md +++ b/docs/user-journeys/users/cluster-operator/intermediate.md @@ -16,9 +16,9 @@ If you are a cluster operator looking to expand your grasp of Kubernetes, this p {% capture body %} -## Work with Ingress, Networking, Storage, Workloads +## Work with ingress, networking, storage, and workloads -Introductions to Kubernetes typically discuss simpler stateless applications. As you move into fuller dev, testing, and production environments, you need to consider more complex cases: +Introductions to Kubernetes typically discuss simple stateless applications. As you move into more complex development, testing, and production environments, you need to consider more complex cases: Communication: Ingress and Networking @@ -49,12 +49,12 @@ And how Pods work with scheduling, priority, disruptions: * [Pods and Priority](/docs/concepts/configuration/pod-priority-preemption/) * [Disruptions](/docs/concepts/workloads/pods/disruptions/) * [Assigning Pods to Nodes](/docs/concepts/configuration/assign-pod-node/) -* [Managing compute resources for containers](/docs/concepts/configuration/manage-compute-resources-container/) -* [Configuration best practices](/docs/concepts/configuration/overview/) +* [Managing Compute Resources for Containers](/docs/concepts/configuration/manage-compute-resources-container/) +* [Configuration Best Practices](/docs/concepts/configuration/overview/) ## Implement security best practices -Securing your cluster includes work beyond the scope of Kubernetes itself. (TODO: identify major items) +Securing your cluster includes work beyond the scope of Kubernetes itself. In Kubernetes, you configure access control: @@ -62,7 +62,7 @@ In Kubernetes, you configure access control: * [Authenticating](/docs/admin/authentication/) * [Using Admission Controllers](/docs/admin/admission-controllers/) -You also configure authorization. That is, you determine not just how users and services authenticate to the API server, or whether they have access, but also what resources they have access to. Role-based access control (RBAC) is currently the recommended mechanism for controlling authorization to Kubernetes resources. Other authorization modes are available for more specific use cases. +You also configure authorization. That is, you determine not just how users and services authenticate to the API server, or whether they have access, but also what resources they have access to. Role-based access control (RBAC) is the recommended mechanism for controlling authorization to Kubernetes resources. Other authorization modes are available for more specific use cases. * [Authorization Overview](/docs/admin/authorization/) * [Using RBAC Authorization](/docs/admin/authorization/rbac/) @@ -73,19 +73,19 @@ You should create Secrets to hold sensitive data such as passwords, tokens, or k ## Implement custom logging and monitoring -Monitoring the health and state of your cluster is important. Collecting metrics, logging, and providing access to that information are common needs. Kubernetes provides some basic logging structure and you may want to use additional tools to help aggregate and analyze log data. +Monitoring the health and state of your cluster is important. Collecting metrics, logging, and providing access to that information are common needs. Kubernetes provides some basic logging structure, and you may want to use additional tools to help aggregate and analyze log data. Start with the [basics on Kubernetes logging](/docs/concepts/cluster-administration/logging/) to understand how containers do logging and common patterns. Cluster operators often want to add something to gather and aggregate those logs. See the following topics: * [Logging Using Elasticsearch and Kibana](/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/) * [Logging Using Stackdriver](/docs/tasks/debug-application-cluster/logging-stackdriver/) -Like log aggregation, many clusters utilize additional software to help capture metrics and display them. There is an overview at of tools at [Tools for Monitoring Compute, Storage, and Network Resources](/docs/tasks/debug-application-cluster/resource-usage-monitoring/). +Like log aggregation, many clusters utilize additional software to help capture metrics and display them. There is an overview of tools at [Tools for Monitoring Compute, Storage, and Network Resources](/docs/tasks/debug-application-cluster/resource-usage-monitoring/). Kubernetes also supports a [core metrics pipeline](/docs/tasks/debug-application-cluster/core-metrics-pipeline/) which can be used by Horizontal Pod Autoscaler with custom metrics. -[Prometheus](https://prometheus.io/), which is another CNCF project, is a common choice to support capture and temporary collection of metrics. There are several options to installing Prometheus, including using the [stable/prometheus](https://github.com/kubernetes/charts/tree/master/stable/prometheus) [helm](https://helm.sh/) chart, and CoreOS provides a [prometheus operator](https://github.com/coreos/prometheus-operator) and [kube-prometheus](https://github.com/coreos/prometheus-operator/tree/master/contrib/kube-prometheus) which adds on Grafana dashboards and common configurations. +[Prometheus](https://prometheus.io/), which is another CNCF project, is a common choice to support capture and temporary collection of metrics. There are several options for installing Prometheus, including using the [stable/prometheus](https://github.com/kubernetes/charts/tree/master/stable/prometheus) [helm](https://helm.sh/) chart, and CoreOS provides a [prometheus operator](https://github.com/coreos/prometheus-operator) and [kube-prometheus](https://github.com/coreos/prometheus-operator/tree/master/contrib/kube-prometheus), which adds on Grafana dashboards and common configurations. -A common configuration on [minikube](https://github.com/kubernetes/minikube) and some kubernetes clusters used [Heapster](https://github.com/kubernetes/heapster) +A common configuration on [Minikube](https://github.com/kubernetes/minikube) and some Kubernetes clusters uses [Heapster](https://github.com/kubernetes/heapster) [along with InfluxDB and Grafana](https://github.com/kubernetes/heapster/blob/master/docs/influxdb.md). There is a [walkthrough of how to install this configuration in your cluster](https://blog.kublr.com/how-to-utilize-the-heapster-influxdb-grafana-stack-in-kubernetes-for-monitoring-pods-4a553f4d36c9). As of Kubernetes 1.9, the [sig-instrumentation](https://github.com/kubernetes/community/tree/master/sig-instrumentation) team is shifting away from an all-inclusive monitoring pattern with heapster, described in [Prometheus vs. Heapster vs. Kubernetes Metrics APIs](https://brancz.com/2018/01/05/prometheus-vs-heapster-vs-kubernetes-metrics-apis/).