Demystify use of the term cluster in the context of Kubernetes

[shashimara]

it is troubling the use of the generic name "cluster" for PG custom resources. Many not familiar with the postgres assume "cluster" is referring to the Kubernetes cluster.

It will be good for commands in the doc if you could use PG-Cluster-name so the customers are aware of what is that support is looking adn will not error out while sending the document for troubleshooting

For Example / suggestion
kubectl cnp restart [PGclusterName]

kubectl cnp report cluster <PGclusterName> [flags]

Thanks

[josh-heyer]

Not sure I'm a fan of that particular placeholder name, but agree there can be ambiguity right now - we'll try to make time for a review of the use of "cluster" in these docs in the future!

[djw-m]

Not sure I'm a fan of that particular placeholder name, but agree there can be ambiguity right now - we'll try to make time for a review of the use of "cluster" in these docs in the future!

Added to that is the use of the word cluster is embedded in various commands and baked into the CNPG docs. In both those examples above, they are referring to a Kubernetes cluster which is configured with Postgres instances.

Taking this over to the Terminology discussion elsewhere, but am concerned that there is no obvious way to discriminate between two completely different cultural uses of cluster without always prefixing - postgres-cluster kubernetes-cluster - in all references.

[djw-m]

This is more for the meta issue of text references to clusters: https://docs.google.com/document/d/1hNyLSVi6DTw2Bd3069fz9ctiNAi_HTi2jTgnRKBLdsQ/edit?usp=sharing

Basically:

There are a lot of clusters in the EDB world.

Trying to not use the word cluster is not going to work. There are few alternatives and most clash with common usage.

Therefore, this proposal is to make it an essential style rule that all clusters are preceded by a clarifying type.

Postgres cluster - A Postgres server which hosts a number of databases (trad Postgres community usage)

PGD cluster - A Postgres Distributed system comprised of a top-level group of nodes and subgroups.

K8S/Kuberbetes cluster - A Kubernetes cluster, multiple nodes which run containerized applications (trad K8S community usage)

---

With reference to the original issue this would translate to a placeholder name of PostgresClusterName

[josh-heyer]

Closing in favor of #4879