Chapter 29. Service Discovery
With the Service Discovery feature provided by 3scale, you can import API services from OpenShift.
29.1. About Service Discovery
When Service Discovery is configured, 3scale scans for discoverable API services that are running in the same OpenShift cluster and automatically imports the associated API definitions into 3scale. Additionally, 3scale can update the API integration and its specification, based on OpenAPI Specification (OAS), to 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 the API service specification as a 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 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.
29.2. Criteria for a discoverable service
If you want to have 3scale discover an API service in an OpenShift (OCP) cluster, said OCP service 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.
29.3. Considerations for configuring OpenShift to enable Service Discovery
As a 3scale administrator, you have two options to configure Service Discovery: with or without an Open Authorization (OAuth) server.
If you configure 3scale Service Discovery with an 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 single sign-on (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:
If you configure Service Discovery without an OAuth server, when a user signs in to 3scale, the user is not redirected. Instead, the 3scale Single Service Account provides a seamless authentication to the cluster for the Service Discovery. All 3scale tenant administration users have the same access level to the cluster while discovering API services through 3scale.
29.4. Configuring Service Discovery with an OpenShift OAuth server
As a 3scale system administrator, allow users to individually authenticate and authorize 3scale to discover APIs by using OpenShift built-in OAuth server.
Prerequisites
- You must deploy 3scale 2.14 to an OpenShift Container Platform (OCP) 4.x cluster.
- 3scale users that want to use Service Discovery in 3scale must have access to the OpenShift cluster.
Procedure
Create an OpenShift OAuth client for 3scale. For more details, see the OpenShift Authentication documentation. In the following example, replace
<provide-a-client-secret>
with a secret that you generate and replace<3scale-master-domain-route>
with the URL to access the 3scale Master Admin Portal:$ oc project default $ cat <<-EOF | oc create -f - kind: OAuthClient apiVersion: v1 metadata: name: 3scale secret: "<provide-a-client-secret>" redirectURIs: - "<3scale-master-domain-route>" grantMethod: prompt EOF
Open the 3scale Service Discovery settings file:
$ oc project <3scale-project> $ oc edit configmap system
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>'
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>
After modifying
configmap
, you must redeploy thesystem-app
andsystem-sidekiq
pods to apply the changes:$ oc rollout latest dc/system-app $ oc rollout latest dc/system-sidekiq
Check the status of the rollout to ensure it has finished:
$ oc rollout status dc/system-app $ oc rollout status dc/system-sidekiq
Additional resources
- For more information about OpenShift OAuth tokens, see Configuring the internal OAuth server.
29.5. Configuring Service Discovery with a Red Hat single sign-on server (Keycloak)
As a system administrator, allow users to individually authenticate and authorize 3scale to discover services by using Red Hat Single Sign-On for OpenShift.
For an example about configuring OpenShift to use the Red Hat single sign-on deployment as the authorization gateway for OpenShift, you can refer to this workflow.
Prerequisites
- You must deploy 3scale 2.14 to an OpenShift Container Platform (OCP) 4.x cluster.
- 3scale users that want to use Service Discovery in 3scale must have access to the OpenShift cluster.
Procedure
Create an OAuth client for 3scale in Red Hat OAuth server (Keycloak).
NoteIn the client configuration, verify that the
username
maps topreferred_username
, so that OpenShift can link accounts.Edit 3scale Service Discovery settings:
$ oc project <3scale-project> $ oc edit configmap system
Verify that the following settings are configured, where
`<the-client-secret-from-Keycloak>
is the value that Keycloak generated automatically when you created the OAuth client:service_discovery.yml: production: enabled: true authentication_method: oauth oauth_server_type: rh_sso client_id: '3scale' client_secret: '<the-client-secret-from-Keycloak>'
Make sure that 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>
-
After modifying
configmap
, you must redeploy thesystem-app
andsystem-sidekiq
pods to apply the changes.
Additional resources
- 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.
29.6. Configuring Service Discovery 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.
Prerequisites
- You must deploy 3scale 2.14 to an OpenShift Container Platform (OCP) 4.x cluster.
- 3scale users that want to use Service Discovery in 3scale must have access to the OpenShift cluster.
Procedure
Verify that the 3scale project is the current project.
$ oc project <3scale-project>
Open the 3scale Service Discovery settings in an editor.
$ oc edit configmap system
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
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 withview
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.
29.7. Importing discovered services
From the OpenShift cluster, import a new API service that conforms to the OpenAPI Specification. This API is 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 Admin Portal.
- From APIs on the Admin Portal Dashboard, click Create Product.
Click 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 Product.
-
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.
Additional resources
- See the Red Hat 3scale API Management documentation for information about managing the API.
29.8. 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 totrue
. - The 3scale administrator has configured the 3scale deployment for Service Discovery as described in Criteria for a discoverable service.
- 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 Criteria for a discoverable service.
Procedure
- Click the Authenticate to enable this option link.
- Log in to OpenShift using the namespace administrator credentials.
- Authorize access to the 3scale user, by clicking Allow selected permissions.
Additional resources
- See the Red Hat 3scale API Management documentation for information about managing the API.
29.9. Updating services
You can update (refresh) an existing API service in 3scale with the current definitions for the service in the cluster.
Prerequisites
- The service was previously imported from the cluster, as described in Importing discovered services.
Procedure
- Log in to 3scale Admin Portal.
- Navigate to the Overview page of the API product.
- Click the Refresh link, next to Source: OpenSource.
- Wait for the new API service to be asynchronously imported into 3scale.