[id="contributing-to-docs-term-glossary"]
= OpenShift glossary of terms
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:

toc::[]

== Usage of OpenShift terms

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.

[IMPORTANT]
====
Do not backport `term_glossary.adoc` file updates to enterprise branches. An enterprise branch is created from the latest enterprise branch and not the `main` branch. Asynchronous behavior can occur between `main` and an enterprise branch if you complete a backport operation.
====

For terms that are also API objects, there is different guidance for general usage of the term compared to referencing the actual API object. This glossary mainly defines the general usage guideline (lowercase, separating words), but be sure to use the object formatting (PascalCase, in monospace) when referring to the actual object. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more information.

[NOTE]
====
If you want to add terms or other content to this document, or if anything must be fixed, send an email to openshift-docs@redhat.com or submit a PR on GitHub. Do not bundle the glossary term update in a regular writing assignment PR.
====

== A

''''
=== action

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, deployment, build, etc.

''''
=== API server

Usage: API server(s)

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.

''''
=== API service

Usage: API service(s)

When referencing the actual object, write as `APIService`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

''''
=== app

Usage: app(s)

Acceptable when referring to a mobile or web xref:application[application].

''''
[id="application"]
=== application

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, and 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.
====

''''
=== Assisted Installer

Usage: Assisted Installer

In Red Hat OpenShift, the Assisted Installer is an installation solution that is offered on the Red Hat Hybrid Cloud Console to provide Software-as-a-Service functionality for cluster installations. The Assisted Installer supports installing OpenShift Container Platform on premises in a connected environment. The Assisted Installer is used for connected deployments.

Do not use: AI, assisted installer

''''
=== authorization

Usage: authorization

An authorization determines whether an _identity_ is allowed to perform any
action. It consists of _identity_ and _action_.

== B

''''
=== boot image

Usage: boot image(s)

* A boot image is a disk image that contains a bootable operating system (OS) and all the configuration settings for the OS, such as drivers.

''''
=== build

Usage: build(s), or when speaking generally about `Build` objects.

* A build is the process of transforming input parameters into a resulting object.
* A `Build` object encapsulates the inputs needed to produce a new deployable image, as well as the status of the execution and a reference to the pod that executed the build.

When referencing the actual object, write as "``Build`` object" as appropriate. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

''''
=== build configuration

Usage: build configuration(s) when speaking generally about `BuildConfig` objects.

A `BuildConfig` object is the definition of the entire build process. A build configuration describes a single build definition and a set of triggers for when a new build is created.

When referencing the actual object, write as "``BuildConfig`` object" as appropriate. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

== C

''''
=== cluster

Usage: cluster

The collection of controllers, pods, and services and related DNS and networking
routing configuration that are defined on the system.

''''
=== Cluster API

Usage: Cluster API

Cluster API is a Kubernetes subproject focused on providing declarative APIs and tooling to simplify provisioning, upgrading, and operating multiple Kubernetes clusters.^[link:https://github.com/kubernetes-sigs/cluster-api?tab=readme-ov-file#-what-is-the-cluster-api[1]]^
For more information, see the link:https://github.com/kubernetes-sigs/cluster-api[Cluster API project repository].

Depending on the platform and version support status, Cluster API replaces Terraform in the OpenShift installation process and can be used to manage machines.

The only legitimate use of the term "CAPI" in documentation is within the name of the downstream OpenShift _Cluster CAPI Operator_.
To avoid using "CAPI" in plain text when referring to this Operator, use the `{cluster-capi-operator}` attribute in the link:https://github.com/openshift/openshift-docs/blob/main/_attributes/common-attributes.adoc[common attributes file].

Do not use: CAPI

''''
=== Cluster API provider implementations

Usage examples: Cluster API Provider AWS, Cluster API Provider GCP, Cluster API Provider OpenStack

A platform-specific implementation of the Cluster API that supports cloud provider infrastructure.

[NOTE]
====
* Do not insert the word "for" before the platform name.

* Do not use initialisms.

* To avoid common typos, use the attributes in the _Cluster API terminology_ section of the link:https://github.com/openshift/openshift-docs/blob/main/_attributes/common-attributes.adoc[common attributes file].
====

Do not use: CAPA, CAPG, CAPIBM, CAPK, CAPZ, CAPX, CAPO, CAPOCI, CAPV, Cluster API Provider for AWS

''''
=== cluster service version

Usage: cluster service version

Operator Lifecycle Manager (OLM), part of the Operator Framework, uses a cluster service version (CSV) to define the metadata that accompanies an Operator container image and assist in running the Operator in a cluster. This metadata is defined in a `ClusterServiceVersion` API object used to populate user interfaces with information such as its logo, description, and version. It is also a source of technical information that is required to run the Operator, like the RBAC rules it requires and which custom resources (CRs) it manages or depends on.

This is commonly abbreviated as a CSV.

''''
=== config map

Usage: config map(s)

Config maps hold configuration data for pods to consume.

When referencing the actual object, write as `ConfigMap`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

Do not use: configuration map(s)

''''
=== container

Usage: container(s)

''''
=== containerize

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."

''''
=== container group

Usage: container group

''''
=== control plane

Usage: control plane

The control plane, which is composed of control plane machines, manages the {product-title} cluster. The control plane machines manage workloads on the compute machines, which are also known as worker machines.

Note that the OpenShift "control plane" was previously known as "master" and could still be in the code.

''''
=== custom resource

Usage: custom resource (CR)

A resource implemented through the Kubernetes `CustomResourceDefinition` API. A custom resource is distinct from the built-in Kubernetes resources, such as the pod and service resources. Every CR is part of an API group.

Do not capitalize.

''''
=== custom resource definition (CRD)

Usage: custom resource definition (CRD) for the first time reference; CRD thereafter.

Create a custom resource definition to define a new custom resource.

This is commonly abbreviated as a CRD.

== D

''''
=== deployment

Usage: deployment(s) when speaking generally about `Deployment` or `DeploymentConfig` objects

* A `Deployment` is a Kubernetes-native object that provides declarative updates for pods and
replica sets.
* A `DeploymentConfig` is an OpenShift-specific object that defines the template for a pod and manages
deploying new images or configuration changes. Uses replication controllers. Predates Kubernetes `Deployment` objects.

When referencing the actual object, write as `Deployment` or `DeploymentConfig` as appropriate. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

To avoid further confusion, do not refer to an overall OpenShift installation /
instance / cluster as an "OpenShift deployment".

Do not use: deployment configuration(s), deployment config(s)

''''
=== disconnected

Usage: disconnected environment, disconnected installation

Use "disconnected" when discussing installing a cluster in an environment that does not have an active connection to the internet. Use "disconnected" regardless of whether the restriction is physical or logical.

"Disconnected" is the preferred term over "restricted", "air-gapped", or "offline".

''''
=== Dockerfile

Usage: Dockerfile; wrapped with [filename] markup. See
link:doc_guidelines.adoc[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 to build a docker image.

Source: https://docs.docker.com/reference/builder/

.Examples of correct usage
====
Open the [filename]#Dockerfile# and make the following changes.

Create a [filename]#Dockerfile# at the root of your repository.
====

== E

''''
=== event

Usage: event(s)

An event is a data record expressing an occurrence and its context, based on the CNCF CloudEvents specification.
Events contain two types of information: the event data representing the occurrence, and the context metadata providing contextual information about the occurrence.
Events are routed from an event producer, or source, to connected event consumers.

Routing can be performed based on information contained in the event, but an event will not identify a specific routing destination.
Events can be delivered through various industry standard protocols such as HTTP, AMQP, MQTT, or SMTP, or through messaging and broker systems, such as Kafka, NATS, AWS Kinesis, or Azure Event Grid.

When referencing the actual object, write as `Event`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

// NOTE: This is inconsistently used, e.g. https://docs.openshift.com/container-platform/4.5/rest_api/metadata_apis/event-core-v1.html
See: link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#event-v1-core[Event v1 core API], link:https://github.com/cloudevents/spec/blob/master/primer.md#cloudevents-concepts[CloudEvents concepts], and link:https://github.com/cloudevents/spec/blob/master/spec.md#event[CloudEvents specification].

== F

== G

''''
=== group/version/kind (GVK)

Usage: group/version/kind (GVK) for the first time reference; GVK thereafter.

A unique identifier for a Kubernetes API, specifying its _group_ (a collection of related APIs), _version_ (defines the release and level of stability), and _kind_ (an individual API type or name).

While "GroupVersionKind" does appear in the API guide, typically there should not be a reason to mark up in reference to a specific object. Favor simply "GVK", or "GVKs" for pluralization, after the first time reference as much as possible. Avoid pluralizing the long form (e.g., group/version/kinds or groups/versions/kinds).

== H

''''
=== hosted control planes

Usage: hosted control planes or Hosted control planes

When referencing hosted control planes for the first time, write as "hosted control planes for {product-title}". Capitalize the “h” in “hosted control planes” only when “hosted” is the first word in a title, heading, or sentence. Use lowercase “h” for subsequent references of hosted control planes.

Avoid referencing hosted control planes as HyperShift in any customer-facing content as HyperShift is the internal name.

In the documentation for hosted control planes with ROSA, the writers are allowed to use “HCP with ROSA”, per branding.

== I

''''
=== identity

Usage: identity or identities

Both the user name and list of groups the user belongs to.

''''
=== image

Usage: image(s)

''''
=== image stream

Usage: image stream(s)

Image streams provide a means of creating and updating container images in an ongoing way.

''''
=== Ignition config

Usage: Ignition config file or Ignition config files

The file that Ignition uses to configure Red Hat Enterprise Linux CoreOS (RHCOS) during
operating system initialization. The installation program generates different
Ignition config files to initialize bootstrap, control plane, and worker nodes.

''''

=== Ingress

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 might also add additional security, caching, or
traffic controls on the service content.

''''

=== Ingress Controller

Usage: Ingress Controller(s)

A resource that forwards traffic to endpoints of services. The Ingress Controller
replaces router from {product-title} 3 and earlier.

''''
=== installer-provisioned infrastructure

Usage: installer-provisioned infrastructure

If the installation program deploys and configures the infrastructure that the
cluster runs on, it is an installer-provisioned infrastructure installation.

Do not use: IPI

== J

== K

''''
=== kubelet

Usage: kubelet(s)

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 control plane (also known as master).

''''
=== Kubernetes API server

Usage: Kubernetes API server

== L

== M

''''
=== MetalLB

Usage: MetalLB, MetalLB Operator, MetalLB project

MetalLB is an open source project that provides a way to add services of type `LoadBalancer` to clusters that are not installed on infrastructure from a cloud provider. MetalLB primarily targets on-premise, bare-metal clusters, but any infrastructure that does not include a native load-balancing capability is a candidate.

"MetalLB" always has the first letter and last two letters capitalized in general text. Do not use "Metallb."

''''
=== minion

Usage: Deprecated. Use link:#node[node] instead.

== N

''''
=== node

Usage: node(s)

A
http://docs.openshift.org/latest/architecture/infrastructure_components/kubernetes_infrastructure.html#node[node]
provides the runtime environments for containers.

''''
=== namespace

Usage: namespace

Typically synonymous with link:#project[project] in OpenShift parlance, which is
preferred.

== O

''''
=== OpenShift

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 Pipeline
- OpenShift SDN
- OpenShift Ansible Broker (deprecated in 4.2 / removed in 4.4)

''''
=== OpenShift API server

Usage: OpenShift API server

''''
=== OpenShift CLI

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 CLI (`oc`).

''''
=== Operator

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.

The term "Operator" is always captalized.

While "containerized" is allowed, do not use "Operatorize" to refer to building an
Operator that packages an application.

.Examples of correct usage
====
Install the etcd Operator.
====

See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for
more on Operator naming.

''''
=== OperatorHub

Usage: OperatorHub

''''
=== Operator Lifecycle Manager (OLM)
Usage: Operator Lifecycle Manager, OLM

Refer to this component without a preceding article ("the").

.Examples of correct usage
====
You can use OpenShift Lifecycle Manager (OLM) to manually or automatically upgrade an Operator.
====

''''
=== Options menu

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.

''''

== P

''''
=== persistent volume (PV)

Usage: persistent volume

Developers can use a persistent volume claim (PVC) to request a persistent volume (PV) resource without having specific knowledge of the underlying storage infrastructure.

''''
=== persistent volume claim (PVC)

Usage: persistent volume claim

Developers can use a persistent volume claim (PVC) to request a persistent volume (PV) resource without having specific knowledge of the underlying storage infrastructure.

''''
=== pod

Usage: pod(s)

Kubernetes object that groups related Docker containers that have to share
network, file system, or memory together for placement on a node. Multiple
instances of a pod can run to provide scaling and redundancy.

When referencing the actual object, write as `Pod`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

''''
=== project

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.

When referencing the actual object, write as `Project`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

== Q

''''
=== quick start

Usage: quick start(s)

There are two types of quick starts in OpenShift:

* quick starts that are guided tutorials in the web console
* quick start templates that allow users to quickly get started creating a new application

Be sure to provide context about which type of quick start you are referring to.

== R

''''
=== replica set

Usage: replica set(s)

Similar to a replication controller, a replica set is a native Kubernetes API
object that ensures a specified number of pod replicas are running at any given
time. Used by `Deployment` objects.

When referencing the actual object, write as `ReplicaSet`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

See link:https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/[ReplicaSet - Kubernetes].

''''
=== replication controller

Usage: replication controller(s)

Kubernetes object that ensures N (as specified by the user) instances of a given
pod are running at all times. Used by deployment configs.

''''
=== 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 might 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 might also add additional security,
caching, or traffic controls on the service content.

== S

''''
=== scheduler

Usage: scheduler(s)

Component of the Kubernetes control plane or OpenShift control plane 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].

''''
=== security context constraints (SCC)

Usage: security context constraints

Security context constraints govern the ability to make requests that affect the security context that will be applied to a container.

When referencing the actual object, write as `SecurityContextConstraints`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

This is commonly abbreviated as SCC.

''''
=== service

Usage: service(s)

Kubernetes native API object that serves as an internal load balancer. It
identifies a set of replicated pods 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.

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

''''
=== single-node OpenShift

Usage: single-node OpenShift

Single-node OpenShift (or {product-title} on a single-node cluster) is a deployment footprint that provides control plane and worker node capabilities in a single server for deployments in constrained environments.

Do not use: Single Node Openshift (SNO).

''''
=== three-node OpenShift

Usage: three-node OpenShift

Three-node OpenShift is a compact cluster deployment footprint on three nodes for deployments in constrained environments. It provides three control plane nodes that you configure as schedulable for workloads.

Do not use: Three Node Openshift.

''''
=== SkyDNS

Usage: SkyDNS

Component of the Kubernetes control plane or OpenShift control plane that provides
cluster-wide DNS resolution of internal hostnames for services and pods.

''''
=== Source-to-Image (S2I)

Usage: Source-to-Image for the first time reference; S2I thereafter.

Deprecated abbreviation (do not use): STI

''''
=== spec

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.
====

''''
=== storage class

Usage: storage class(es)

Kubernetes API object that describes the parameters for a class of storage for
which persistent volumes can be dynamically provisioned. storage classes are
non-namespaced; the name of the storage class according to etcd is in
`ObjectMeta.Name`.

When referencing the actual object, write as `StorageClass`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details.

See link:https://kubernetes.io/docs/concepts/storage/storage-classes/[Storage Classes - Kubernetes].

== T

== U

''''
=== update

Usage: update

Use "update" when referring to updating the cluster to a new version. Although "upgrade" is sometimes used interchangeably, "update" is the preferred term to use, for consistency.


''''
=== user-provisioned infrastructure

Usage: user-provisioned infrastructure

If the user must deploy and configure separate virtual or physical hosts as part of
the cluster deployment process, it is a user-provisioned infrastructure
installation.

Do not use: UPI

''''

== V

== W

== X

== Y

== Z
