Site icon CormacHogan.com

Getting Started with Data Services Manager 2.0 – Part 7: DSM API

One of the guiding goals for Data Services Manager (DSM) 2.0 is to provide a very rich Kubernetes compliant API server for end-users and developers. We refer to this as the Gateway API. In this post, I will demonstrate the Gateway API server’s capabilities and show how it can be used to query the state of the objects that are provisioned through DSM, and also how to modify and manipulate these objects. The kubectl command line interface is used. We will use this tool to query and modify some of the infrastructure components, as well as query the existing data services and databases. We will also use it to restore a database from a backup. The really nice aspect of using a Kubernetes compatible API server  for DSM is that it lends itself to seamless integration with many other systems for automation, e.g. Terraform.

Note: At the time of writing, DSM version 2.0 is not yet generally available. Therefore some of the screenshots captured in the upcoming post, as well as some of the outputs displayed, may differ slightly in the final product. However, for the purposes of our getting started series of posts, this should not matter too much.

Retrieve the Gateway API kubeconfigs

Before we begin, the assumption is that you already have the kubectl command line tool installed on your host or workstation. The next step is to download the kubeconfig for accessing the DSM API. A kubeconfig file is a file that is used to configure access to a Kubernetes cluster. It can be retrieved from various places when DSM is deployed onto vSphere infrastructure. The first is from the vCenter Server > Configure > Data Services Manager > Infrastructure Policies view. This would provide permissions to the API Server as an Infrastructure Admin. This persona can make changes to infrastructure components but not to the database services directly.

A kubeconfig may also be retrieved from the DSM appliance from the User drop-down menu. This would provide permissions as a DSM Admin or User (depending on the role of the user who is logged in), which means that operations could be carried out on the data services, but not on the infrastructure.

The DSM (Gateway) API – Infrastructure

Let’s begin as an Infrastructure Admin. With the kubeconfig (kubeconfig-gateway.yaml) downloaded from the vSphere client, and the kubectl command line interface installed, it should now be possible to see which DSM API objects can be queried and perhaps modified by running the following command:

% kubectl api-resources --kubeconfig kubeconfig-gateway.yaml
NAME                        SHORTNAMES  APIVERSION                                        NAMESPACED  KIND
namespaces                  ns          v1                                                false       Namespace
secrets                                 v1                                                true        Secret
customresourcedefinitions   crd,crds    apiextensions.k8s.io/v1                           false       CustomResourceDefinition
apiservices                             apiregistration.k8s.io/v1                         false       APIService
databaseconfigs                         databases.dataservices.vmware.com/v1alpha1        true        DatabaseConfig
mysqlclusters                           databases.dataservices.vmware.com/v1alpha1        true        MySQLCluster
postgresclusters                        databases.dataservices.vmware.com/v1alpha1        true        PostgresCluster
infrastructurepolicies                  infrastructure.dataservices.vmware.com/v1alpha1   false       InfrastructurePolicy
ippools                                 infrastructure.dataservices.vmware.com/v1alpha1   false       IPPool
vmclasses                               infrastructure.dataservices.vmware.com/v1alpha1   false       VMClass
dataservicesreleases                    internal.dataservices.vmware.com/v1alpha1         false       DataServicesRelease
systempolicies                          system.dataservices.vmware.com/v1alpha1           false       SystemPolicy

As you can probably see, a number of these API objects relate directly to the infrastructure. In our opening blog post on DSM 2.0, Infrastructure Policies as well as IP pools and VM Classes were discussed in detail. Let’s query these objects using the DSM API now.

% kubectl get infrastructurepolicies --kubeconfig kubeconfig-gateway.yaml
NAME              AGE
infra-policy-01  21h

% kubectl get infrastructurepolicies infra-policy-01 --kubeconfig kubeconfig-gateway.yaml -o yaml
apiVersion: infrastructure.dataservices.vmware.com/v1alpha1
kind: InfrastructurePolicy
metadata:
  creationTimestamp: "2024-01-16T14:19:25Z"
  finalizers:
  - infrastructurepolicy.infrastructure.dataservices.vmware.com/finalizer
  generation: 1
  name: infra-policy-01
  resourceVersion: "51"
  uid: ebcb5583-609a-483e-9f2a-98d59920261c
spec:
  enabled: true
  ipRanges:
  - poolName: ip-pool-0
    portGroups:
    - datacenter: /OCTO-Datacenter
      name: VM-51-DPG-B
    - datacenter: /OCTO-Datacenter
      name: VM-51-DPG
  placements:
  - cluster: Cluster-B
    datacenter: /OCTO-Datacenter
    folder: DB
    portGroups:
    - VM-51-DPG-B
  - cluster: Cluster-A
    datacenter: /OCTO-Datacenter
    folder: DB
    portGroups:
    - VM-51-DPG
  storagePolicies:
  - vSAN Default Storage Policy
  vmClasses:
  - name: medium
status:
  conditions:
  - lastTransitionTime: "2024-01-16T14:19:26Z"
    message: Infrastructure Policy is ready
    observedGeneration: 1
    reason: Ready
    status: "True"
    type: Ready

Note that the second command uses the ‘-o yaml’ option to display detailed information about the object in YAML format. Looking closely at the output, you can see various infrastructure components described, such as the vSphere Clusters, the distributed portgroups, storage policies, etc. Also of interest are some of the objects used by DSM to create data services, such as the IP Pool and VM class. Let’s look at the IP Pool in further detail using the DSM API.

% kubectl get ippools --kubeconfig kubeconfig-gateway.yaml
NAME        AGE
ip-pool-0  21h


% kubectl get ippools ip-pool-0 --kubeconfig kubeconfig-gateway.yaml -o yaml
apiVersion: infrastructure.dataservices.vmware.com/v1alpha1
kind: IPPool
metadata:
  creationTimestamp: "2024-01-16T14:18:40Z"
  finalizers:
  - ippool.infrastructure.dataservices.vmware.com/finalizer
  generation: 2
  name: ip-pool-0
  resourceVersion: "2863"
  uid: efdb9e94-0525-42c0-ba0e-0274df2fb8a4
spec:
  addresses:
  - xx.xx.xx.175-xx.xx.xx.199
  - xx.xx.xx.165-xx.xx.xx.174
  gateway: xx.xx.xx.254
  prefix: 24
status:
  conditions:
  - lastTransitionTime: "2024-01-17T11:29:23Z"
    message: IP pool is ready
    observedGeneration: 2
    reason: Ready
    status: "True"
    type: Ready
  - lastTransitionTime: "2024-01-16T14:18:41Z"
    message: ""
    observedGeneration: 2
    reason: Reconciled
    status: "True"
    type: Provisioning
  ipAddresses:
    free: 16
    outOfRange: 0
    total: 35
    used: 19

Not only does this allow us to query the ranges of IP address in the IP Pool (which I have obfuscated for security reasons), but it also allows us to check how many IP address are in use and how many IP addresses are still available without having to check on the UI. The API can also be used to create new API objects, such as a new IP Pool, as shown here:

% cat my-ippool.yaml
apiVersion: infrastructure.dataservices.vmware.com/v1alpha1
kind: IPPool
metadata:
  name: ip-pool-1
spec:
  addresses:
  - 192.168.0.1-192.168.0.253
  gateway: 192.168.0.254
  prefix: 24


% kubectl create -f my-ippool.yaml --kubeconfig kubeconfig-gateway.yaml
ippool.infrastructure.dataservices.vmware.com/ip-pool-1 created


% kubectl get ippools --kubeconfig kubeconfig-gateway.yaml
NAME        AGE
ip-pool-0   21h
ip-pool-1   11s

Let’s check the vSphere Client to see if the new IP Pool is actually present.


Success! We have created a new IP Pool using the DSM API. As you can imagine, it is possible to do a lot more with the infrastructure configuration using the DSM API, but let’s now turn our attention to the data services and databases.

The DSM (Gateway) API – Data Services

Let’s now look at operations as a DSM Admin. I have already provisioned a number of databases in this deployment. I can query these databases as follows:

% kubectl get postgresclusters --kubeconfig kubeconfig-gateway.yaml
NAME             STATUS   STORAGE   VERSION                  AGE
pg-01            Ready    60Gi      15.5+vmware.v2.0.0-rc.8  20h
pg-01-65a6a26b   Ready    60Gi      15.5+vmware.v2.0.0-rc.8  20h


% kubectl get mysqlclusters --kubeconfig kubeconfig-gateway.yaml
NAME                  STATUS   STORAGE   VERSION                    AGE
mysql-01              Ready    60Gi      8.0.29+vmware.v2.0.0-rc.8  20h
mysql-01-65a6a0c4     Ready    60Gi      8.0.29+vmware.v2.0.0-rc.8  20h
rest-mysql-01-65a6a   Ready    60Gi      8.0.29+vmware.v2.0.0-rc.8  20h

There are two PostgreSQL database clusters and three MySQL database clusters. Let’s focus on the PostgreSQL database pg-01-65a6a26b for the purposes of this demonstration. First, let’s take a look at the configuration of this database cluster. I’ve removed the conditions section to simplify the output.

% kubectl get postgresclusters pg-01-65a6a26b --kubeconfig kubeconfig-gateway.yaml -o yaml
apiVersion: databases.dataservices.vmware.com/v1alpha1
kind: PostgresCluster
metadata:
  annotations:
    dsm.vmware.com/owner: chogan@vmware.com
  creationTimestamp: "2024-01-16T15:36:15Z"
  finalizers:
  - databases.dataservices.vmware.com/finalizer
  generation: 1
  labels:
    dsm.vmware.com/created-in: dsm
    dsm.vmware.com/infra-policy: infra-policy-01
    dsm.vmware.com/vm-class: medium
  name: pg-01-65a6a26b
  namespace: default
  resourceVersion: "1381"
  uid: e11687e7-d0b9-4778-85f4-160b84672535
spec:
  backupConfig:
    backupRetentionDays: 30
    schedules:
    - name: default-full-backup
      schedule: 59 23 * * 6
      type: full
    - name: default-incremental-backup
      schedule: 59 23 1/1 * *
      type: incremental
  backupLocation:
    name: dsm2-db-backup
  basedOn:
    cluster:
      name: pg-01
  infrastructurePolicy:
    name: infra-policy-01
  maintenanceWindow:
    duration: 6h0m0s
    startDay: SATURDAY
    startTime: "23:59"
  replicas: 0
  storagePolicyName: vSAN Default Storage Policy
  storageSpace: 60Gi
  version: 15.5+vmware.v2.0.0-rc.8
  vmClass:
    name: medium
status:
  alertLevel: OK
  backupId: default-pg-01-65a6a26b-708cd808-59c8-4d7c-91e1-73e6709d380d
  conditions:
.
.
.
  connection:
    dbname: pg-01
    host: xx.xx.xx.190
    passwordRef:
      name: pg-01-65a6a26b
    port: 5432
    username: pgadmin
  lastSuccessfulBackup: "2024-01-16T23:59:09Z"
  lastUpdate: "2024-01-16T15:36:15Z"
  nodes:
  - datacenter: /OCTO-Datacenter
    folder: DB
    network:
      devices:
      - ipPool: ip-pool-0
        networkName: VM-51-DPG
    resourcePool: Cluster-A/Resources
    server: xx.xx.xx.106
    storagePolicyName: vSAN Default Storage Policy
    vmMoid: vm-35279
    vmName: pg-01-65a6a26b-2b6xc

There is a lot of good information that can be gleaned from this output. We can see backup configuration, infrastructure policy, maintenance windows for updates, storage policy, version as well as the topology (0 replicas) implying that there is only a single node in the cluster. Detail about the node is shown at the end. There are also details about how to connect to the database. I have once again obfuscated the IP addresses. One other interesting field is the ‘basedOn‘. This tells us that this database was created/restored from database cluster pg-01.

Let’s now assume that we want to scale out the database cluster from 1 node to 3 nodes and provide some level of protection and availability to the data service. One can simply edit the manifest of the database in question and change the replica values from 0 to 1. Then reapply the YAML manifest to the DSM API server which includes this change. This will cause DSM to build 2 additional VMs for his database cluster. The Primary will use one node, the new replica will use another node and the Monitor component will be placed on its own third node. Note that this can only be done as a DSM Admin or owner of the database. It is not possible to do this as an Infra Admin since the SSO user configured for infrastructure administrator has no access to the database. Another way to achieve this is to patch the database directly using the kubectl edit command.

% kubectl edit postgresclusters pg-01-65a6a26b --kubeconfig kubeconfig-gateway.yaml
postgrescluster.databases.dataservices.vmware.com/pg-01-65a6a26b edited

And soon after making and saving the change, the topology of the database should show as changed in both the kubectl get command line output as well as in the UI.

Many other operations are also possible using the DSM API, ranging from database creation to day 2 operations such as  restoring from backup. In this final example, I will create a YAML manifest which defines a single node PostgreSQL cluster, and will proceed to create it using the API. The manifest specification includes fields which define owner, backup details, infrastructure policy, database name and user, as well as the version of PostgreSQL to deploy.

% cat pg-02.yaml
apiVersion: databases.dataservices.vmware.com/v1alpha1
kind: PostgresCluster
metadata:
  annotations:
    dsm.vmware.com/owner: provider@broadcom.com
  name: pg-02
  namespace: default
spec:
  adminUsername: pgadmin
  backupConfig:
    backupRetentionDays: 30
    schedules:
    - name: default-full-backup
      schedule: 59 23 * * 6
      type: full
    - name: default-incremental-backup
      schedule: 59 23 1/1 * *
      type: incremental
  backupLocation:
    name: dsm2-db-backup
  databaseName: pg-02
  infrastructurePolicy:
    name: infra-policy-01
  maintenanceWindow:
    duration: 6h0m0s
    startDay: SATURDAY
    startTime: "23:59"
  replicas: 0
  storagePolicyName: vSAN Default Storage Policy
  storageSpace: 60Gi
  version: 15.5+vmware.v2.0.0-rc.8
  vmClass:
    name: medium


% kubectl create -f pg-02.yaml --kubeconfig kubeconfig-gateway.yaml
postgrescluster.databases.dataservices.vmware.com/pg-02 created
After sending the request to the API server to create the database, we can also use the API server to monitor it. After a short while, the database should become ready.
% kubectl get postgresclusters --kubeconfig kubeconfig-gateway.yaml
NAME             STATUS       STORAGE   VERSION                  AGE
pg-01            Ready        60Gi      15.5+vmware.v2.0.0-rc.8  22h
pg-01-65a6a26b   Ready        60Gi      15.5+vmware.v2.0.0-rc.8  22h
pg-02            InProgress   60Gi      15.5+vmware.v2.0.0-rc.8  4m9s


% kubectl get postgresclusters --kubeconfig kubeconfig-gateway.yaml
NAME             STATUS   STORAGE   VERSION                  AGE
pg-01            Ready    60Gi      15.5+vmware.v2.0.0-rc.8  22h
pg-01-65a6a26b   Ready    60Gi      15.5+vmware.v2.0.0-rc.8  22h
pg-02            Ready    60Gi      15.5+vmware.v2.0.0-rc.8  8m29s

And finally we can verify that the database is also present in the DSM UI.

Success! The newly create database is present and correct. I hope that what you have read in this post has demonstrated the power of the DSM 2.0 API, and how through well-known developer mechanisms like YAML and kubectl, administrators can query and make changes to both the infrastructure components and data service/database components of DSM in an easy to understand manner. For those interested in evaluating this DSM capability in a bit more detail, I have created a bunch of YAML manifests for various infra and DSM operations and placed them up on github. Feel free to use these as a basis for building out your own manifests.

Exit mobile version