Chapter 10. Configuring service discovery
This guide helps you to configure Service Discovery with the following alternatives:
Additionally, you can find instructions to make an API discoverable.
10.1. Prerequisites
- You must deploy 3scale 2.5 on an OpenShift cluster, version 3.10 or later.
- You must use 3scale-amp-openshift-templates to deploy 3scale on OpenShift.
10.2. Configuring with RH SSO
When configuring with Red Hat Single Sign On (RH SSO), consider the following:
- Users will be redirected to the OAuth Server.
- If users are not logged into the OAuth Server, they will see a request to enter the credentials to log in.
- If it is the first time they use 3scale Service Discovery feature with SSO, the OAuth server will request them to authorize 3scale to perform the relevant actions.
- They will be redirected back to 3scale.
To configure Service Discovery feature with RH SSO, you have the following options:
10.2.1. Using OpenShift OAuth server
As a system administrator, you want users to individually authenticate and authorize 3scale to discover APIs on their behalf using OpenShift builtin OAuth server. This means that 3scale tenant admin users who are willing to use Service Discovery are required to be also OpenShift users, possibly with different access levels over the cluster among them.
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 EOFEdit 3scale Service Discovery settings.
$ oc project <3scale-project> $ oc edit configmap systemYou need to 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 users have proper permissions to view cluster projects containing discoverable services.
Additional notes:
-
After modifying
configmap, you need to redeploy thesystem-appandsystem-sidekiqpods to apply the changes. - Token lifespan: By default, OpenShift OAuth session tokens expire after 24 hours, as indicated in OpenShift Token Options.
10.2.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 SSO for OpenShift.
Create an OAuth client for 3scale in Red Hat OAuth server (Keycloak).
IMPORTANT: In the client configuration, make sure that the user's username maps to `preferred_username`, so OpenShift can link accounts.
Edit 3scale Service Discovery settings.
$ oc project <3scale-project> $ oc edit configmap systemMake sure 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>'- Make sure users have proper permissions to view cluster projects containing discoverable services
Additional notes:
-
After modifying
configmap, you need to redeploy thesystem-appandsystem-sidekiqpods to apply the changes. - Token lifespan: By default, session tokens expire after 1 minute, as indicated in Keycloak - Session and Token Timeouts. However, it is a good recommendation to set the timeout to an acceptable value of 1 day.
10.3. Configuring without RH SSO
To configure Service Discovery feature without SSO, you can use 3scale Single Service Account to authenticate to OpenShift API service. In this case, there is a seamless authentication to the cluster for the service discovery feature without an authorization layer at the user level, meaning all 3scale tenant administration users will have the same access level to the cluster while discovering API services through 3scale.
Procedure
Edit 3scale Service Discovery settings.
$ oc project <3scale-project> $ oc edit configmap systemMake sure these 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_accountProvide 3scale deployment
ampservice account with the relevant permissions to view projects containing discoverable services, by following one of these options:Grant 3scale deployment
ampservice account withviewcluster level permission.-------------------------------- oc adm policy add-cluster-role-to-user view system:serviceaccount:<3scale-project>:amp -------------------------------
- Apply a more restrictive policy. For more information, see OpenShift - Service Accounts.
10.4. Making a service discoverable
An API service, deployed or to be deployed to the OpenShift cluster, can be discoverable by 3scale. To achieve this, configure the OpenShift Service Object YAML definition to include the following metadata:
metadata:
labels:
discovery.3scale.net: "true"
annotations:
discovery.3scale.net/scheme: <http | https>
discovery.3scale.net/port: '<port number of the service within the cluster>'
discovery.3scale.net/path: <relative base path of the API backend from the root>
discovery.3scale.net/description-path: <relative or absolute path to the Open API Specification for the API>
From the described metadata, port and scheme are mandatory annotations.
Additionally, Service Discovery will only import the specification if the Content-Type header is one of the following values:
-
application/swagger+json -
application/vnd.oai.openapi+json -
application/json
Make sure the user or service account (depending on the configured authentication mode) has the right privileges to view the namespace and service.
