Chapter 10. Configuring service discovery

This guide helps you to configure Service Discovery with the following alternatives:

Additionally, you can find instructions to make an API discoverable.

10.1. Prerequisites

  • You must deploy 3scale 2.5 on an OpenShift cluster, version 3.10 or later.
  • You must use 3scale-amp-openshift-templates to deploy 3scale on OpenShift.

10.2. Configuring with RH SSO

When configuring with Red Hat Single Sign On (RH SSO), consider the following:

  • Users will be redirected to the OAuth Server.
  • If users are not logged into the OAuth Server, they will see a request to enter the credentials to log in.
  • If it is the first time they use 3scale Service Discovery feature with SSO, the OAuth server will request them to authorize 3scale to perform the relevant actions.
  • They will be redirected back to 3scale.

To configure Service Discovery feature with RH SSO, you have the following options:

10.2.1. Using OpenShift OAuth server

As a system administrator, you want users to individually authenticate and authorize 3scale to discover APIs on their behalf using OpenShift builtin OAuth server. This means that 3scale tenant admin users who are willing to use Service Discovery are required to be also OpenShift users, possibly with different access levels over the cluster among them.

  1. Create an OpenShift OAuth client for 3scale. For more details about OpenShift authentication, see OAuth Clients.

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

        $ oc project <3scale-project>
        $ oc edit configmap system

    You need to 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>'
  3. Ensure users have proper permissions to view cluster projects containing discoverable services.

Additional notes:

  • After modifying configmap, you need to redeploy the system-app and system-sidekiq pods to apply the changes.
  • Token lifespan: By default, OpenShift OAuth session tokens expire after 24 hours, as indicated in OpenShift Token Options.

10.2.2. Using RH SSO server (Keycloak)

As a system administrator, you can allow users to individually authenticate and authorize 3scale to discover services using Red Hat SSO for OpenShift.

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

    IMPORTANT: In the client configuration, make sure that the user's username maps to `preferred_username`, so OpenShift can link accounts.
  2. Edit 3scale Service Discovery settings.

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. Make sure these settings are configured.

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

Additional notes:

  • After modifying configmap, you need to redeploy the system-app and system-sidekiq pods to apply the changes.
  • Token lifespan: By default, session tokens expire after 1 minute, as indicated in Keycloak - Session and Token Timeouts. However, it is a good recommendation to set the timeout to an acceptable value of 1 day.

10.3. Configuring without RH SSO

To configure Service Discovery feature without SSO, you can use 3scale Single Service Account to authenticate to OpenShift API service. In this case, there is a seamless authentication to the cluster for the service discovery feature without an authorization layer at the user level, meaning all 3scale tenant administration users will have the same access level to the cluster while discovering API services through 3scale.

Procedure

  1. Edit 3scale Service Discovery settings.

        $ oc project <3scale-project>
        $ oc edit configmap system
  2. Make sure these 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
  3. Provide 3scale deployment amp service account with the relevant permissions to view projects containing discoverable services, by following one of these options:

    • Grant 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. For more information, see OpenShift - Service Accounts.

10.4. Making a service discoverable

An API service, deployed or to be deployed to the OpenShift cluster, can be discoverable by 3scale. To achieve this, configure the OpenShift Service Object YAML definition to include the following metadata:

    metadata:
      labels:
        discovery.3scale.net: "true"
      annotations:
        discovery.3scale.net/scheme: <http | https>
        discovery.3scale.net/port: '<port number of the service within the cluster>'
        discovery.3scale.net/path: <relative base path of the API backend from the root>
        discovery.3scale.net/description-path: <relative or absolute path to the Open API Specification for the API>

From the described metadata, port and scheme are mandatory annotations.

Additionally, Service Discovery will only import the specification if the Content-Type header is one of the following values:

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

Make sure the user or service account (depending on the configured authentication mode) has the right privileges to view the namespace and service.