Documentation ¶
Overview ¶
Crunchy PostgreSQL Operator API
The Crunchy PostgreSQL Operator API defines HTTP(S) interactions with the Crunchy PostgreSQL Operator.
## Direct API Calls
The API can also be accessed by interacting directly with the API server. This can be done by making HTTP requests with curl to get information from the server. In order to make these calls you will need to provide certificates along with your request using the `--cacert`, `--key`, and `--cert` flags. Next you will need to provide the username and password for the RBAC along with a header that includes the content type and the `--insecure` flag. These flags will be the same for all of your interactions with the API server and can be seen in the following examples.
###### Get API Server Version
The most basic example of this interaction is getting the version of the API server. You can send a GET request to `$PGO_APISERVER_URL/version` and this will send back a json response including the API server version. You must specify the client version that matches the API server version as part of the request.
The API server is setup to work with the pgo command line interface so the parameters that are passed to the server can be found by looking at the related flags. ``` curl --cacert $PGO_CA_CERT --key $PGO_CLIENT_KEY --cert $PGO_CA_CERT -u \ pgoadmin:examplepassword -H "Content-Type:application/json" --insecure -X \ GET $PGO_APISERVER_URL/version ```
#### Body examples In the following examples data is being passed to the apiserver using a json structure. These json structures are defined in the following documentation.
``` curl --cacert $PGO_CA_CERT --key $PGO_CLIENT_KEY --cert $PGO_CA_CERT -u \ pgoadmin:examplepassword -H "Content-Type:application/json" --insecure -X GET \ "$PGO_APISERVER_URL/workflow/<id>?version=<client-version>&namespace=<namespace>" ```
###### Create Cluster You can create a cluster by sending a POST request to `$PGO_APISERVER_URL/clusters`. In this example `--data` is being sent to the API URL that includes the client version that was returned from the version call, the namespace where the cluster should be created, and the name of the new cluster.
``` curl --cacert $PGO_CA_CERT --key $PGO_CLIENT_KEY --cert $PGO_CA_CERT -u \ pgoadmin:examplepassword -H "Content-Type:application/json" --insecure -X \
POST --data \ '{"ClientVersion":"4.3.0", "Namespace":"pgouser1", "Name":"mycluster",
$PGO_APISERVER_URL/clusters ```
###### Show and Delete Cluster The last two examples show you how to `show` and `delete` a cluster. Notice how instead of passing `"Name":"mycluster"` you pass `"Clustername":"mycluster" to reference a cluster that has already been created. For the show cluster example you can replace `"Clustername":"mycluster"` with `"AllFlag":true` to show all of the clusters that are in the given namespace.
``` curl --cacert $PGO_CA_CERT --key $PGO_CLIENT_KEY --cert $PGO_CA_CERT -u \ pgoadmin:examplepassword -H "Content-Type:application/json" --insecure -X \
POST --data \ '{"ClientVersion":"4.3.0", "Namespace":"pgouser1", "Clustername":"mycluster"}' \
$PGO_APISERVER_URL/showclusters ```
``` curl --cacert $PGO_CA_CERT --key $PGO_CLIENT_KEY --cert $PGO_CA_CERT -u \ pgoadmin:examplepassword -H "Content-Type:application/json" --insecure -X \
POST --data \ '{"ClientVersion":"4.3.0", "Namespace":"pgouser1", "Clustername":"mycluster"}' \
$PGO_APISERVER_URL/clustersdelete ```
Schemes: http, https BasePath: / Version: 4.3.0 License: Apache 2.0 http://www.apache.org/licenses/LICENSE-2.0 Contact: Crunchy Data<info@crunchydata.com> https://www.crunchydata.com/ Consumes: - application/json Produces: - application/json
swagger:meta
Index ¶
- Constants
- Variables
- func Kind(kind string) schema.GroupKind
- func Resource(resource string) schema.GroupResource
- type PgContainerResources
- type PgStorageSpec
- type Pgcluster
- type PgclusterList
- type PgclusterSpec
- type PgclusterState
- type PgclusterStatus
- type Pgpolicy
- type PgpolicyList
- type PgpolicySpec
- type PgpolicyState
- type PgpolicyStatus
- type Pgreplica
- type PgreplicaList
- type PgreplicaSpec
- type PgreplicaState
- type PgreplicaStatus
- type Pgtask
- type PgtaskList
- type PgtaskSpec
- type PgtaskState
- type PgtaskStatus
- type PodAntiAffinityDeployment
- type PodAntiAffinitySpec
- type PodAntiAffinityType
- type TLSSpec
Constants ¶
const ( // PgclusterStateCreated ... PgclusterStateCreated PgclusterState = "pgcluster Created" // PgclusterStateProcessed ... PgclusterStateProcessed PgclusterState = "pgcluster Processed" // PgclusterStateInitialized ... PgclusterStateInitialized PgclusterState = "pgcluster Initialized" // PgclusterStateRestore ... PgclusterStateRestore PgclusterState = "pgcluster Restoring" // PgclusterStateShutdown indicates that the cluster has been shut down (i.e. the primary) // deployment has been scaled to 0 PgclusterStateShutdown PgclusterState = "pgcluster Shutdown" // PodAntiAffinityRequired results in requiredDuringSchedulingIgnoredDuringExecution for any // default pod anti-affinity rules applied to pg custers PodAntiAffinityRequired PodAntiAffinityType = "required" // PodAntiAffinityPreffered results in preferredDuringSchedulingIgnoredDuringExecution for any // default pod anti-affinity rules applied to pg custers PodAntiAffinityPreffered PodAntiAffinityType = "preferred" // PodAntiAffinityDisabled disables any default pod anti-affinity rules applied to pg custers PodAntiAffinityDisabled PodAntiAffinityType = "disabled" )
const ( // PGUserAdmin is a special user that can perform administrative actions // without being a superuser itself PGUserAdmin = "crunchyadm" // PGUserMonitor is the monitoring user that can access metric data PGUserMonitor = "ccp_monitoring" // PGUserPgBouncer is the user that's used for managing pgBouncer, which a // user can use to access pgBouncer stats, etc. PGUserPgBouncer = "pgbouncer" // PGUserReplication is the user that's used for replication, which has // elevated privileges PGUserReplication = "primaryuser" // PGUserSuperuser is the superuser account that can do anything PGUserSuperuser = "postgres" )
the following are standard PostgreSQL user service accounts that are created as part of managed the PostgreSQL cluster environment via the Operator
const ( // this type of backup is taken following a failover event BackupTypeFailover string = "failover" // this type of backup is taken when a new cluster is being bootstrapped BackupTypeBootstrap string = "bootstrap" )
Defines the types of pgBackRest backups that are taken throughout a clusters lifecycle
const CollectSecretSuffix = "-collect-secret"
CollectSecretSuffix ...
const CompletedStatus = "completed"
CompletedStatus -
const GroupName = "crunchydata.com"
GroupName is the group name used in this package. const GroupName = "cr.client-go.k8s.io"
const InProgressStatus = "in progress"
InProgressStatus -
const JobCompletedStatus = "job completed"
JobCompletedStatus ....
const JobErrorStatus = "job error"
JobErrorStatus ....
const JobSubmittedStatus = "job submitted"
JobSubmittedStatus ....
const PgBackupJobSubmitted = "Backup Job Submitted"
this is ported over from legacy backup code
const PgclusterResourcePlural = "pgclusters"
PgclusterResourcePlural ..
const PgpolicyResourcePlural = "pgpolicies"
PgpolicyResourcePlural ...
const PgreplicaResourcePlural = "pgreplicas"
PgreplicaResourcePlural ..
const PgtaskAddPgbouncer = "add-pgbouncer"
const PgtaskAddPolicies = "addpolicies"
const PgtaskAutoFailover = "autofailover"
const PgtaskBackrest = "backrest"
const PgtaskBackrestBackup = "backup"
const PgtaskBackrestInfo = "info"
const PgtaskBackrestRestore = "restore"
const PgtaskBackrestStanzaCreate = "stanza-create"
const PgtaskCloneStep1 = "clone-step1" // performs a pgBackRest repo sync
const PgtaskCloneStep2 = "clone-step2" // performs a pgBackRest restore
const PgtaskCloneStep3 = "clone-step3" // creates the Pgcluster
const PgtaskDeleteBackups = "delete-backups"
const PgtaskDeleteData = "delete-data"
const PgtaskDeletePgbouncer = "delete-pgbouncer"
const PgtaskFailover = "failover"
const PgtaskMinorUpgrade = "minorupgradecluster"
const PgtaskResourcePlural = "pgtasks"
PgtaskResourcePlural ...
const PgtaskUpdatePgbouncer = "update-pgbouncer"
const PgtaskWorkflow = "workflow"
const PgtaskWorkflowBackrestRestoreJobCreatedStatus = "restore job created"
const PgtaskWorkflowBackrestRestorePVCCreatedStatus = "restored PVC created"
const PgtaskWorkflowBackrestRestorePrimaryCreatedStatus = "restored Primary created"
const PgtaskWorkflowBackrestRestoreType = "pgbackrestrestore"
const PgtaskWorkflowBackupType = "backupworkflow"
const PgtaskWorkflowCloneClusterCreate = "clone 3: cluster creating"
const PgtaskWorkflowCloneCreatePVC = "clone 1.1: create pvc"
const PgtaskWorkflowCloneRestoreBackup = "clone 2: restoring backup"
const PgtaskWorkflowCloneSyncRepo = "clone 1.2: sync pgbackrest repo"
const PgtaskWorkflowCloneType = "cloneworkflow"
const PgtaskWorkflowCompletedStatus = "task completed"
const PgtaskWorkflowCreateClusterType = "createcluster"
const PgtaskWorkflowID = "workflowid"
const PgtaskWorkflowSubmittedStatus = "task submitted"
const PgtaskpgDump = "pgdump"
const PgtaskpgDumpBackup = "pgdumpbackup"
const PgtaskpgDumpInfo = "pgdumpinfo"
const PgtaskpgRestore = "pgrestore"
const PrimarySecretSuffix = "-primaryuser-secret"
PrimarySecretSuffix ...
const RootSecretSuffix = "-postgres-secret"
RootSecretSuffix ...
const StorageCreate = "create"
StorageCreate ...
const StorageDynamic = "dynamic"
StorageDynamic ...
const StorageEmptydir = "emptydir"
StorageEmptydir ...
const StorageExisting = "existing"
StorageExisting ...
const SubmittedStatus = "submitted"
SubmittedStatus -
const UserSecretSuffix = "-secret"
UserSecretSuffix ...
Variables ¶
var ( // SchemeBuilder ... SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes) // AddToScheme ... AddToScheme = SchemeBuilder.AddToScheme )
var BackrestStorageTypes = []string{"local", "s3"}
BackrestStorageTypes defines the valid types of storage that can be utilized with pgBackRest
var PGFSGroup int64 = 26
PGFSGroup stores the UID of the PostgreSQL user that runs the PostgreSQL process, which is 26. This also sets up for future work, as the PodSecurityContext structure takes a *int64 for its FSGroup
This has to be a "var" as Kubernetes requires for this to be a pointer
var PGUserSystemAccounts = map[string]struct{}{ PGUserAdmin: struct{}{}, PGUserMonitor: struct{}{}, PGUserPgBouncer: struct{}{}, PGUserReplication: struct{}{}, PGUserSuperuser: struct{}{}, }
PGUserSystemAccounts maintains an easy-to-access list of what the systems accounts are, which may affect how information is returned, etc.
var SchemeGroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1"}
SchemeGroupVersion is the group version used to register these objects.
Functions ¶
func Resource ¶
func Resource(resource string) schema.GroupResource
Resource takes an unqualified resource and returns a Group-qualified GroupResource.
Types ¶
type PgContainerResources ¶
type PgContainerResources struct { RequestsMemory string `json:"requestsmemory"` RequestsCPU string `json:"requestscpu"` LimitsMemory string `json:"limitsmemory"` LimitsCPU string `json:"limitscpu"` }
PgContainerResource ... swagger:ignore
type PgStorageSpec ¶
type PgStorageSpec struct { Name string `json:"name"` StorageClass string `json:"storageclass"` AccessMode string `json:"accessmode"` Size string `json:"size"` StorageType string `json:"storagetype"` Fsgroup string `json:"fsgroup"` SupplementalGroups string `json:"supplementalgroups"` MatchLabels string `json:"matchLabels"` }
PgStorageSpec ... swagger:ignore
func (PgStorageSpec) GetSupplementalGroups ¶
func (s PgStorageSpec) GetSupplementalGroups() []int64
GetSupplementalGroups converts the comma-separated list of SupplementalGroups into a slice of int64 IDs. If it errors, it returns an empty slice and logs a warning
type Pgcluster ¶
type Pgcluster struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata"` Spec PgclusterSpec `json:"spec"` Status PgclusterStatus `json:"status,omitempty"` }
Pgcluster is the CRD that defines a Crunchy PG Cluster
swagger:ignore Pgcluster +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
func (*Pgcluster) DeepCopyInto ¶
DeepCopyInto copies all properties of this object into another object of the same type that is provided as a pointer.
func (*Pgcluster) DeepCopyObject ¶
DeepCopyObject returns a generically typed copy of an object
type PgclusterList ¶
type PgclusterList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata"` Items []Pgcluster `json:"items"` }
PgclusterList is the CRD that defines a Crunchy PG Cluster List swagger:ignore +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
func (*PgclusterList) DeepCopyObject ¶
func (in *PgclusterList) DeepCopyObject() runtime.Object
DeepCopyObject returns a generically typed copy of an object
type PgclusterSpec ¶
type PgclusterSpec struct { Namespace string `json:"namespace"` Name string `json:"name"` ClusterName string `json:"clustername"` Policies string `json:"policies"` CCPImage string `json:"ccpimage"` CCPImageTag string `json:"ccpimagetag"` Port string `json:"port"` PGBadgerPort string `json:"pgbadgerport"` ExporterPort string `json:"exporterport"` NodeName string `json:"nodename"` PrimaryStorage PgStorageSpec `json:primarystorage` ArchiveStorage PgStorageSpec `json:archivestorage` ReplicaStorage PgStorageSpec `json:replicastorage` BackrestStorage PgStorageSpec `json:backreststorage` ContainerResources PgContainerResources `json:containerresources` PrimaryHost string `json:"primaryhost"` User string `json:"user"` Database string `json:"database"` Replicas string `json:"replicas"` SecretFrom string `json:"secretfrom"` UserSecretName string `json:"usersecretname"` RootSecretName string `json:"rootsecretname"` PrimarySecretName string `json:"primarysecretname"` CollectSecretName string `json:"collectSecretName"` Status string `json:"status"` PswLastUpdate string `json:"pswlastupdate"` CustomConfig string `json:"customconfig"` UserLabels map[string]string `json:"userlabels"` PodAntiAffinity PodAntiAffinitySpec `json:"podPodAntiAffinity"` SyncReplication *bool `json:"syncReplication"` BackrestS3Bucket string `json:"backrestS3Bucket"` BackrestS3Region string `json:"backrestS3Region"` BackrestS3Endpoint string `json:"backrestS3Endpoint"` BackrestRepoPath string `json:"backrestRepoPath"` TablespaceMounts map[string]PgStorageSpec `json:"tablespaceMounts"` TLS TLSSpec `json:"tls"` TLSOnly bool `json:"tlsOnly"` Standby bool `json:"standby"` Shutdown bool `json:"shutdown"` }
PgclusterSpec is the CRD that defines a Crunchy PG Cluster Spec swagger:ignore
type PgclusterState ¶
type PgclusterState string
PgclusterState is the crd that defines PG Cluster Stage swagger:ignore
type PgclusterStatus ¶
type PgclusterStatus struct { State PgclusterState `json:"state,omitempty"` Message string `json:"message,omitempty"` }
PgclusterStatus is the CRD that defines PG Cluster Status swagger:ignore
type Pgpolicy ¶
type Pgpolicy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata"` Spec PgpolicySpec `json:"spec"` Status PgpolicyStatus `json:"status,omitempty"` }
Pgpolicy ... swagger:ignore +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
func (*Pgpolicy) DeepCopyInto ¶
DeepCopyInto copies all properties of this object into another object of the same type that is provided as a pointer.
func (*Pgpolicy) DeepCopyObject ¶
DeepCopyObject returns a generically typed copy of an object
type PgpolicyList ¶
type PgpolicyList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata"` Items []Pgpolicy `json:"items"` }
PgpolicyList ... swagger:ignore +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
func (*PgpolicyList) DeepCopyObject ¶
func (in *PgpolicyList) DeepCopyObject() runtime.Object
DeepCopyObject returns a generically typed copy of an object
type PgpolicySpec ¶
type PgpolicySpec struct { Namespace string `json:"namespace"` Name string `json:"name"` URL string `json:"url"` SQL string `json:"sql"` Status string `json:"status"` }
PgpolicySpec ... swagger:ignore
type PgpolicyState ¶
type PgpolicyState string
PgpolicyState ... swagger:ignore
const ( // PgpolicyStateCreated ... PgpolicyStateCreated PgpolicyState = "pgpolicy Created" // PgpolicyStateProcessed ... PgpolicyStateProcessed PgpolicyState = "pgpolicy Processed" )
type PgpolicyStatus ¶
type PgpolicyStatus struct { State PgpolicyState `json:"state,omitempty"` Message string `json:"message,omitempty"` }
PgpolicyStatus ... swagger:ignore
type Pgreplica ¶
type Pgreplica struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata"` Spec PgreplicaSpec `json:"spec"` Status PgreplicaStatus `json:"status,omitempty"` }
Pgreplica .. swagger:ignore +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
func (*Pgreplica) DeepCopyInto ¶
DeepCopyInto copies all properties of this object into another object of the same type that is provided as a pointer.
func (*Pgreplica) DeepCopyObject ¶
DeepCopyObject returns a generically typed copy of an object
type PgreplicaList ¶
type PgreplicaList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata"` Items []Pgreplica `json:"items"` }
PgreplicaList ... swagger:ignore +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
func (*PgreplicaList) DeepCopyObject ¶
func (in *PgreplicaList) DeepCopyObject() runtime.Object
DeepCopyObject returns a generically typed copy of an object
type PgreplicaSpec ¶
type PgreplicaSpec struct { Namespace string `json:"namespace"` Name string `json:"name"` ClusterName string `json:"clustername"` ReplicaStorage PgStorageSpec `json:"replicastorage"` ContainerResources PgContainerResources `json:"containerresources"` Status string `json:"status"` UserLabels map[string]string `json:"userlabels"` }
PgreplicaSpec ... swagger:ignore
type PgreplicaState ¶
type PgreplicaState string
PgreplicaState ... swagger:ignore
const ( // PgreplicaStateCreated ... PgreplicaStateCreated PgreplicaState = "pgreplica Created" // PgreplicaStatePending ... PgreplicaStatePendingInit PgreplicaState = "pgreplica Pending init" // PgreplicaStatePendingRestore ... PgreplicaStatePendingRestore PgreplicaState = "pgreplica Pending restore" // PgreplicaStateProcessed ... PgreplicaStateProcessed PgreplicaState = "pgreplica Processed" )
type PgreplicaStatus ¶
type PgreplicaStatus struct { State PgreplicaState `json:"state,omitempty"` Message string `json:"message,omitempty"` }
PgreplicaStatus ... swagger:ignore
type Pgtask ¶
type Pgtask struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata"` Spec PgtaskSpec `json:"spec"` Status PgtaskStatus `json:"status,omitempty"` }
Pgtask ... swagger:ignore +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
func (*Pgtask) DeepCopyInto ¶
DeepCopyInto copies all properties of this object into another object of the same type that is provided as a pointer.
func (*Pgtask) DeepCopyObject ¶
DeepCopyObject returns a generically typed copy of an object
type PgtaskList ¶
type PgtaskList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata"` Items []Pgtask `json:"items"` }
PgtaskList ... swagger:ignore +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
func (*PgtaskList) DeepCopyObject ¶
func (in *PgtaskList) DeepCopyObject() runtime.Object
DeepCopyObject returns a generically typed copy of an object
type PgtaskSpec ¶
type PgtaskSpec struct { Namespace string `json:"namespace"` Name string `json:"name"` StorageSpec PgStorageSpec `json:"storagespec"` TaskType string `json:"tasktype"` Status string `json:"status"` Parameters map[string]string `json:"parameters"` }
PgtaskSpec ... swagger:ignore
type PgtaskState ¶
type PgtaskState string
PgtaskState ... swagger:ignore
const ( // PgtaskStateCreated ... PgtaskStateCreated PgtaskState = "pgtask Created" // PgtaskStateProcessed ... PgtaskStateProcessed PgtaskState = "pgtask Processed" )
type PgtaskStatus ¶
type PgtaskStatus struct { State PgtaskState `json:"state,omitempty"` Message string `json:"message,omitempty"` }
PgtaskStatus ... swagger:ignore
type PodAntiAffinityDeployment ¶
type PodAntiAffinityDeployment int
PodAntiAffinityDeployment distinguishes between the different types of Deployments that can leverage PodAntiAffinity
const ( PodAntiAffinityDeploymentDefault PodAntiAffinityDeployment = iota PodAntiAffinityDeploymentPgBackRest PodAntiAffinityDeploymentPgBouncer )
The list of different types of PodAntiAffinityDeployments
type PodAntiAffinitySpec ¶
type PodAntiAffinitySpec struct { Default PodAntiAffinityType `json:"default"` PgBackRest PodAntiAffinityType `json:"pgBackRest"` PgBouncer PodAntiAffinityType `json:"pgBouncer"` }
PodAntiAffinitySpec provides multiple configurations for how pod anti-affinity can be set.
- "Default" is the default rule that applies to all Pods that are a part of the PostgreSQL cluster
- "PgBackrest" applies just to the pgBackRest repository Pods in said Deployment
- "PgBouncer" applies to just pgBouncer Pods in said Deployment
swaggier:ignore
type PodAntiAffinityType ¶
type PodAntiAffinityType string
PodAntiAffinityType defines the different types of type of anti-affinity rules applied to pg clusters when utilizing the default pod anti-affinity rules provided by the PostgreSQL Operator, which are enabled for a new pg cluster by default. Valid Values include "required" for requiredDuringSchedulingIgnoredDuringExecution anti-affinity, "preferred" for preferredDuringSchedulingIgnoredDuringExecution anti-affinity, and "disabled" to disable the default pod anti-affinity rules for the pg cluster all together.
func (PodAntiAffinityType) Validate ¶
func (p PodAntiAffinityType) Validate() error
ValidatePodAntiAffinityType is responsible for validating whether or not the type of pod anti-affinity specified is valid
type TLSSpec ¶
type TLSSpec struct { // CASecret contains the name of the secret to use as the trusted CA for the // TLSSecret // This is our own format and should contain at least one key: "ca.crt" // It can also contain a key "ca.crl" which is the certificate revocation list CASecret string `json:"caSecret"` // TLSSecret contains the name of the secret to use that contains the TLS // keypair for the PostgreSQL server // This follows the Kubernetes secret format ("kubernetes.io/tls") which has // two keys: tls.crt and tls.key TLSSecret string `json:"tlsSecret"` }
TLSSpec contains the information to set up a TLS-enabled PostgreSQL cluster
func (TLSSpec) IsTLSEnabled ¶
IsTLSEnabled returns true if the cluster is TLS enabled, i.e. both the TLS secret name and the CA secret name are available