Chapter 29. Service Discovery

With the Service Discovery feature provided by 3scale, you can import API services from OpenShift.

29.1. About Service Discovery

When Service Discovery is configured, 3scale scans for discoverable API services that are running in the same OpenShift cluster and automatically imports the associated API definitions into 3scale. Additionally, 3scale can update the API integration and its specification, based on OpenAPI Specification (OAS), to resynchronize them with the cluster.

Service Discovery offers the following features:

  • Uses the cluster API to query for services that are properly annotated for discovery.
  • Configures 3scale to access the service using an internal endpoint inside the cluster.
  • Imports the API service specification as a 3scale ActiveDocs.
  • Supports OpenShift and Red Hat Single Sign-On (RH SSO) authorization flows.
  • Works with Red Hat Fuse, starting with Fuse version 7.2.

When you import a discoverable service, it keeps its namespace within the project it belongs to. The imported service becomes a new customer-facing API, product, and its corresponding internal API, backend.

  • For 3scale on premises, the 3scale API provider may have its own namespace and services. Discovered services can co-exist with 3scale existing and native services.
  • Fuse discoverable services are deployed to the Fuse production namespace.

29.2. Criteria for a discoverable service

If you want to have 3scale discover an API service in an OpenShift (OCP) cluster, said OCP service must meet the criteria for each element below:

Content-Type header

The API specification’s Content-Type header must be one of the following values:

  • application/swagger+json
  • application/vnd.oai.openapi+json
  • application/json

OpenShift Service Object YAML definition

  • The OpenShift Service Object YAML definition must include the following metadata:

    • The discovery.3scale.net label: (required) Set to "true". 3scale uses this label when it executes the selector definition to find all services that need discovery.
    • The following annotations:

      discovery.3scale.net/discovery-version: (optional) The version of the 3scale discovery process.

      discovery.3scale.net/scheme: (required) The scheme part of the URL where the service is hosted. Possible values are "http" or "https".

      discovery.3scale.net/port: (required) The port number of the service within the cluster.

      discovery.3scale.net/path: (optional) The relative base path of the URL where the service is hosted. You can omit this annotation when the path is at root, "/".

      discovery.3scale.net/description-path: The path to the OpenAPI service description document for the service.

      For example:

          metadata:
            annotations:
              discovery.3scale.net/scheme: "https"
              discovery.3scale.net/port: '8081'
              discovery.3scale.net/path: "/api"
              discovery.3scale.net/description-path: "/api/openapi/json"
           labels:
              discovery.3scale.net: "true"
           name: i-task-api
           namespace: fuse
    • If you are an OpenShift user with administration privileges, you can view the API service’s YAML file in the OpenShift Console:

      1. Select Applications> Services.
      2. Select the service, for example i-task-api, to open its Details page.
      3. Select Actions> Edit YAML to open the YAML file.
      4. When you have finished viewing it, select Cancel.

Clusters with the ovs-networkpolicy plugin

  • To allow traffic between the OpenShift and 3scale projects, clusters that have the ovs-networkpolicy plugin require NetworkPolicy objects created within their application project.
  • For more information about configuring a NetworkPolicy object, see About network policy

29.3. Considerations for configuring OpenShift to enable Service Discovery

As a 3scale administrator, you have two options to configure Service Discovery: with or without an Open Authorization (OAuth) server.

If you configure 3scale Service Discovery with an OAuth server, this is what happens when a user signs in to 3scale:

  • The user is redirected to the OAuth Server.
  • If the user is not already logged in to the OAuth Server, the user is prompted to log in.
  • If it is the first time that the user implements 3scale Service Discovery with SSO, the OAuth server prompts for authorization to perform the relevant actions.
  • The user is redirected back to 3scale.

To configure Service Discovery with an OAuth server, you have the following options:

If you configure Service Discovery without an OAuth server, when a user signs in to 3scale, the user is not redirected. Instead, the 3scale Single Service Account provides a seamless authentication to the cluster for the Service Discovery. All 3scale tenant administration users have the same access level to the cluster while discovering API services through 3scale.

29.4. Configuring Service Discovery with an OpenShift OAuth server

As a 3scale system administrator, allow users to individually authenticate and authorize 3scale to discover APIs by using OpenShift built-in OAuth server.

Prerequisites

  • You must deploy 3scale 2.13 to an OpenShift cluster (version 3.11 or later).
  • To deploy 3scale to OpenShift, you need to use 3scale-amp-openshift-templates.
  • 3scale users that want to use Service Discovery in 3scale must have access to the OpenShift cluster.

Procedure

  1. Create an OpenShift OAuth client for 3scale. For more details, see the OpenShift Authentication documentation. In the following example, replace <provide-a-client-secret> with a secret that you generate and replace <3scale-master-domain-route> with the URL to access the 3scale Master Admin Portal.

        $ oc project default
        $ cat <<-EOF | oc create -f -
        kind: OAuthClient
        apiVersion: v1
        metadata:
         name: 3scale
        secret: "<provide-a-client-secret>"
        redirectURIs:
         - "<3scale-master-domain-route>"
        grantMethod: prompt
        EOF
  2. Open the 3scale Service Discovery settings file:

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. Configure the following settings:

        service_discovery.yml:
          production:
            enabled: true
            authentication_method: oauth
            oauth_server_type: builtin
            client_id: '3scale'
            client_secret: '<choose-a-client-secret>'
  4. Ensure that users have proper permissions to view cluster projects containing discoverable services.

    To give an administrator user, represented by <user>, the view permission for the <namespace> project containing a service to be discovered, use this command:

    oc adm policy add-role-to-user view <user> -n <namespace>
  5. After modifying configmap, you must redeploy the system-app and system-sidekiq pods to apply the changes.

    oc rollout latest dc/system-app
    oc rollout latest dc/system-sidekiq
  6. Check the status of the rollout to ensure it has finished:

    oc rollout status dc/system-app
    oc rollout status dc/system-sidekiq

Additional resources

29.5. Configuring Service Discovery with an RH-SSO server (Keycloak)

As a system administrator, allow users to individually authenticate and authorize 3scale to discover services by using Red Hat Single Sign-On for OpenShift.

For an example about configuring OpenShift to use the RH-SSO deployment as the authorization gateway for OpenShift, you can refer to this workflow.

Prerequisites

  • You must deploy 3scale 2.13 to an OpenShift cluster (version 3.11 or later).
  • To deploy 3scale to OpenShift, you need to use 3scale-amp-openshift-templates.
  • 3scale users that want to use Service Discovery in 3scale must have access to the OpenShift cluster.

Procedure

  1. Create an OAuth client for 3scale in Red Hat OAuth server (Keycloak).

    Note

    In the client configuration, verify that the username maps to preferred_username, so that OpenShift can link accounts.

  2. Edit 3scale Service Discovery settings.

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. Verify that the following settings are configured, where `<the-client-secret-from-Keycloak> is the value that Keycloak generated automatically when you created the OAuth client.

        service_discovery.yml:
          production:
            enabled: true
            authentication_method: oauth
            oauth_server_type: rh_sso
            client_id: '3scale'
            client_secret: '<the-client-secret-from-Keycloak>'
  4. Make sure that users have proper permissions to view cluster projects containing discoverable services.

    For example, to give <user> view permission for the <namespace> project, use this command:

    oc adm policy add-role-to-user view <user> -n <namespace>
  5. After modifying configmap, you must redeploy the system-app and system-sidekiq pods to apply the changes.

Additional resources

  • Token lifespan: By default, session tokens expire after one minute, as indicated in Keycloak - Session and Token Timeouts. However, it is recommended to set the timeout to an acceptable value of one day.

29.6. Configuring Service Discovery without an OAuth server

To configure the 3scale Service Discovery without an OAuth server, you can use 3scale Single Service Account to authenticate to OpenShift API service.

Prerequisites

  • You must deploy 3scale 2.13 to an OpenShift cluster (version 3.11 or later).
  • To deploy 3scale to OpenShift, you need to use 3scale-amp-openshift-templates.
  • 3scale users that want to use Service Discovery in 3scale must have access to the OpenShift cluster.

Procedure

  1. Verify that the 3scale project is the current project.

       $ oc project <3scale-project>
  2. Open the 3scale Service Discovery settings in an editor.

       $ oc edit configmap system
  3. Verify that the following settings are configured.

    service_discovery.yml:
       production:
          enabled: <%= cluster_token_file_exists = File.exists?(cluster_token_file_path = '/var/run/secrets/kubernetes.io/serviceaccount/token') %>
          bearer_token: "<%= File.read(cluster_token_file_path) if cluster_token_file_exists %>"
          authentication_method: service_account
  4. Provide the 3scale deployment amp service account with the relevant permissions to view projects containing discoverable services by following one of these options:

    • Grant the 3scale deployment amp service account with view cluster level permission.

      oc adm policy add-cluster-role-to-user view system:serviceaccount:<3scale-project>:amp
    • Apply a more restrictive policy as described in OpenShift - Service Accounts.

29.7. Importing discovered services

From the OpenShift cluster, import a new API service that conforms to the OpenAPI Specification. This API is managed with 3scale.

Prerequisites

  • The OpenShift administrator has configured Service Discovery for the OpenShift cluster. For example, the OpenShift administrator must have enabled 3scale discovery by editing the Fuse Online custom resource to specify the URL for their 3scale user interface.
  • The 3scale administrator has configured the 3scale deployment for Service Discovery as described in About Service Discovery.
  • The 3scale administrator has granted your 3scale user or service account (depending on the configured authentication mode) the necessary privileges to view the API service and its namespace. For more details, you can see Authorizing 3scale access to an OpenShift project.
  • The API has the correct annotations that enable Service Discovery, as described in Criteria for a discoverable service.
  • The API service is deployed on the same OpenShift cluster where 3scale is installed.
  • You know the API’s service name and its namespace (OpenShift project).

Procedure

  1. Log in to the 3scale Admin Portal.
  2. From APIs on the Admin Portal Dashboard, click Create Product
  3. Click Import from OpenShift.

  4. In the Namespace field, specify or select the OpenShift project that contains the API, for example fuse.
  5. In the Name field, type or select the name of an OpenShift service within that namespace, for example i-task-api.
  6. Click Create Product.
  7. Wait for the new API service to be asynchronously imported into 3scale. A message appears in the upper right section of the Admin Portal: The service will be imported shortly. You will receive a notification when it is done.

Additional resources

29.8. Authorizing 3scale access to an OpenShift project

As an OpenShift project administrator, you can authorize a 3scale user to access a namespace when the OAuth token is not valid.

Prerequisites

  • You need to have the credentials as an OpenShift project administrator.
  • The OpenShift administrator has configured Service Discovery for the OpenShift cluster. For example, for Fuse Online APIs, the OpenShift administrator must set the Fuse Online service’s CONTROLLERS_EXPOSE_VIA3SCALE environment variable to true.
  • The 3scale administrator has configured the 3scale deployment for Service Discovery as described in Criteria for a discoverable service.
  • You know the API service name and its namespace of the OpenShift project.
  • The API service is deployed on the same OpenShift cluster where 3scale is installed.
  • The API has the correct annotations that enable Service Discovery, as described in Criteria for a discoverable service.

Procedure

  1. Click the Authenticate to enable this option link.
  2. Log in to OpenShift using the namespace administrator credentials.
  3. Authorize access to the 3scale user, by clicking Allow selected permissions.

Additional resources

29.9. Updating services

You can update (refresh) an existing API service in 3scale with the current definitions for the service in the cluster.

Prerequisites

Procedure

  1. Log in to 3scale Admin Portal.
  2. Navigate to the Overview page of the API product.
  3. Click the Refresh link, next to Source: OpenSource.
  4. Wait for the new API service to be asynchronously imported into 3scale.