Skip to content

Kubernetes basics

The Kubernetes you need to install, operate and debug pg-regression-radar, and nothing more.

Overview

pg-regression-radar is built to run in Kubernetes, and its manager mode is driven by Kubernetes objects: you describe what to watch in YAML, and the radar does the rest. You do not need to be a Kubernetes administrator to use it, but you do need a working model of a handful of concepts: objects and namespaces, Deployments, Secrets, Services, custom resources, RBAC and Helm. This section teaches exactly those, always from the point of view of what the radar does with each one.

Every page follows the same shape: the concept in a few paragraphs, the kubectl commands you will actually type, and a short "In pg-regression-radar" part that ties it back to the tool.

What this section does not cover

Building or sizing a cluster, choosing a CNI or a storage class, autoscaling, service meshes, GitOps tooling and Postgres operators (CloudNativePG and friends) are out of scope. If you can already run kubectl get pods against a cluster you are allowed to use, you have everything this section assumes.

What you need on your machine

Tool Needed for Check
kubectl everything on these pages kubectl version --client
helm (3.x) only the Helm install path (Helm basics) helm version
A cluster and a kubeconfig a place to run the radar: kind, minikube, k3d, Docker Desktop, or a real cluster kubectl config current-context

kubectl talks to whichever cluster your current context points at. Before running anything that changes state, confirm you are where you think you are:

kubectl config current-context
kubectl config get-contexts
kubectl get nodes

Check the context before you apply

The most common Kubernetes mistake is applying a manifest to the wrong cluster. kubectl apply does not ask for confirmation. If you work with more than one cluster, make kubectl config current-context a habit before every install or delete.

What permissions you need

Installing the radar in manager mode creates cluster-scoped objects (CustomResourceDefinitions, a ClusterRole and a ClusterRoleBinding), so the person installing it needs cluster-level rights. You can check before you start:

kubectl auth can-i create customresourcedefinitions
kubectl auth can-i create clusterroles
kubectl auth can-i create deployments -n <ns>

operator mode creates nothing cluster-scoped: a Deployment, a Service, a ServiceAccount and a Secret in one namespace are enough. See RBAC and access for what each mode asks for.

How the concepts map to the radar

Kubernetes concept What pg-regression-radar does with it Page
Object, spec and status You write spec; the radar writes status (phase, message, results) Objects and namespaces
Namespace Scopes your PostgresWatch, DeploySource and Secrets; the radar's own home Objects and namespaces
Labels and annotations The consent label on your DSN Secret; the revision annotation on a Deployment Objects and namespaces
Deployment, rollout The radar itself runs as a Deployment; a finished rollout of your app is a deploy event Pods and Deployments
Probes, requests, limits Health of the radar's pods; the namespace quota the chart can create Pods and Deployments
Secret Holds the Postgres DSN, the webhook token and alert credentials Config and Secrets
Service, DNS, port-forward How a webhook sender reaches the radar, and how the radar reaches Postgres Services and networking
NetworkPolicy Optional default-deny rules the chart can render Services and networking
CustomResourceDefinition, controller PostgresWatch, DeploySource, PerformanceRegression, PostgresRadarCluster CRDs and operators
ServiceAccount, Role, ClusterRole The permissions the manager has, and why they are what they are RBAC and access
Helm chart, release, values The supported way to install and upgrade Helm basics
Events, logs, conditions How you find out why something is not working Troubleshooting toolkit

Suggested reading order

Conventions on these pages

  • <ns> stands for the namespace the radar is installed in. In the lab it is pgrr-lab.
  • <fullname> stands for the name Helm gives the chart's objects: the release name, plus the chart name unless the release name already contains it. Find the real value with kubectl get deploy -n <ns>.
  • Commands that only read are shown plain. Commands that change something say so in the text around them.
  • Every command works with a plain kubectl; none of them needs a plugin.

A ten-minute look at a running install

If the radar is already running (the lab is the easiest way to get one), these four commands show you most of what the rest of the section explains:

# 1. The radar's pods. Look for READY 1/1 and STATUS Running.
kubectl get pods -n <ns>

# 2. The things you configure, in one call (short names, see "CRDs and operators").
kubectl get postgreswatch,deploysource -n <ns>

# 3. The things the radar produces.
kubectl get performanceregressions -n <ns>

# 4. What the radar says about itself.
kubectl logs -n <ns> deployment/<fullname>-manager --tail=50

If any of these shows something you do not recognise, the page for that concept is in the table above.

See also