Set up services for consumption by developers

This how-to guide walks service operators and application operators through setting up services for consumption by application developers. For the sake of example, you’ll set up the RabbitMQ Cluster Kubernetes operator. You will learn about the tanzu services CLI plug-in and the most important APIs for working with services on Tanzu Application Platform.

What you will do

Set up a service.
Create a service instance.
Claim a service instance.

This enables the application developer to bind an application workload to the service instance, as described in Consume services on Tanzu Application Platform.

Before you begin, for important background, see About consuming services on Tanzu Application Platform.

Overview

The following diagram depicts a summary of what this walkthrough covers, including binding an application workload to the service instance by the application developer.

Diagram shows the default namespace and service instances namespace. The default namespace has two application workloads, each connected to a service binding. The service bindings connect to the service instance in the service instances namespace through a resource claim.

Bear the following observations in mind as you work through this guide:

There is a clear separation of concerns across the various user roles.
- The life cycle of workloads is determined by application developers.
- The life cycle of resource claims is determined by application operators.
- The life cycle of service instances is determined by service operators.
- The life cycle of service bindings is implicitly tied to the life cycle of workloads.
Resource claims and resource claim policies are the mechanism to enable cross-namespace binding.
ProvisionedService is the contract allowing credentials and connectivity information to flow from the service instance, to the resource claim, to the service binding, and ultimately to the application workload. For more information, see ProvisionedService on GitHub.
Exclusivity of resource claims: Resource claims are considered to be mutually exclusive, meaning that service instances can be claimed by at most one resource claim.

Prerequisites

Before following this walkthrough, you must:

Have access to a cluster with Tanzu Application Platform installed.
Have downloaded and installed the Tanzu CLI and the corresponding plug-ins.
Ensure that your Tanzu Application Platform cluster can pull the container images required by the Kubernetes operator providing the service. For more information, see:

Set up a service

This section covers the following:

Installing the selected service Kubernetes operator.
Creating the role-based access control (RBAC) rules to grant Tanzu Application Platform permission to interact with the APIs provided by the newly installed Kubernetes operator.
Creating the additional supporting resources to aid with discovery of services.

For this part of the walkthrough, you assume the role of the service operator.

Note: Although this walkthrough uses the example of RabbitMQ Cluster Kubernetes operator, the setup steps remain largely the same for any compatible operator. Also, this walkthrough uses the open source RabbitMQ Cluster operator for Kubernetes. For most real-world deployments, VMware recommends using the official, supported version provided by VMware. For more information, see VMware Tanzu RabbitMQ for Kubernetes.

To set up a service:

Use kapp to install the open source RabbitMQ Cluster Kubernetes operator by running:
```
kapp -y deploy --app rmq-operator --file https://github.com/rabbitmq/cluster-operator/releases/latest/download/cluster-operator.yml
```
As a result, a new API Group (rabbitmq.com) and Kind (RabbitmqCluster) are now available in the cluster.

Apply RBAC rules to grant Tanzu Application Platform permission to interact with the new API.

In a file named resource-claims-rmq.yaml, create a ClusterRole that defines the rules and label it so that the rules are aggregated to the appropriate controller:

# resource-claims-rmq.yaml
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: resource-claims-rmq
  labels:
    servicebinding.io/controller: "true"
rules:
- apiGroups: ["rabbitmq.com"]
  resources: ["rabbitmqclusters"]
  verbs: ["get", "list", "watch"]

Apply resource-claims-rmq.yaml by running:

kubectl apply -f resource-claims-rmq.yaml

Make the new API discoverable to application operators.
1. In a file named rabbitmqcluster-clusterinstanceclass.yaml, create a ClusterInstanceClass that refers to the new service, and set any additional metadata. For example:
```
# rabbitmqcluster-clusterinstanceclass.yaml
---
apiVersion: services.apps.tanzu.vmware.com/v1alpha1
kind: ClusterInstanceClass
metadata:
  name: rabbitmq
spec:
  description:
    short: It's a RabbitMQ cluster!
  pool:
    group: rabbitmq.com
    kind: RabbitmqCluster
```
2. Apply rabbitmqcluster-clusterinstanceclass.yaml by running:
```
kubectl apply -f rabbitmqcluster-clusterinstanceclass.yaml
```
  After applying this resource, it is listed in the output of the tanzu service classes list command, and is discoverable in the tanzu tooling.

Create a service instance

This section covers the following:

Using kubectl to create a RabbitmqCluster service instance.
Creating a resource claim policy that permits the service instance to be claimed.

For this part of the walkthrough, you assume the role of the service operator.

To create a service instance:

Create a dedicated namespace for service instances by running:
```
kubectl create namespace service-instances
```
Note: Using namespaces to separate service instances from application workloads allows for greater separation of concerns, and means that you can achieve greater control over who has access to what. However, this is not a strict requirement. You can create both service instances and application workloads in the same namespace.

Create a RabbitmqCluster service instance.

Create a file named rmq-1-service-instance.yaml:

# rmq-1-service-instance.yaml
---
apiVersion: rabbitmq.com/v1beta1
kind: RabbitmqCluster
metadata:
  name: rmq-1
  namespace: service-instances

Apply rmq-1-service-instance.yaml by running:

kubectl apply -f rmq-1-service-instance.yaml

Create a resource claim policy to define the namespaces the instance can be claimed and bound from.

Note: By default, you can only claim and bind to service instances that are running in the same namespace as the application workloads. To claim service instances running in a different namespace, you must create a resource claim policy.
1. Create a file named rmq-claim-policy.yaml as follows:
```
# rmq-claim-policy.yaml
---
apiVersion: services.apps.tanzu.vmware.com/v1alpha1
kind: ResourceClaimPolicy
metadata:
  name: rabbitmqcluster-cross-namespace
  namespace: service-instances
spec:
  consumingNamespaces:
  - '*'
  subject:
    group: rabbitmq.com
    kind: RabbitmqCluster
```
2. Apply rmq-claim-policy.yaml by running:
```
kubectl apply -f rmq-claim-policy.yaml
```
This policy states that any resource of kind RabbitmqCluster on the rabbitmq.com API group in the service-instances namespace can be consumed from any namespace.

Claim a service instance

This section covers the following:

Using tanzu service claimable list --class to view details about service instances claimable from a namespace.
Using tanzu service claim create to create a claim for the service instance.

For this part of the walkthrough, you assume the role of the application operator.

Resource claims in Tanzu Application Platform are a powerful concept that serve many purposes. Arguably their most important role is to enable application operators to request services that they can use with their application workloads without having to create and manage the services themselves. For more information, see Resource Claims.

In cases where service instances are running in the same namespace as application workloads, you do not have to create a claim. You can bind to the service instance directly.

In this section you use the tanzu service claim create command to create a claim that the RabbitmqCluster service instance you created earlier can fulfill. This command requires the following information to create a claim successfully:

--resource-name
--resource-kind
--resource-api-version
--resource-namespace

To claim a service instance:

Find the claimable instance and the necessary claim information by running:

tanzu service claimable list --class rabbitmq

Expected output:

  tanzu service claimable list --class rabbitmq

  NAME    NAMESPACE            API KIND         API GROUP/VERSION
  rmq-1   service-instances    RabbitmqCluster  rabbitmq.com/v1beta1

Using the information from the previous command, create a claim for the service instance by running:

tanzu service claim create rmq-1 \
  --resource-name rmq-1 \
  --resource-namespace service-instances \
  --resource-kind RabbitmqCluster \
  --resource-api-version rabbitmq.com/v1beta1

You have successfully set the scene for the application developer to inspect the claim and to use it to bind to application workloads, as described in Consume services on Tanzu Application Platform.

Further use cases and reading

There are more service use cases not covered in this getting started guide. See the following:

Use Case	Short Description
Consuming AWS RDS on Tanzu Application Platform	Using the Controllers for Kubernetes (ACK) to provision an RDS instance and consume it from a Tanzu Application Platform workload. Involves making a third-party API consumable from Tanzu Application Platform.
Consuming AWS RDS on Tanzu Application Platform with Crossplane	Using Crossplane to provision an RDS instance and consume it from a Tanzu Application Platform workload. Involves making a third-party API consumable from Tanzu Application Platform.
Consuming Google Cloud SQL on Tanzu Application Platform with Config Connector	Using GCP Config Connector to provision a Cloud SQL instance and consume it from a Tanzu Application Platform workload. Involves making a third-party API consumable from Tanzu Application Platform.
Consuming Google Cloud SQL on Tanzu Application Platform with Crossplane	Using Crossplane to provision a Cloud SQL instance and consume it from a Tanzu Application Platform workload. Involves making a third-party API consumable from Tanzu Application Platform.
Direct Secret References	Binding to services running external to the cluster, for example, an in-house oracle database. Binding to services that do not conform with the binding specification.
Dedicated Service Clusters (Experimental)	Separates application workloads from service instances across dedicated clusters.

For more information about the APIs and concepts underpinning Services on Tanzu Application Platform, see the Services Toolkit Component documentation.

Next steps

Now that you’ve completed the Getting started guides, learn about:

Multicluster Tanzu Application Platform