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

  1. Log in to OpenShift with an account that has permission to install Fuse Online. For example:

    oc login -u developer -p developer

  2. 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

  3. Edit the syndesis custom resource:

    1. Invoke the following command, which typically opens the resource in an editor:

      oc edit syndesis

    2. 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
    3. Save the resource.
  4. 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

  1. 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
  2. Open the 3scale Service Discovery settings file:

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. 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>'
  4. 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>
  5. After modifying configmap, you must redeploy the system-app and system-sidekiq pods to apply the changes.

    oc rollout latest dc/system-app
    oc rollout latest dc/system-sidekiq
  6. 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

  1. 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.

  2. Edit 3scale Service Discovery settings.

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. 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>'
  4. 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>
  5. After modifying configmap, you must redeploy the system-app and system-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

  1. Verify that the 3scale project is the current project.

       $ oc project <3scale-project>
  2. Open the 3scale Service Discovery settings in an editor.

       $ oc edit configmap system
  3. 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
  4. 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.

      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 to true.
  • 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

  1. Click the Authenticate to enable this option link.
  2. Log in to OpenShift using the namespace administrator credentials.
  3. 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.