Getting Started with Data Services Manager 2.0 – Part 7: DSM (Gateway) 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
% 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.
2 Replies to “Getting Started with Data Services Manager 2.0 – Part 7: DSM (Gateway) API”
Comments are closed.