Service catalog command-line interface (CLI)

You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see [4]

You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see [4]

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:

  1. # 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:

  1. $ 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:

  1. $ svcat get brokers
  2.            NAME                                                        URL                                              STATUS
  3. +-------------------------+-------------------------------------------------------------------------------------------+--------+
  4.   ansible-service-broker    https://asb.openshift-ansible-service-broker.svc:1338/ansible-service-broker                Ready
  5.   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:

  1. $ svcat sync broker ansible-service-broker
  2. Synchronization requested for broker: ansible-service-broker

View broker details

To view the details of the broker:

  1. $ svcat describe broker ansible-service-broker
  2.   Name:     ansible-service-broker
  3.   URL:      https://openshift-automation-service-broker.openshift-automation-service-broker.svc:1338/openshift-automation-service-broker/
  4.   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:

  1. $ svcat get classes
  2.         NAME                   DESCRIPTION
  3. +-------------------+--------------------------------+
  4.   rh-mediawiki-apb    Mediawiki apb implementation
  6.   ...
  8.   rh-mariadb-apb      Mariadb apb implementation
  9.   rh-mysql-apb        Software Collections MySQL APB
  10.   rh-postgresql-apb   SCL PostgreSQL apb
  11.                       implementation

To view details of a service class:

  1. $ svcat describe class rh-postgresql-apb
  2.   Name:          rh-postgresql-apb
  3.   Description:   SCL PostgreSQL apb implementation
  4.   UUID:          d5915e05b253df421efe6e41fb6a66ba
  5.   Status:        Active
  6.   Tags:          database, postgresql
  7.   Broker:        ansible-service-broker
  9. Plans:
  10.   NAME            DESCRIPTION
  11. +------+--------------------------------+
  12.   prod   A single DB server with
  13.          persistent storage
  14.   dev    A single DB server with no
  15.          storage

View service plans

To view the ClusterServicePlan resources available in the cluster:

  1. $ svcat get plans
  2.    NAME           CLASS                  DESCRIPTION
  3. +---------+-------------------+--------------------------------+
  4.   default   rh-mediawiki-apb    An APB that deploys MediaWiki
  6.   ...
  8.   prod      rh-mariadb-apb      This plan deploys a single
  9.                                 MariaDB instance with 10 GiB
  10.                                 of persistent storage
  11.   dev       rh-mariadb-apb      This plan deploys a single
  12.                                 MariaDB instance with
  13.                                 ephemeral storage
  14.   prod      rh-mysql-apb        A MySQL server with persistent
  15.                                 storage
  16.   dev       rh-mysql-apb        A MySQL server with ephemeral
  17.                                 storage
  18.   prod      rh-postgresql-apb   A single DB server with
  19.                                 persistent storage
  20.   dev       rh-postgresql-apb   A single DB server with no
  21.                                 storage

View details of a plan:

  1. $ svcat describe plan rh-postgresql-apb/dev
  2.   Name:          dev
  3.   Description:   A single DB server with no storage
  4.   UUID:          9783fc2e859f9179833a7dd003baa841
  5.   Status:        Active
  6.   Free:          true
  7.   Class:         rh-postgresql-apb
  9. Instances:
  10. No instances defined
  12. Instance Create Parameter Schema:
  13.   $schema: http://json-schema.org/draft-04/schema
  14.   additionalProperties: false
  15.   properties:
  16.     postgresql_database:
  17.       default: admin
  18.       pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
  19.       title: PostgreSQL Database Name
  20.       type: string
  21.     postgresql_password:
  22.       pattern: ^[a-zA-Z0-9_~!@#$%^&*()-=<>,.?;:|]+$
  23.       title: PostgreSQL Password
  24.       type: string
  25.     postgresql_user:
  26.       default: admin
  27.       maxLength: 63
  28.       pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
  29.       title: PostgreSQL User
  30.       type: string
  31.     postgresql_version:
  32.       default: "9.6"
  33.       enum:
  34.       - "9.6"
  35.       - "9.5"
  36.       - "9.4"
  37.       title: PostgreSQL Version
  38.       type: string
  39.   required:
  40.   - postgresql_database
  41.   - postgresql_user
  42.   - postgresql_password
  43.   - postgresql_version
  44.   type: object
  46. Instance Update Parameter Schema:
  47.   $schema: http://json-schema.org/draft-04/schema
  48.   additionalProperties: false
  49.   properties:
  50.     postgresql_version:
  51.       default: "9.6"
  52.       enum:
  53.       - "9.6"
  54.       - "9.5"
  55.       - "9.4"
  56.       title: PostgreSQL Version
  57.       type: string
  58.   required:
  59.   - postgresql_version
  60.   type: object
  62. Binding Create Parameter Schema:
  63.   $schema: http://json-schema.org/draft-04/schema
  64.   additionalProperties: false
  65.   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.

  1. Create a new project.

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

  2. Create service instance using the command:

    1. $ 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
    2.   Name:        postgresql-instance
    3.   Namespace:   szh-project
    4.   Status:
    5.   Class:       rh-postgresql-apb
    6.   Plan:        dev
    8. Parameters:
    9.   postgresql_database: admin
    10.   postgresql_password: admin
    11.   postgresql_user: admin
    12.   postgresql_version: "9.6"
View service instance details

To view service instance details:

  1. $ svcat get instance
  2.          NAME            NAMESPACE          CLASS         PLAN   STATUS
  3. +---------------------+-------------+-------------------+------+--------+
  4.   postgresql-instance   szh-project   rh-postgresql-apb   dev    Ready

Create ServiceBinding

When you create a ServiceBinding resource:

  1. The service catalog controller communicates with the broker server to initiate the binding.

  2. The broker server create credentials and issue them to the service catalog controller.

  3. The service catalog controller adds those credentials as secrets to the project.

Create the service binding using the command:

  1. $ svcat bind postgresql-instance --name mediawiki-postgresql-binding
  2.   Name:        mediawiki-postgresql-binding
  3.   Namespace:   szh-project
  4.   Status:
  5.   Instance:    postgresql-instance
  7. Parameters:
  8.   {}
View service binding details

  1. To view service binding details:

    1. $ svcat get bindings
    2.               NAME                NAMESPACE         INSTANCE         STATUS
    3. +------------------------------+-------------+---------------------+--------+
    4.   mediawiki-postgresql-binding   szh-project   postgresql-instance   Ready

  2. Verify the instance details after binding the service:

    1. $ svcat describe instance postgresql-instance
    2.   Name:        postgresql-instance
    3.   Namespace:   szh-project
    4.   Status:      Ready - The instance was provisioned successfully @ 2018-06-05 08:42:55 +0000 UTC
    5.   Class:       rh-postgresql-apb
    6.   Plan:        dev
    8. Parameters:
    9.   postgresql_database: admin
    10.   postgresql_password: admin
    11.   postgresql_user: admin
    12.   postgresql_version: "9.6"
    14. Bindings:
    15.               NAME               STATUS
    16. +------------------------------+--------+
    17.   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

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

    1. $ svcat unbind -n <project-name> (1)
    2.   \ <instance-name> (2)
    1Name of the project that contains the service instance.
    2Name of the service instance associated with the binding.

    For example:

    1. $ svcat unbind -n szh-project postgresql-instance
    2. deleted mediawiki-postgresql-binding
    4. $ svcat get bindings
    5.   NAME   NAMESPACE   INSTANCE   STATUS
    6. +------+-----------+----------+--------+

    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.

  2. Verify that the associated secret is deleted.

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

Deleting service instances

Deprovision the service instance:

  1. $ svcat deprovision postgresql-instance
  2. deleted postgresql-instance
  4. $ svcat get instance
  5.   NAME   NAMESPACE   CLASS   PLAN   STATUS
  6. +------+-----------+-------+------+--------+

Deleting service brokers

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

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

  2. View the ClusterServiceClass resources for the broker, to verify that the broker is removed:

    1. $ svcat get classes
    2.   NAME   DESCRIPTION
    3. +------+-------------+