Merge pull request #13723 from adellape/termgloss_deploy

Add more terms to glossary

Author: adellape

contributing_to_docs/term_glossary.adoc

@@ -113,6 +113,15 @@ Usage: cluster
 The collection of controllers, Pods, and Services and related DNS and networking
 routing configuration that are defined on the system.
 
+''''
+=== ConfigMap
+
+Usage: ConfigMap(s)
+
+ConfigMaps hold configuration data for Pods to consume.
+
+Do not use: configuration map(s)
+
 ''''
 === container
 
@@ -139,25 +148,28 @@ Usage: container group
 
 Usage: Deployment(s)
 
-A Deployment is a statement of intent by a user to roll out a new version of a
-configuration. A ReplicationController can be used for that and other purposes.
-All Deployments are ReplicationControllers, but all ReplicationControllers are
-not Deployments.
+Kubernetes-native objects that provide declarative updates for Pods and
+ReplicaSets.
+
+Do not confuse with DeploymentConfigs, which predate Deployments.
 
-To avoid confusion, do not refer to an overall OpenShift installation / instance
-/ cluster as an "OpenShift deployment".
+To avoid further confusion, do not refer to an overall OpenShift installation /
+instance / cluster as an "OpenShift deployment".
 
+See link:https://kubernetes.io/docs/concepts/workloads/controllers/deployment/[Deployments - Kubernetes].
 See link:doc_guidelines.adoc#api-object-formatting[API Object Formatting].
 
-''''
-=== Deployment controller
+=== DeploymentConfig
+
+Usage: DeploymentConfig(s)
+
+OpenShift-specific objects that define the template for a Pod and manage
+deploying new images or configuration changes. Uses ReplicationControllers.
 
-Usage: Deployment controller(s) as appropriate
+Do not confuse with the Kubernetes native object Deployment, which were
+introduced later and use ReplicaSets.
 
-Kubernetes object that creates a replication controller from a given Pod
-template.  If that Pod template is modified, the Deployment controller creates
-a new replication controller based on the modified Pod template and replaces the
-old replication controller with this new one.
+Do not use: deployment configuration(s)
 
 ''''
 === Dockerfile
@@ -266,7 +278,7 @@ allowed for use across all distribution documentation:
 
 Usage: OpenShift CLI
 
-This is the command line interface of OpenShift v3.
+The `oc` tool is the command line interface of OpenShift 3 and 4.
 
 ''''
 === OpenShift master
@@ -300,6 +312,9 @@ Install the etcd Operator.
 Build an Operator using the Operator SDK.
 ====
 
+See link:doc_guidelines.adoc#api-object-formatting[API Object Formatting] for
+more on Operator naming.
+
 == P
 
 ''''
@@ -327,13 +342,41 @@ like namespace is not capitalized.
 
 == R
 
+''''
+=== ReplicaSet
+
+Usage: ReplicaSet(s)
+
+Similar to a ReplicationController, a ReplicaSet is a native Kubernetes API
+object that ensures a specified number of pod replicas are running at any given
+time. Used by Deployments.
+
+Do not use: replica set(s)
+
+See link:https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/[ReplicaSet - Kubernetes].
+
 ''''
 === ReplicationController
 
 Usage: ReplicationController(s)
 
 Kubernetes object that ensures N (as specified by the user) instances of a given
-Pod are running at all times.
+Pod are running at all times. Used by DeploymentConfigs.
+
+Do not use: replication controller(s)
+
+''''
+=== Route
+
+Usage: Route(s)
+
+OpenShift-specific API object that allows developers to expose Services through
+an HTTP(S) aware load balancing and proxy layer via a public DNS entry. The
+Route may further specify TLS options and a certificate, or specify a public
+CNAME that the OpenShift router should also accept for HTTP and HTTPS traffic.
+An administrator typically configures their router to be visible outside the
+cluster firewall, and may also add additional security, caching, or traffic
+controls on the Service content.
 
 == S
 
@@ -346,6 +389,47 @@ Component of the Kubernetes master or OpenShift master that manages the state of
 the system, places Pods on nodes, and ensures that all containers that are
 expected to be running are actually running.
 
+''''
+=== secret
+
+Usage: secret(s)
+
+Kubernetes API object that holds secret data of a certain type.
+
+See link:https://kubernetes.io/docs/concepts/configuration/secret/[Secrets - Kubernetes].
+
+''''
+=== Service
+
+Usage: Service(s)
+
+Kubernetes native API object that serves as an internal load balancer. It
+identifies a set of replicated Pods in order to proxy the connections it
+receives to them. Backing Pods can be added to or removed from a Service
+arbitrarily while the Service remains consistently available, enabling anything
+that depends on the Service to refer to it at a consistent address.
+
+A Service is a named abstraction of software service (for example, `mysql`)
+consisting of local port (for example `3306`) that the proxy listens on, and the
+selector that determines which Pods will answer requests sent through the proxy.
+
+Capitalize when referring to the Kubernetes object specifically.
+
+Do not confuse with link:https://www.openservicebrokerapi.org/[Open Service Broker API related objects].
+See
+link:https://docs.openshift.com/container-platform/3.11/architecture/service_catalog/index.html#service-catalog-concepts-terminology[Service Catalog Concepts and Terminology].
+
+''''
+=== service account
+
+Usage: service account(s)
+
+A service account binds together:
+
+* a name, understood by users, and perhaps by peripheral systems, for an identity
+* a principal that can be authenticated and authorized
+* a set of secrets
+
 ''''
 === SkyDNS
 
@@ -376,3 +460,15 @@ Update the Pod spec to reflect the changes.
 ====
 
 ''''
+=== StorageClass
+
+Usage: StorageClass(es)
+
+Kubernetes API object that describes the parameters for a class of storage for
+which PersistentVolumes can be dynamically provisioned. StorageClasses are
+non-namespaced; the name of the StorageClass according to etcd is in
+ObjectMeta.Name.
+
+See link:https://kubernetes.io/docs/concepts/storage/storage-classes/[Storage Classes - Kubernetes].
+
+''''