Chapter 4. Importing the API into 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, to later 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, as 3scale ActiveDocs, the OpenAPI Specification associated with the service.
- 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.
4.1.1. Criteria for a discoverable service
If you want 3scale find an API in an OpenShift cluster, said API 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:
- Select Applications> Services.
-
Select the service, for example
i-task-api
, to open its Details page. - Select Actions> Edit YAML to open the YAML file.
- When you have finished viewing it, select Cancel.
-
The
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
When you create an API provider integration in Fuse Online, the API automatically includes these required annotations.
4.2. Importing discovered services
From the OpenShift cluster, you can import a new API service that conforms to the OpenAPI Specification. This API can be 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
- Log in to the 3scale Administration Portal.
- From the Admin Portal’s Dashboard, click New API.
Choose Import from OpenShift.
- If the OAuth token is not valid, the OpenShift project administrator should authorize access to the 3scale user as described in Authorizing 3scale access to an OpenShift project.
-
In the Namespace field, specify or select the OpenShift project that contains the API, for example
fuse
. -
In the Name field, type or select the name of an OpenShift service within that namespace, for example
i-task-api
. - Click Create Service.
-
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.