Chapter 2. Configuring Red Hat Integration products for API development and deployment
Your OpenShift Container Platform (OCP) on premise administrator must configure the Red Hat Integration products for API development and deployment:
- Deploy Fuse Online and 3scale API Management on the same OpenShift cluster (requires OpenShift cluster admin permission).
- Configure Fuse Online to enable 3scale discovery of APIs (requires permission to install Fuse Online to an OpenShift project).
- Configure 3scale for service discovery (requires 3scale admin permission).
In addition, the following configurations are required:
- For Fuse Online, the default behavior is that APIs are not exposed for automatic discovery in 3scale. You must enable discovery for the OpenShift project in which you install Fuse Online.
- A 3scale API Management administrator must configure 3scale for service discovery. For example, the administrator must ensure that users have proper permissions to view cluster projects that contain discoverable services.
2.1. Configuring Fuse Online to enable 3scale discovery of APIs
If you create an API provider integration, you might want to enable discovery of the API for that integration in Red Hat 3scale. The default behavior is that APIs are not exposed for automatic discovery in 3scale. When you enable discovery, you must provide a URL for a 3scale user interface.
To configure Fuse Online to enable 3scale discovery of APIs before you install Fuse Online, see Descriptions of custom resource attributes that configure Fuse Online.
After installation, you can enable discovery by updating the syndesis
custom resource. Instructions for doing this are in this topic. When you enable discovery, it applies to only the OpenShift project that you are connected to when you update the resource.
Turning on 3scale service discovery means that:
The default behavior is that 3scale publishes API provider integrations. When 3scale publishes an API provider integration:
- Fuse Online does not provide an external URL for an API provider integration that is running.
- The API is accessible only through 3scale. Configuration in 3scale is required to expose the endpoint. For details, see Red Hat 3scale API Management, Service Discovery.
- The creator of an API provider integration can disable 3scale discovery for that integration. In other words, each API provider integration creator can choose whether that integration’s API is discoverable.
Prerequisites
- Fuse Online is installed on OCP on-site.
-
The
oc
client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed. - You have permission to install Fuse Online in the project for which you want to enable discovery of APIs.
Procedure
Log in to OpenShift with an account that has permission to install Fuse Online. For example:
oc login -u developer -p developer
Switch to an OpenShift project in which Fuse Online is running. You are enabling discovery for only this project. For example:
oc project my-fuse-online-project
Edit the
syndesis
custom resource:Invoke the following command, which typically opens the resource in an editor:
oc edit syndesis
Edit the resource by setting
managementUrlFor3scale
to the URL for your 3scale user interface. The result looks like this:spec: components: server: features: managementUrlFor3scale: https://3scale-admin.apps.mycluster.com
- Save the resource.
Optional. To confirm that discovery is turned on for the project that you switched to, invoke the following command:
oc describe dc/syndesis-server
When discovery is turned on, the output from this command shows that the
OPENSHIFT_MANAGEMENT_URL_FOR3SCALE
environment variable is set to the URL that you specified in the custom resource.
Results
This change to the syndesis
custom resource triggers syndesis-operator
, which is responsible for installing Fuse Online, to redeploy syndesis-server
. In the OpenShift project that you switched to, the new default behavior is that APIs are exposed for discovery in 3scale.
Do not edit the syndesis-server DeploymentConfig
object to set the OPENSHIFT_MANAGEMENT_URL_FOR3SCALE
environment variable. This does not work because syndesis-operator
reverts your change. The syndesis-operator
ensures that Fuse Online is deployed only and always according to the syndesis
custom resource.
2.2. Configuring OpenShift to enable Service Discovery
As a 3scale administrator, you can 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 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.
2.2.1. Configuring Service Discovery with an OpenShift OAuth server
As a 3scale system administrator, you can allow users to individually authenticate and authorize 3scale to discover APIs by using OpenShift built-in OAuth server.
Prerequisites
- You must deploy 3scale 1.1 to an OpenShift cluster (version 3.11 or later).
- To deploy 3scale to OpenShift, you need to use 3scale-amp-openshift-templates.
- 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 note
For more information about OpenShift OAuth tokens, Configuring the internal OAuth server.
2.2.2. Configuring Service Discovery with an RH-SSO server (Keycloak)
As a system administrator, you can 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 RH-SSO deployment as the authorization gateway for OpenShift, you can refer to this workflow.
Prerequisites
- You must deploy 3scale 1.1 to an OpenShift cluster (version 3.11 or later).
- To deploy 3scale to OpenShift, you need to use 3scale-amp-openshift-templates.
- 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 note:
- 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.
2.2.3. 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 1.1 to an OpenShift cluster (version 3.11 or later).
- To deploy 3scale to OpenShift, you need to use 3scale-amp-openshift-templates.
- 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.
2.3. 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 Section 4.1, “About Service Discovery”.
- 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 Section 4.1, “About Service Discovery”.
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.
Next steps
See the Red Hat 3scale API Management documentation for information about managing the API.