PGAdmin CRD field reference for standalone pgAdmin 4

The PGAdmin custom resource deploys a standalone pgAdmin 4 web interface for managing PostgreSQL clusters. Unlike the embedded pgAdmin available via spec.userInterface.pgAdmin in a PostgresCluster, the standalone PGAdmin resource can connect to multiple clusters simultaneously — either by name or by label selector — making it the preferred choice for teams managing several clusters in a namespace. API group: postgres-operator.crunchydata.com/v1beta1 Kind: PGAdmin Scope: Namespaced

Connecting pgAdmin to a PostgresCluster

The spec.serverGroups field controls which PostgresCluster resources appear in pgAdmin. You can reference clusters by name or dynamically select them by label.

serverGroups:
  # Add a specific cluster by name
  - name: Production
    postgresClusterName: hippo

  # Dynamically add all clusters with a specific label
  - name: Staging Clusters
    postgresClusterSelector:
      matchLabels:
        environment: staging

Exactly one of postgresClusterName or postgresClusterSelector is required per server group. An empty postgresClusterSelector ({}) selects all clusters in the namespace.

PGO automatically registers the selected clusters as server connections in pgAdmin, using connection credentials from the cluster’s secrets. You do not need to configure server connections manually in the pgAdmin UI.

Example

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PGAdmin
metadata:
  name: hippo-pgadmin
spec:
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 1Gi
  serverGroups:
    - name: Production
      postgresClusterName: hippo
    - name: All Dev Clusters
      postgresClusterSelector:
        matchLabels:
          environment: development
  users:
    - username: admin@example.com
      passwordRef:
        name: pgadmin-admin-secret
        key: password
      role: Administrator
  config:
    settings:
      MAX_LOGIN_ATTEMPTS: 5
      SESSION_EXPIRATION_TIME: 60
  resources:
    requests:
      cpu: 250m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 512Mi

Spec fields

VolumeClaimSpec

required

PersistentVolumeClaim definition for pgAdmin’s data directory. Must include at least one accessMode and a storage request.

dataVolumeClaimSpec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: standard

[]ServerGroup

Groups of PostgresCluster resources to import into pgAdmin. Leave this field empty to create a pgAdmin instance with no auto-discovered servers. PostgresClusters can still be added manually through the pgAdmin UI.

Show serverGroup properties

string

required

Display name for this server group in pgAdmin. Must be unique among all serverGroups on this PGAdmin.

string

The name of a single PostgresCluster in the same namespace to add to this group. Mutually exclusive with postgresClusterSelector.

LabelSelector

A Kubernetes label selector that matches PostgresCluster resources to add to this group. Mutually exclusive with postgresClusterName. An empty selector ({}) matches all clusters in the namespace.

postgresClusterSelector:
  matchLabels:
    environment: production
  matchExpressions:
    - key: tier
      operator: In
      values: [database]

[]PGAdminUser

pgAdmin users managed declaratively through the PGAdmin spec. Users added through the pgAdmin web UI are not reflected here. Uses username as the list map key (must be unique).

Show user properties

string

required

The email address used as the pgAdmin login username. Must be unique in the users list.

SecretKeySelector

required

Reference to a Kubernetes Secret containing the user’s password.

passwordRef:
  name: pgadmin-users
  key: admin-password

string

The user’s role in pgAdmin. One of: Administrator, User. Default: User.

StandalonePGAdminConfiguration

Configuration settings for the pgAdmin process. Changes are applied without validation — an invalid configuration may leave pgAdmin in an unusable state.

Show config properties

object

Key-value settings for the pgAdmin server process, corresponding to entries in config_py. Keys should be uppercase. Values must be constants (strings, integers, or booleans).

config:
  settings:
    MAX_LOGIN_ATTEMPTS: 3
    SESSION_EXPIRATION_TIME: 480
    SECURITY_PASSWORD_HASH: "pbkdf2:sha512:260000"
    LOG_FILE: "/tmp/pgadmin4.log"

object

Settings for the Gunicorn WSGI server. See Gunicorn docs for available options.

config:
  gunicorn:
    workers: 2
    timeout: 120

OptionalSecretKeyRef

Reference to a Secret containing the value for pgAdmin’s CONFIG_DATABASE_URI setting. Used to configure an external database for pgAdmin’s own metadata. See pgAdmin external database docs.

config:
  configDatabaseURI:
    name: pgadmin-config-db
    key: uri
    optional: false

OptionalSecretKeyRef

Reference to a Secret containing the value for the LDAP_BIND_PASSWORD setting. See pgAdmin LDAP docs.

config:
  ldapBindPassword:
    name: pgadmin-ldap-secret
    key: password

[]PGAdminOAuthConfig

OAuth2 provider configurations for pgAdmin. Between 1 and 10 entries. Each entry requires a name and a secret reference containing the OAuth2 settings as a JSON object. Values are merged with any OAUTH2_CONFIG entries in config.settings. See pgAdmin OAuth2 docs.

config:
  oauthConfigurations:
    - name: google
      secret:
        name: pgadmin-google-oauth
        key: config.json

Show oauthConfigurations[] properties

string

required

The OAUTH2_NAME identifier for this configuration. Must be alphanumeric, 1–20 characters.

SecretKeyRef

required

Reference to a Secret containing the OAuth2 provider settings as a JSON object.

secret:
  name: my-oauth-secret
  key: provider.json

[]VolumeProjection

Projected volumes mounted into the pgAdmin container for referencing custom files (e.g. CA certificates, custom themes).

string

Container image for pgAdmin 4. When omitted, the operator uses the RELATED_IMAGE_PGADMIN environment variable.

string

Image pull policy for the pgAdmin container. One of: Always, Never, IfNotPresent.

[]LocalObjectReference

Image pull secrets for pulling the pgAdmin image from a private registry. Changing this value causes all running pgAdmin pods to restart.

imagePullSecrets:
  - name: my-registry-secret

ResourceRequirements

Compute resource requests and limits for the pgAdmin container.

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: "1"
    memory: 512Mi

Affinity

Kubernetes affinity rules for scheduling the pgAdmin pod.

[]Toleration

Tolerations for scheduling the pgAdmin pod onto tainted nodes.

string

Priority class name for the pgAdmin pod. Changing this value causes the pod to restart.

string

Name to use for the ClusterIP Service pointing to the pgAdmin pod. If a Service with this name already exists, PGO updates it. When omitted, the service is named after the PGAdmin resource.

PGAdminVolumesSpec

Additional volumes to add to the pgAdmin pod.

Show volumes properties

[]AdditionalVolume

Up to 10 additional pre-existing PVC or OCI image volumes. Each entry requires a name and either a claimName or image. Volumes are mounted at /volumes/{name}.

InstrumentationSpec

Configuration for the OpenTelemetry collector container used to collect logs and metrics from the pgAdmin pod.

Metadata

Labels and annotations to apply to all resources created for this pgAdmin instance.

metadata:
  labels:
    app.kubernetes.io/component: pgadmin
  annotations:
    example.com/owner: platform-team

Status fields

Field	Type	Description
`status.conditions`	`[]Condition`	Observations of pgAdmin’s current state. Known type: `PersistentVolumeResizing`.
`status.imageSHA`	`string`	Image SHA of the running pgAdmin container.
`status.majorVersion`	`integer`	The major version of the running pgAdmin.
`status.minorVersion`	`string`	The minor version of the running pgAdmin.
`status.observedGeneration`	`integer`	The `.metadata.generation` on which the status was last based.

Accessing pgAdmin

By default, the pgAdmin service is a ClusterIP Service. To access it from outside the cluster, use kubectl port-forward:

kubectl port-forward svc/hippo-pgadmin 5050:5050

Then open http://localhost:5050 in your browser. For external access, configure the spec.serviceName and a LoadBalancer or NodePort service using an ingress controller, or expose the service directly. See the Kubernetes services documentation for details.

The pgAdmin web UI default port is 5050. The PGAdmin service exposes this port by default. If you change the port via config.settings, you must also update your Service configuration accordingly.

Embedded vs. standalone pgAdmin

PGO supports two ways to run pgAdmin:

Feature	`spec.userInterface.pgAdmin` (embedded)	`PGAdmin` resource (standalone)
Location	Inside the `PostgresCluster` spec	Separate resource
Cluster scope	One `PostgresCluster` only	Multiple clusters via `serverGroups`
Management	Managed with the cluster lifecycle	Independent lifecycle
Recommended for	Simple, single-cluster setups	Multi-cluster or shared admin environments

PostgresCluster reference — embedded pgAdmin via spec.userInterface.pgAdmin
Connection pooling guide
Authentication guide

Custom Resources

Configuration

Troubleshooting

PGAdmin CRD field reference for standalone pgAdmin 4

Connecting pgAdmin to a PostgresCluster

Example

Spec fields

Status fields

Accessing pgAdmin

Embedded vs. standalone pgAdmin

​Connecting pgAdmin to a PostgresCluster

​Example

​Spec fields

​Status fields

​Accessing pgAdmin

​Embedded vs. standalone pgAdmin

​Related resources

Connecting pgAdmin to a PostgresCluster

Example

Spec fields

Status fields

Accessing pgAdmin

Embedded vs. standalone pgAdmin

Related resources