Work with Bitnami Services

In this tutorial you learn how application operators can discover, claim, and bind services to application workloads.

Tanzu Application Platform has six services that are available in the Bitnami Services package. These are MySQL, PostgreSQL, RabbitMQ, Redis, MongoDB, and Kafka. The corresponding Bitnami Helm chart backs each of these services.

About this tutorial

Target user role: Application operator
Complexity: Basic
Estimated time: 15 minutes
Topics covered: Classes, claims, Bitnami
Learning outcomes: An understanding of how to work with the standard services provided by the Bitnami Services package

Prerequisites

To follow this tutorial, you must have:

Access to a Tanzu Application Platform cluster v1.5.0 or later.
Installed the Tanzu services CLI plug-in v0.6.0 or later.

Concepts

The following diagram provides an overview of the elements you will use during this tutorial and how these elements fit together.

Diagram shows a high-level overview of the Bitnami Services that are available in the Bitnami services package.

In this diagram:

There are two elements that require user input. These are creating a ClassClaim and creating a Workload. The workload is configured to refer to the class claim.
The life cycles of the ClassClaim and the Workload are separate. This allows you to update one without affecting the other.
The dynamic provisioning process is simplified. This is intentional because application operators and developers do not need to know about the inner workings and configuration of service instances.

Procedure

The following steps explain how to work with Bitnami Services.

Step 1: Discover the services

Application teams can discover the range of available services by running:
```
tanzu service class list
```
Example output:
```
  NAME                  DESCRIPTION
  kafka-unmanaged       Kafka by Bitnami
  mongodb-unmanaged     MongoDB by Bitnami
  mysql-unmanaged       MySQL by Bitnami
  postgresql-unmanaged  PostgreSQL by Bitnami
  rabbitmq-unmanaged    RabbitMQ by Bitnami
  redis-unmanaged       Redis by Bitnami
```
This output shows six classes. These are the six services available in the Bitnami Services package. You can see from the names and descriptions that they are all unmanaged services. This implies that the resulting service instances run on cluster, that is, they are not a managed service running in the cloud. Other classes might be listed here as well.

As an application operator, you review the classes on offer and choose one that meets your requirements.
You can learn more about a class by running:
```
tanzu service class get postgresql-unmanaged
```
Example output:
```
NAME:           postgresql-unmanaged
DESCRIPTION:    PostgreSQL by Bitnami
READY:          true

PARAMETERS:
  KEY        DESCRIPTION                                                  TYPE     DEFAULT  REQUIRED
  storageGB  The desired storage capacity of the database, in Gigabytes.  integer  1        false
```
The output shows the name, a short description for the class, its current status, and the parameters. The parameters represent the set of configuration options that are available to application teams.

The postgresql-unmanaged class here has one parameter, which is storageGB. You can also see that it is not required to pass this parameter when creating a claim for the class, in which case the default value of 1 is used.

Step 2: Claim a service

In this example you have an application workload that requires a PostgreSQL database to function correctly. You can claim the PostgreSQL Bitnami service to obtain such a database.

To claim a PostgreSQL service:

Create the namespace dev-team-1 by running:
```
kubectl create namespace dev-team-1
```

Create a claim for the postgresql-unmanaged class.

The following command also overrides the default value of 1 for the storageGB parameter by setting it to 3. You can override any of the options.

tanzu service class-claim create psql-1 \
  --class postgresql-unmanaged \
  --parameter storageGB=3 \
  -n dev-team-1

Example output:

Creating claim 'psql-1' in namespace 'dev-team-1'.
Please run `tanzu service class-claim get psql-1 --namespace dev-team-1` to see the progress of create.

Confirm the status of the claim by running:

tanzu service class-claim get psql-1 --namespace dev-team-1

Example output:

Name: psql-1
Namespace: dev-team-1
Claim Reference: services.apps.tanzu.vmware.com/v1alpha1:ClassClaim:psql-1
Class Reference:
  Name: postgresql-unmanaged
Parameters:
  storageGB: 3
Status:
  Ready: True
  Claimed Resource:
    Name: 7974379c-7b4d-41c3-af57-f4f1ae08c65d
    Namespace: dev-team-1
    Group:
    Version: v1
    Kind: Secret

Wait for the claim to report Ready: True.

After the claim is ready, you then have a successful claim for a PostgreSQL database configured to your needs with 3 GB of storage.

Step 3: Bind the claim to a workload

After creating the service claim, you can bind it to one or more of your application workloads.

Important
If you are binding to more than one application workload, all application workloads must exist in the same namespace. This is a known limitation. For more information, see Cannot claim and bind to the same service instance from across multiple namespaces.

To bind the claim to your workload:

Find the reference for the claim by running:
```
tanzu service class-claim get psql-1
```
The reference is in the output under the heading Claim Reference.
Bind the claim to your workload by passing the reference for the claim to the --service-ref flag of the tanzu apps workload create command. For example:
```
tanzu apps workload create my-workload \
  --image my-registry/my-app-image \
  --service-ref db=services.apps.tanzu.vmware.com/v1alpha1:ClassClaim:psql-1
```
You must pass the claim reference with a corresponding name that follows the format --service-ref db=services.apps.tanzu.vmware.com/v1alpha1:ClassClaim:psql-1. The db= prefix to this example reference is an arbitrary name for the reference.