This topic provides guidelines for referring to the various components of OpenShift 4 and objects of a running OpenShift system in our documentation. The goal is to standardize terminology across OpenShift content and be consistent in the usage of our terminology when referring to OpenShift components or architecture.
|
Note
|
If you want to add terms or other content to this document, or if anything must be fixed, send an email to [email protected] or submit a PR on GitHub. |
Usage: action
An action consists of project, verb, and resource:
-
Project is the project containing the resource that is to be acted upon.
-
Verb is a get, list, create, or update operation.
-
Resource is the API endpoint being accessed. This is distinct from the referenced resource itself, which can be a Pod, DeploymentConfig, Build, etc.
Usage: apiserver(s) or API server(s) as appropriate
A REST API endpoint for interacting with the system. New deployments and configurations can be created with this endpoint, and the state of the system can be interrogated through this endpoint as well.
Usage: application(s)
Although the term application is no longer an official noun in OpenShift, customers still create and host applications on OpenShift, and using the term within certain contexts is acceptable. For example, the term application might refer to some combination of an image, a Git repository, or a replication controller, and this application might be running PHP, MySQL, Ruby, JBoss, or something else.
Examples of correct usage
OpenShift runs your applications.
The new-app command creates a new application from the components you specify.
My application has two Ruby web Services connected to a database back end and a RabbitMQ message queue, as well as a python worker framework.
You can check the health of your application by adding probes to the various parts.
You can host a WordPress application on OpenShift.
Usage: cluster
The collection of controllers, Pods, and Services and related DNS and networking routing configuration that are defined on the system.
Usage: ConfigMap(s)
ConfigMaps hold configuration data for Pods to consume.
Do not use: configuration map(s)
Usage: containerize(d)
Use "containerized" as an adjective when referring to applications made up of multiple services that are distributed in containers. "Containerized" can be used interchangeably with "container-based."
Usage: Deployment(s)
Kubernetes-native objects that provide declarative updates for Pods and ReplicaSets.
Do not confuse with DeploymentConfigs, which predate Deployments.
To avoid further confusion, do not refer to an overall OpenShift installation / instance / cluster as an "OpenShift deployment".
Usage: DeploymentConfig(s)
OpenShift-specific objects that define the template for a Pod and manage deploying new images or configuration changes. Uses ReplicationControllers.
Do not confuse with the Kubernetes native object Deployment, which were introduced later and use ReplicaSets.
Do not use: deployment configuration(s)
Usage: Dockerfile; wrapped with [filename] markup. See Documentation Guidelines for markup information.
Docker can build images automatically by reading the instructions from a Dockerfile. A Dockerfile is a text document that contains all the commands you would normally execute manually in order to build a Docker image.
Open the Dockerfile and make the following changes.
Create a Dockerfile at the root of your repository.
Usage: identity or identities as appropriate
Both the username and list of groups the user belongs to.
Usage: Ignition config file or Ignition config files
The file that Ignition uses to configure Red Hat Enterprise Linux CoreOS during operating system initialization. The installation program generates different Ignition config files to initialize bootstrap, master, and worker nodes.
Usage: Ingress
API object that allows developers to expose Services through an HTTP(S) aware load balancing and proxy layer via a public DNS entry. The Ingress resource may further specify TLS options and a certificate, or specify a public CNAME that the OpenShift Ingress Controller should also accept for HTTP and HTTPS traffic. An administrator typically configures their Ingress Controller to be visible outside the cluster firewall, and may also add additional security, caching, or traffic controls on the Service content.
Usage: kubelet(s) as appropriate
The agent that controls a Kubernetes node. Each node runs a kubelet, which handles starting and stopping containers on a node, based on the desired state defined by the master.
Usage: Kubernetes master(s) as appropriate
The Kubernetes-native equivalent to the OpenShift master. An OpenShift system runs OpenShift masters, not Kubernetes masters, and an OpenShift master provides a superset of the functionality of a Kubernetes master, so it is generally preferred to use the term OpenShift master.
Usage: Deprecated. Use node instead.
Usage: OpenShift Container Platform, OpenShift Online, OpenShift Dedicated, OpenShift Container Engine
The OpenShift product name should be paired with its product distribution / variant name whenever possible. Previously, the upstream distribution was called OpenShift Origin, however it is now called OKD; use of the OpenShift Origin name is deprecated.
Avoid using the name "OpenShift" on its own when referring to something that applies to all distributions, as OKD does not have OpenShift in its name. However, the following components currently use "OpenShift" in the name and are allowed for use across all distribution documentation:
-
OpenShift Ansible Broker
-
OpenShift Pipeline
-
OpenShift SDN
Usage: OpenShift CLI (oc)
The oc tool is the command line interface of OpenShift 3 and 4.
When referencing as a prerequisite for a procedure module, use the following
construction: Install the OpenShift Command-line Interface (CLI), commonly known
as oc.
When referencing in overview text, use: OpenShift CLI (oc).
Usage: OpenShift master(s) as appropriate
Provides a REST endpoint for interacting with the system and manages the state of the system, ensuring that all containers expected to be running are actually running and that other requests such as builds and deployments are serviced. New deployments and configurations are created with the REST API, and the state of the system can be interrogated through this endpoint as well. An OpenShift master comprises the apiserver, scheduler, and SkyDNS.
Usage: Operator(s)
An Operator is a method of packaging, deploying and managing a Kubernetes
application. A Kubernetes application is an application that is both deployed on
a Kubernetes cluster (including OpenShift clusters) and managed using the
Kubernetes APIs and kubectl or oc tooling.
While "containerized" is allowed, do not use "Operatorize" to refer to building an Operator that packages an application.
Install the etcd Operator.
Build an Operator using the Operator SDK.
See API Object Formatting for more on Operator naming.
Usage: Options menu; use sparingly; not to be confused with Actions menu, which signifies a specific menu seen in the web console.
This describes a menu type commonly called a "kebab", "hamburger", or "overflow" menu that does not have hover text or a given name or label in the web console.
Usage: Pod(s) as appropriate
Kubernetes object that groups related Docker containers that have to share network, filesystem, or memory together for placement on a node. Multiple instances of a Pod can run to provide scaling and redundancy.
Usage: project(s)
A project allows a community of users to organize and manage their content in isolation from other communities. It is an extension of the namespace object from Kubernetes.
Even though projects are an OpenShift API object, it is not capitalized, much like namespace is not capitalized.
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)
Usage: ReplicationController(s)
Kubernetes object that ensures N (as specified by the user) instances of a given Pod are running at all times. Used by DeploymentConfigs.
Do not use: replication controller(s)
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 Ingress Controller should also accept for HTTP and HTTPS traffic. An administrator typically configures their Ingress Controller to be visible outside the cluster firewall, and may also add additional security, caching, or traffic controls on the Service content.
Usage: scheduler(s) as appropriate
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.
Usage: secret(s)
Kubernetes API object that holds secret data of a certain type.
See Secrets - Kubernetes.
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 Open Service Broker API related objects. See Service Catalog Concepts and Terminology.
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
Usage: SkyDNS
Component of the Kubernetes master or OpenShift master that provides cluster-wide DNS resolution of internal host names for Services and Pods.
Usage: Source-to-Image for the first time reference; S2I thereafter.
Deprecated abbreviation (do not use): STI
Usage: spec(s)
In addition to "spec file" being allowed related to RPM spec files, general usage of "spec" is allowed when describing Kubernetes or OpenShift object specs / manifests / definitions.
Examples of correct usage
Update the Pod spec to reflect the changes.
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.