SupportConsoleDevelopersStart a trialContact

Chapter 8. Service Discovery

With Red Hat 3scale API Management’s Service Discovery feature, you can import services from OpenShift.

8.1. About Service Discovery

Using Service Discovery, you can scan for discoverable API services that are running in the same OpenShift cluster and automatically import the associated API definitions into 3scale.

You can also update the API integration and the Open API Specification at any time and then 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 Open API Specification (Swagger) up to version 2.0 as 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.

  • For 3scale on premise installations, 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.

8.1.1. Criteria for a discoverable service

An API service must meet the following criteria in order for 3scale Service Discovery to find it:

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

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

  • The OpenShift Service Object YAML definition includes 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
Note

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.

8.2. Configuring Service Discovery

As a 3scale administrator, you can configure Service Discovery with or without an OAuth server.

Prerequisites

  • You must deploy 3scale 2.7 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 3scale must have access to the OpenShift cluster.

8.2.1. Configuring with an OAuth server

If you configure 3scale Service Discovery with an Open Authorization (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:

  1. Section 8.2.1.1, “Using OpenShift OAuth server”
  2. Section 8.2.1.2, “Using RH-SSO server (Keycloak)”

8.2.1.1. Using OpenShift OAuth server

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

  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. 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 need to 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 note

By default, OpenShift OAuth session tokens expire after 24 hours, as indicated in OpenShift Token Options.

8.2.1.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 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.

  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 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.

    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 need to redeploy the system-app and system-sidekiq pods to apply the changes.

Additional note:

  • 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.

8.2.2. Configuring 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. 3scale Single Service Account provides a seamless authentication to the cluster for the Service Discovery without an authorization layer at the user level. All 3scale tenant administration users have the same access level to the cluster while discovering API services through 3scale.

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.

8.3. Discovering services

You can discover a new API service corresponding to an OpenAPI Specification (OAS, also known as Swagger specification), if applicable; which is discovered from the cluster, for management with 3scale.

Prerequisites

  • 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 Section 8.1, “About Service Discovery”.
  • You know the API’s service name and its namespace (OpenShift project).
  • 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 Section 8.4, “Authorizing 3scale access to an 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 Section 8.1, “About Service Discovery”.

Procedure

  1. Log in to the 3scale Administration Portal.
  2. From the Admin Portal’s Dashboard, click New API.

  3. Choose Import from OpenShift.

    • If the OAuth token is not valid, the OpenShift project administrator should authorize access to the 3scale user.
  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 Service.
  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.

Next steps

See the Red Hat 3scale API Management documentation for information about managing the API.

8.4. 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 Section 8.1, “About Service Discovery”.
  • 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 Section 8.1, “About Service Discovery”.

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.

Next steps

See the Red Hat 3scale API Management documentation for information about managing the API.

8.5. Updating services

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

Prerequisite

The service was previously imported/discovered from the cluster.

Procedure

  1. Log in to 3scale Administration Portal.
  2. Navigate to the Overview page of the API service.
  3. Click the Refresh link, next to Source: OpenSource.
  4. Wait for the new API service to be asynchronously imported into 3scale.
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.

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.

© 2024 Red Hat, Inc.