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, Red Hat single sign-on and Red Hat build of Keycloak 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: 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 . 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: Configuring Service Discovery with an OpenShift OAuth server Configuring Service Discovery with a Red Hat single sign-on server (Keycloak) 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.15 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: USD oc project default USD 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: USD oc project <3scale-project> USD 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: USD oc adm policy add-role-to-user view <user> -n <namespace> After modifying configmap , you must redeploy the system-app and system-sidekiq pods to apply the changes: USD oc rollout restart deployment/system-app USD oc rollout restart deployment/system-sidekiq Check the status of the rollout to ensure it has finished: USD oc rollout status deployment/system-app USD oc rollout status deployment/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.15 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). Note In the client configuration, verify that the username maps to preferred_username , so that OpenShift can link accounts. Edit 3scale Service Discovery settings: USD oc project <3scale-project> USD 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: USD oc adm policy add-role-to-user view <user> -n <namespace> After modifying configmap , you must redeploy the system-app and system-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.15 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. USD oc project <3scale-project> Open the 3scale Service Discovery settings in an editor. USD 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 with view cluster level permission. USD 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 to true . 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, to Source: OpenSource. Wait for the new API service to be asynchronously imported into 3scale.

Commands:
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
oc project default USD 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
oc project <3scale-project> oc edit configmap system
service_discovery.yml: production: enabled: true authentication_method: oauth oauth_server_type: builtin client_id: '3scale' client_secret: '<choose-a-client-secret>'
oc adm policy add-role-to-user view <user> -n <namespace>
oc rollout restart deployment/system-app oc rollout restart deployment/system-sidekiq
oc rollout status deployment/system-app oc rollout status deployment/system-sidekiq
oc project <3scale-project> oc edit configmap system
service_discovery.yml: production: enabled: true authentication_method: oauth oauth_server_type: rh_sso client_id: '3scale' client_secret: '<the-client-secret-from-Keycloak>'
oc adm policy add-role-to-user view <user> -n <namespace>
oc project <3scale-project>
oc edit configmap system
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
oc adm policy add-cluster-role-to-user view system:serviceaccount:<3scale-project>:amp