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
  5. ...
  6. rh-mariadb-apb Mariadb apb implementation
  7. rh-mysql-apb Software Collections MySQL APB
  8. rh-postgresql-apb SCL PostgreSQL apb
  9. 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
  8. Plans:
  9. NAME DESCRIPTION
  10. +------+--------------------------------+
  11. prod A single DB server with
  12. persistent storage
  13. dev A single DB server with no
  14. 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
  5. ...
  6. prod rh-mariadb-apb This plan deploys a single
  7. MariaDB instance with 10 GiB
  8. of persistent storage
  9. dev rh-mariadb-apb This plan deploys a single
  10. MariaDB instance with
  11. ephemeral storage
  12. prod rh-mysql-apb A MySQL server with persistent
  13. storage
  14. dev rh-mysql-apb A MySQL server with ephemeral
  15. storage
  16. prod rh-postgresql-apb A single DB server with
  17. persistent storage
  18. dev rh-postgresql-apb A single DB server with no
  19. 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
  8. Instances:
  9. No instances defined
  10. Instance Create Parameter Schema:
  11. $schema: http://json-schema.org/draft-04/schema
  12. additionalProperties: false
  13. properties:
  14. postgresql_database:
  15. default: admin
  16. pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
  17. title: PostgreSQL Database Name
  18. type: string
  19. postgresql_password:
  20. pattern: ^[a-zA-Z0-9_~!@#$%^&*()-=<>,.?;:|]+$
  21. title: PostgreSQL Password
  22. type: string
  23. postgresql_user:
  24. default: admin
  25. maxLength: 63
  26. pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
  27. title: PostgreSQL User
  28. type: string
  29. postgresql_version:
  30. default: "9.6"
  31. enum:
  32. - "9.6"
  33. - "9.5"
  34. - "9.4"
  35. title: PostgreSQL Version
  36. type: string
  37. required:
  38. - postgresql_database
  39. - postgresql_user
  40. - postgresql_password
  41. - postgresql_version
  42. type: object
  43. Instance Update Parameter Schema:
  44. $schema: http://json-schema.org/draft-04/schema
  45. additionalProperties: false
  46. properties:
  47. postgresql_version:
  48. default: "9.6"
  49. enum:
  50. - "9.6"
  51. - "9.5"
  52. - "9.4"
  53. title: PostgreSQL Version
  54. type: string
  55. required:
  56. - postgresql_version
  57. type: object
  58. Binding Create Parameter Schema:
  59. $schema: http://json-schema.org/draft-04/schema
  60. additionalProperties: false
  61. 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
    7. Parameters:
    8. postgresql_database: admin
    9. postgresql_password: admin
    10. postgresql_user: admin
    11. 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
  6. Parameters:
  7. {}
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
    7. Parameters:
    8. postgresql_database: admin
    9. postgresql_password: admin
    10. postgresql_user: admin
    11. postgresql_version: "9.6"
    12. Bindings:
    13. NAME STATUS
    14. +------------------------------+--------+
    15. 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
    3. $ svcat get bindings
    4. NAME NAMESPACE INSTANCE STATUS
    5. +------+-----------+----------+--------+

    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
  3. $ svcat get instance
  4. NAME NAMESPACE CLASS PLAN STATUS
  5. +------+-----------+-------+------+--------+

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
    3. $ svcat get brokers
    4. NAME URL STATUS
    5. +-------------------------+-------------------------------------------------------------------------------------------+--------+
    6. 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. +------+-------------+