Installing and Configuring Service Instance Manager

Page last updated:

This topic provides instructions for operators for how to install and configure Service Instance Manager.

Overview

Service Instance Manager consists of two apps. These are deployed on a single host foundation.

The apps are:

  • service-instance-manager-api, which communicates with the Cloud Controller of all target foundations.
  • service-instance-manager, which hosts the web UI.


To install and configure Service Instance Manager:

  1. Download Service Instance Manager
  2. Configure the API App
  3. Deploy the Apps
  4. Create a UAA client

About Networking for Service Instance Manager

Before you begin installation, here are a few things to know about the networking and routing for the Service Instance Manager:

  • The service-instance-manager-api app must be able to reach the Cloud Controller API (CAPI) for each target foundation. Depending on the network setup, extra steps might be required to allow traffic from the app to the target foundation.

  • The service-instance-manager web app only requires a connection to the service-instance-manager-api. The web app does not connect directly to the target foundations.

  • Because of browser cross-origin access, the service-instance-manager-api API app and the service-instance-manager-api web app must be pushed with the same route. The web app expects the API app to be available at /api.

Prerequisites

Before you install and configure Service Instance Manager, you must have:

  1. The cf Command Line Interface (CLI). For how to install it, see Installing the cf CLI.

  2. The User Account and Authentication Command Line Interface (UAAC). For how to install it, see cf-uaac on GitHub.

Download Service Instance Manager

Download the latest version of Service Instance Manager from VMware Tanzu Network.

Configure the API App

To configure the API app:

  1. Unzip the Service Instance Manager tarball you downloaded.

  2. Open the config.json file that you just extracted from the tarball in a text editor.

  3. Edit config.json to include a section for each target foundation. The example below shows the configuration for two foundations.

    [
      {
        "name":"TARGET-FOUNDATION",
        "cfApi":"API-URL"
      },
      {
        "name":"TARGET-FOUNDATION",
        "cfApi":"API-URL",
        "client_id":"CUSTOM-UAA-CLIENT-ID",
        "identityProviderName":"SAML-PROVIDER"
      }
      ...
    ]
    

    Where:

    • TARGET-FOUNDATION is a human-readable name for the target foundation.
    • API-URL is the URL of the API endpoint for the target foundation.
    • CUSTOM-UAA-CLIENT-ID (Optional) is a custom client_id that you can set when following the steps in Create a UAA Client below. If you do not set a custom ID, it defaults to fleet-manager.
    • SAML-PROVIDER (Optional) is the name of the identity provider that you can configure for UAA. If an identity provider is configured, the user need only log in once to use Service Instance Manager. If you do not know the name of your identity provider, follow steps 1–4 of Configure TAS for VMs as a Service Provider for SAML.

Deploy the Apps

To install Service Instance Manager, deploy the apps that you downloaded:

  1. Log in to the cf CLI for the foundation on which you want to host Service Instance Manager by running:

    cf api https://api.HOST-CLOUD-FOUNDRY-DOMAIN
    cf auth
    

    For example:

    $ cf api https://api.my-cloud-foundry.example.com
    $ cf auth
    
  2. Target the org and space to deploy Service Instance Manager in by running:

    cf target -o HOST-ORG -s HOST-SPACE
    
  3. Execute the installation script install.sh to push the API and web apps by running:

    ./install.sh
    

    This passes the config.json to the API app.

Create UAA Clients

Before logging in to Service Instance Manager, you must create a client in the UAA of each target foundation. This client is used to authenticate on behalf of the user when a user logs in to Service Instance Manager.

This means that Service Instance Manager only has the permissions available to that user on each target foundation.

To create the clients in each target foundation, perform the following steps for each foundation:

  1. Retrieve the UAA admin credentials for the foundation from the VMware Tanzu Application Service for VMs tile in Ops Manager. These are found at Credentials > UAA > Admin Client Credentials.

  2. Target and authenticate with UAA for the foundation by running:

    uaac target uaa.YOUR-DOMAIN
    uaac token client get
    

    For example:

    $ uaac target uaa.target-cf-system-domain.example.com
    $ uaac token client get
    

    This command prompts for the admin credentials of UAA that you retrieved in the previous step.

  3. Retrieve the route where the Service Instance Manager app is deployed on the host foundation by running:

    cf app service-instance-manager
    export SIM_ROUTE="$(cf app service-instance-manager | grep routes | awk '{ print $2 }')"
    

    Note: The variable SIM_ROUTE is the route where the Service Instance Manager app is deployed on the host foundation. It is the same for every client in each target foundation.
    redirect_uri is used by UAA to confirm that the request for authentication is coming from a known location.

  4. Add the client to UAA by running:

    uaac client add "fleet-manager"  \
        --name "Fleet Manager client for Service Instance Manager" \
        --scope "cloud_controller.read,cloud_controller.write,cloud_controller.admin_read_only,cloud_controller.admin,cloud_controller.global_auditor" \
        --authorized_grant_types "implicit" \
        --redirect_uri "http://${SIM_ROUTE}/**,https://${SIM_ROUTE}/**" \
        --autoapprove "true" \
        --secret ""
    

Service Instance Manager is now accessible at the route it was pushed to.

(Optional) Enable the Service Instance Manager Cache

You must enable the Service Instance Manager cache for foundations of more than 2000 service instances or service bindings.

To enable the Service Instance Manager cache:

  1. Set the SIM_CACHE_ENABLED environment variable in the Service Instance Manager API app on the host foundation by running:

     cf set-env service-instance-manager-api SIM_CACHE_ENABLED true
    

Troubleshooting

This section provides troubleshooting information for Service Instance Manager.


Buildpack Unavailable

Symptom During deployment of Service Instance Manager, the cf push command outputs the following error:
$ Failed to clone git repository at https://github.com/cloudfoundry/nodejs-buildpack.git
Cause The host foundation cannot retrieve the NodeJS buildpack from GitHub.
Solution To solve this issue, do the following:
  1. Look up the buildpack version listed in the service-instance-manager/api/manifest.yml.

  2. Download the corresponding buildpack version from VMware Tanzu Network or GitHub.

  3. Install the buildpack by running:

    cf create-buildpack BUILDPACK-PATH


The Cloud Controller is Slow to Respond to Requests

Symptom The Cloud Controller is slow to respond to requests, or does not respond at all.
Cause When targeting a foundation with tens of thousands of service instances, Service Instance Manager can deny service to the Cloud
Controller.
Solution To solve this issue, do the following:
  1. Stop both Service Instance Manager apps:
    1. Log in to the cf CLI for the foundation on which you hosted Service Instance Manager by running:
      cf api https://api.HOST-CLOUD-FOUNDRY-DOMAIN
      cf auth
      For example:
      $ cf api https://api.my-cloud-foundry.example.com api.my-cloud-foundry.example.com
      $ cf auth
      
    2. Target the org and space that you deployed Service Instance Manager in by running:
      cf target -o HOST-ORG -s HOST-SPACE
    3. Stop the apps by running:
      cf stop service-instance-manager
      cf stop service-instance-manager-api
  2. Remove the section for the foundation that has an unresponsive Cloud Controller from the config.json that you edited as part of Configure the API App.
  3. Run the install script to re-push the apps:
    ./install.sh