Service catalog command-line interface (CLI)

Service catalog command-line interface (CLI)

Overview

The basic workflow of interacting with the service catalog is that:

The cluster administrator installs and registers a broker server to make available its services.
The users use those services by instantiating them in an OpenShift project and linking those service instances to their pods.

The Service Catalog command-line interface (CLI) utility called svcat is available to handle these user related tasks. While oc commands can perform the same tasks, you can use svcat for easier interaction with Service Catalog resources. svcat communicates with the Service Catalog API by using the aggregated API endpoint on an OpenShift cluster.

Installing svcat

You can install svcat as an RPM by using Red Hat Subscription Management (RHSM) if you have an active OpenShift Enterprise subscription on your Red Hat account:

# yum install atomic-enterprise-service-catalog-svcat

Considerations for cloud providers

Google Compute Engine For Google Cloud Platform, run the following command to setup firewall rules to allow incoming traffic:

$ gcloud compute firewall-rules create allow-service-catalog-secure --allow tcp:30443 --description "Allow incoming traffic on 30443 port."

Using svcat

This section includes common commands to handle the user associated tasks listed in the service catalog workflow. Use the svcat --help command to get more information and view other available command-line options. The sample output in this section assumes that the Ansible Service Broker is already installed on the cluster.

Get broker details

You can view a list available brokers, sync the broker catalog, and get details about brokers deployed in the service catalog.

Find brokers

To view all the brokers installed on the cluster:

$ svcat get brokers
           NAME                                                        URL                                              STATUS
+-------------------------+-------------------------------------------------------------------------------------------+--------+
  ansible-service-broker    https://asb.openshift-ansible-service-broker.svc:1338/ansible-service-broker                Ready
  template-service-broker   https://apiserver.openshift-template-service-broker.svc:443/brokers/template.openshift.io   Ready

Sync broker catalog

To refresh the catalog metadata from the broker:

$ svcat sync broker ansible-service-broker
Synchronization requested for broker: ansible-service-broker

View broker details

To view the details of the broker:

$ svcat describe broker ansible-service-broker
  Name:     ansible-service-broker
  URL:      https://openshift-automation-service-broker.openshift-automation-service-broker.svc:1338/openshift-automation-service-broker/
  Status:   Ready - Successfully fetched catalog entries from broker @ 2018-06-07 00:32:59 +0000 UTC

View service classes and service plans

When you create a ClusterServiceBroker resource, the service catalog controller queries the broker server to find all services it offers and creates a service class (ClusterServiceClass) for each of those services. Additionally, it also creates service plans (ClusterServicePlan) for each of the broker’s services.

View service classes

To view the available ClusterServiceClass resources:

$ svcat get classes
        NAME                   DESCRIPTION
+-------------------+--------------------------------+
  rh-mediawiki-apb    Mediawiki apb implementation
  ...
  rh-mariadb-apb      Mariadb apb implementation
  rh-mysql-apb        Software Collections MySQL APB
  rh-postgresql-apb   SCL PostgreSQL apb
                      implementation

To view details of a service class:

$ svcat describe class rh-postgresql-apb
  Name:          rh-postgresql-apb
  Description:   SCL PostgreSQL apb implementation
  UUID:          d5915e05b253df421efe6e41fb6a66ba
  Status:        Active
  Tags:          database, postgresql
  Broker:        ansible-service-broker
Plans:
  NAME            DESCRIPTION
+------+--------------------------------+
  prod   A single DB server with
         persistent storage
  dev    A single DB server with no
         storage

View service plans

To view the ClusterServicePlan resources available in the cluster:

$ svcat get plans
   NAME           CLASS                  DESCRIPTION
+---------+-------------------+--------------------------------+
  default   rh-mediawiki-apb    An APB that deploys MediaWiki
  ...
  prod      rh-mariadb-apb      This plan deploys a single
                                MariaDB instance with 10 GiB
                                of persistent storage
  dev       rh-mariadb-apb      This plan deploys a single
                                MariaDB instance with
                                ephemeral storage
  prod      rh-mysql-apb        A MySQL server with persistent
                                storage
  dev       rh-mysql-apb        A MySQL server with ephemeral
                                storage
  prod      rh-postgresql-apb   A single DB server with
                                persistent storage
  dev       rh-postgresql-apb   A single DB server with no
                                storage

View details of a plan:

$ svcat describe plan rh-postgresql-apb/dev
  Name:          dev
  Description:   A single DB server with no storage
  UUID:          9783fc2e859f9179833a7dd003baa841
  Status:        Active
  Free:          true
  Class:         rh-postgresql-apb
Instances:
No instances defined
Instance Create Parameter Schema:
  $schema: http://json-schema.org/draft-04/schema
  additionalProperties: false
  properties:
    postgresql_database:
      default: admin
      pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
      title: PostgreSQL Database Name
      type: string
    postgresql_password:
      pattern: ^[a-zA-Z0-9_~!@#$%^&*()-=<>,.?;:|]+$
      title: PostgreSQL Password
      type: string
    postgresql_user:
      default: admin
      maxLength: 63
      pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
      title: PostgreSQL User
      type: string
    postgresql_version:
      default: "9.6"
      enum:
      - "9.6"
      - "9.5"
      - "9.4"
      title: PostgreSQL Version
      type: string
  required:
  - postgresql_database
  - postgresql_user
  - postgresql_password
  - postgresql_version
  type: object
Instance Update Parameter Schema:
  $schema: http://json-schema.org/draft-04/schema
  additionalProperties: false
  properties:
    postgresql_version:
      default: "9.6"
      enum:
      - "9.6"
      - "9.5"
      - "9.4"
      title: PostgreSQL Version
      type: string
  required:
  - postgresql_version
  type: object
Binding Create Parameter Schema:
  $schema: http://json-schema.org/draft-04/schema
  additionalProperties: false
  type: object

Provision services

Provisioning means to make the service available for consumption. To provision a service, you need to create a service instance and then bind to it.

Create ServiceInstance

Service instances must be created inside an OpenShift namespace.

Create a new project.
```
$ oc new-project <project-name> (1)
```
1 Replace <project-name> with the name of your project.

Create service instance using the command:

$ svcat provision postgresql-instance --class rh-postgresql-apb --plan dev --params-json  '{"postgresql_database":"admin","postgresql_password":"admin","postgresql_user":"admin","postgresql_version":"9.6"}' -n szh-project
  Name:        postgresql-instance
  Namespace:   szh-project
  Status:
  Class:       rh-postgresql-apb
  Plan:        dev
Parameters:
  postgresql_database: admin
  postgresql_password: admin
  postgresql_user: admin
  postgresql_version: "9.6"

View service instance details

To view service instance details:

$ svcat get instance
         NAME            NAMESPACE          CLASS         PLAN   STATUS
+---------------------+-------------+-------------------+------+--------+
  postgresql-instance   szh-project   rh-postgresql-apb   dev    Ready

Create ServiceBinding

When you create a ServiceBinding resource:

The service catalog controller communicates with the broker server to initiate the binding.
The broker server create credentials and issue them to the service catalog controller.
The service catalog controller adds those credentials as secrets to the project.

Create the service binding using the command:

$ svcat bind postgresql-instance --name mediawiki-postgresql-binding
  Name:        mediawiki-postgresql-binding
  Namespace:   szh-project
  Status:
  Instance:    postgresql-instance
Parameters:
  {}

View service binding details

To view service binding details:

$ svcat get bindings
              NAME                NAMESPACE         INSTANCE         STATUS
+------------------------------+-------------+---------------------+--------+
  mediawiki-postgresql-binding   szh-project   postgresql-instance   Ready

Verify the instance details after binding the service:

$ svcat describe instance postgresql-instance
  Name:        postgresql-instance
  Namespace:   szh-project
  Status:      Ready - The instance was provisioned successfully @ 2018-06-05 08:42:55 +0000 UTC
  Class:       rh-postgresql-apb
  Plan:        dev
Parameters:
  postgresql_database: admin
  postgresql_password: admin
  postgresql_user: admin
  postgresql_version: "9.6"
Bindings:
              NAME               STATUS
+------------------------------+--------+
  mediawiki-postgresql-binding   Ready

Deleting resources

To delete service catalog related resources, you need to unbind service bindings and deprovision the service instances.

Deleting service bindings

To delete all service bindings, associated with a service instance:

$ svcat unbind -n <project-name> (1)
  \ <instance-name> (2)

1	Name of the project that contains the service instance.
2	Name of the service instance associated with the binding.

For example:

$ svcat unbind -n szh-project postgresql-instance
deleted mediawiki-postgresql-binding
$ svcat get bindings
  NAME   NAMESPACE   INSTANCE   STATUS
+------+-----------+----------+--------+

Running this command deletes all service bindings for the instance. For deleting individual bindings from within an instance run the command svcat unbind -n <project-name> —name <binding-name>. For example, svcat unbind -n szh-project —name mediawiki-postgresql-binding.

Verify that the associated secret is deleted.

$ oc get secret -n szh-project
NAME                       TYPE                                  DATA      AGE
builder-dockercfg-jxk48    kubernetes.io/dockercfg               1         9m
builder-token-92jrf        kubernetes.io/service-account-token   4         9m
builder-token-b4sm6        kubernetes.io/service-account-token   4         9m
default-dockercfg-cggcr    kubernetes.io/dockercfg               1         9m
default-token-g4sg7        kubernetes.io/service-account-token   4         9m
default-token-hvdpq        kubernetes.io/service-account-token   4         9m
deployer-dockercfg-wm8th   kubernetes.io/dockercfg               1         9m
deployer-token-hnk5w       kubernetes.io/service-account-token   4         9m
deployer-token-xfr7c       kubernetes.io/service-account-token   4         9m

Deleting service instances

Deprovision the service instance:

$ svcat deprovision postgresql-instance
deleted postgresql-instance
$ svcat get instance
  NAME   NAMESPACE   CLASS   PLAN   STATUS
+------+-----------+-------+------+--------+

Deleting service brokers

To remove broker services for the service catalog, delete the ClusterServiceBroker resource:

$ oc delete clusterservicebrokers template-service-broker
clusterservicebroker "template-service-broker" deleted
$ svcat get brokers
           NAME                                                        URL                                              STATUS
+-------------------------+-------------------------------------------------------------------------------------------+--------+
  ansible-service-broker    https://asb.openshift-ansible-service-broker.svc:1338/ansible-service-broker                Ready

View the ClusterServiceClass resources for the broker, to verify that the broker is removed:
```
$ svcat get classes
  NAME   DESCRIPTION
+------+-------------+
```

Service Catalog CLI