Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Discovering the API in 3Scale

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

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

4.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
      Copy to Clipboard
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.
Note

When you create an API provider integration in Fuse Online, the API automatically includes these required annotations.

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

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