Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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
Copy link

  • 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
Copy link

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:

  1. Section 10.2.1, “Using OpenShift OAuth server”.
  2. Section 10.2.2, “Using RH SSO server (Keycloak)”.

10.2.1. Using OpenShift OAuth server
Copy link

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
    Copy to Clipboard Toggle word wrap

  2. Edit 3scale Service Discovery settings. 

        $ oc project <3scale-project>
    $ oc edit configmap system
    Copy to Clipboard Toggle word wrap

    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>'
    Copy to Clipboard Toggle word wrap
  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)
Copy link

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.
    Copy to Clipboard Toggle word wrap

  2. Edit 3scale Service Discovery settings. 

        $ oc project <3scale-project>
    $ oc edit configmap system
    Copy to Clipboard Toggle word wrap

  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>'
    Copy to Clipboard Toggle word wrap
  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
Copy link

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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
-------------------------------
      Copy to Clipboard Toggle word wrap
    • Apply a more restrictive policy. For more information, see OpenShift - Service Accounts.

10.4. Making a service discoverable
Copy link

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>
Copy to Clipboard Toggle word wrap

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.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat