此内容没有您所选择的语言版本。
Chapter 4. Discover an API service in 3scale
Red Hat 3scale API Management is an offering from Red Hat that enables you to regulate access to API services on the public Internet. The functionality of 3scale includes the ability to enforce service-level agreements (SLAs), manage API versions, provide security and authentication services and more. Fuse supports a service discovery feature for 3scale, which makes it easy to discover Fuse services from the 3scale Admin Portal UI. Using service discovery, you can scan for Fuse applications running in the same OpenShift cluster and automatically import the associated API definitions into 3scale.
Prerequisites
- A Fuse application that provides an API service is deployed and running in OpenShift.
The Fuse application is annotated with the requisite annotations to make it discoverable by 3scale.
NoteFuse projects that are generated by Apicurito are pre-configured to automatically provide the requisite annotations.
For Fuse projects that are not generated by Apicurito, you must configure your project as described in Section 4.1, “Adding annotations for Fuse projects that are not generated by Apicurito”.
- The 3scale API Management system is deployed on the same OpenShift cluster as the API service that is to be discovered.
For details of the procedure to discover an API service in 3scale, see the service discovery section of the Red Hat 3scale API Management Admin Portal Guide.
Additional resources
4.1. Adding annotations for Fuse projects that are not generated by Apicurito
In order for 3scale to discover an API service, the Fuse application that provides the API service must include Kubernetes Service Annotations that make it discoverable. These annotations are provided by the Fabric8 service discovery enricher which is part of the Fabric8 Maven Plugin.
For Apache Camel Rest DSL projects, the Fabric8 Maven Plugin runs the Fabric8 service discovery enricher by default.
Fuse projects that are generated by Apicurito are pre-configured to automatically provide the required annotations.
Procedure
For a Fuse Rest DSL project that is not generated by Apicurito, configure the project as follows:
Edit the Fuse project’s
pom.xml
file to include thefabric8-maven-plugin
dependency, as shown in this example:<plugin> <groupId>org.jboss.redhat-fuse</groupId> <artifactId>fabric8-maven-plugin</artifactId> <version>${fuse.version}</version> <executions> <execution> <goals> <goal>resource</goal> <goal>build</goal> </goals> </execution> </executions> </plugin>
The Fabric8 Maven Plugin runs the Fabric8 service discovery enricher if certain project-level conditions are met (for example, the project must be a Camel Rest DSL project). You do not need to specify the Fabric8 service discovery enricher as a dependency in the
pom.xml
file, unless you want to customize the enricher’s behavior (as described in Section 4.2, “Customizing the API service annotation values”.)In the Fuse Rest DSL project’s
camel-context.xml
file, specify the following attributes in therestConfiguration
element:-
scheme
: The scheme part of the URL where the service is hosted. You can specify “http” or “https”. -
contextPath
: The path part of the URL where the API service is hosted. apiContextPath
: The path to the location where the API service description document is hosted. You can specify either a relative path if the document is self-hosted or a full URL if the document is hosted externally.The following excerpt from an example
camel-context.xml
file shows annotation attribute values in therestConfiguration
element:<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd"> <camelContext xmlns="http://camel.apache.org/schema/spring"> <restConfiguration component="servlet" scheme="https" contextPath="myapi" apiContextPath="myapi/openapi.json"/> ...
-
The enricher uses the information provided by these restConfiguration
element attribute values to create values for the discovery.3scale.net/scheme
, discovery.3scale.net/path
, and the discovery.3scale.net/description-path
annotations, thereby making the project’s deployed OpenShift service discoverable by 3scale as described in the Making a service discoverable section of the Red Hat 3scale API Management Admin Portal Guide guide.
The enricher adds the following label and annotations to make the service discoverable by 3scale:
-
The
discovery.3scale.net
label: By default, the enricher sets this value 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. The enricher sets this value to "v1" by default. -
discovery.3scale.net/scheme
: The scheme part of the URL where the service is hosted. The enricher uses the default "http" unless you override it in therestConfiguration
element’sscheme
attribute. The other possible value is "https". -
discovery.3scale.net/path
: The path part of the URL where the service is hosted. This annotation is omitted when the path is at root, "/". The enricher gets this value from therestConfiguration
element’spath
attribute. -
discovery.3scale.net/port
: The port of the service. The enricher obtains this value from the Kubernetes service definition, which contains the the port numbers of the services it exposes. If the Kubernetes service definition exposes more than one service, the enricher uses the first port listed. -
discovery.3scale.net/description-path
: (optional) The path to the OpenAPI service description document. The enricher gets this value from therestConfiguration
element’scontextPath
attribute.
-
You can customize the behavior of the Fabric8 service discovery enricher, as described in Section 4.2, “Customizing the API service annotation values”.
4.2. Customizing the API service annotation values
The Maven Fabric8 Plugin runs the Fabric8 service discovery enricher by default. The enricher adds annotations to the Fuse Rest DSL project’s API service so that the API service is discoverable by 3scale, as described in Using Service Discovery in the Red Hat 3scale API Management Admin Portal Guide guide.
The enricher uses default values for some annotations and obtains values for other annotations from the project’s camel-context.xml
file.
You can override the default values and the values defined in the camel-context.xml
file by defining values in the Fuse project pom.xml
file or in a service.yml
file. (If you define values in both files, the enricher uses the values from the service.yml
file.) See Section 4.3, “Fabric8 service discovery enricher elements” for a description of the elements that you can specify for the Fabric8 service discovery enricher.
Procedure
To specify annotation values in the Fuse project pom.xml
file:
-
Open your Fuse project’s
pom.xml
file in an editor of your choice. Locate the
fabric8-maven-plugin
dependency, as shown in this example:<plugin> <groupId>org.jboss.redhat-fuse</groupId> <artifactId>fabric8-maven-plugin</artifactId> <version>${fuse.version}</version> <executions> <execution> <goals> <goal>resource</goal> <goal>build</goal> </goals> </execution> </executions> </plugin>
Add the Fabric8 service discovery enricher as a dependency to the Fabric8-Maven plugin as shown in the following example.
<plugin> <groupId>org.jboss.redhat-fuse</groupId> <artifactId>fabric8-maven-plugin</artifactId> <version>${fuse.version}</version> <executions> <execution> <goals> <goal>resource</goal> <goal>build</goal> </goals> </execution> </executions> <dependencies> <dependency> <groupId>io.acme</groupId> <artifactId>myenricher</artifactId> <version>1.0</version> <configuration> <enricher> <config> <f8-service-discovery> <scheme>https</scheme> <path>/api</path> <descriptionPath>/api/openapi.json</descriptionPath> </f8-service-discovery> </config> </enricher> </configuration> </dependency> </dependencies> </plugin>
- Save your changes.
Alternatively, you can use a src/main/fabric8/service.yml
fragment to override the annotation values, as shown in the following example:
kind: Service name: metadata: labels: discovery.3scale.net/discoverable : "true" annotations: discovery.3scale.net/discovery-version : "v1" discovery.3scale.net/scheme : "https" discovery.3scale.net/path : "/api" discovery.3scale.net/port : "443" discovery.3scale.net/description-path : "/api/openapi.json" spec: type: LoadBalancer
4.3. Fabric8 service discovery enricher elements
The following table describes the elements that you can specify for the Fabric8 service discovery enricher, if you want to override the default values and the values defined in the camel-context.xml
file.
You can define these values in the Fuse Rest DSL project’s pom.xml
file or in a src/main/fabric8/service.yml
file. (If you define values in both files, the enricher uses the values from the service.yml
file.) See Section 4.2, “Customizing the API service annotation values” for examples.
Element | Description | Default |
---|---|---|
|
The path to the spring configuration directory that contains the |
The |
| The scheme part of the URL where the service is hosted. You can specify “http” or “https”. | http |
| The path part of the URL where the API service is hosted. | |
| The port part of the URL where the API service is hosted. | 80 |
| The path to a location where the API service description document is hosted. You can specify either a relative path if the document is self-hosted or a full URL if the document is hosted externally. | |
| The version of the 3scale discovery implementation. | v1 |
|
The element that sets the If set to true, 3scale will try to discover this service. If set to false, 3scale will not try to discover this service. You can use this element as a switch, to temporary turn off 3scale discovery integration by setting it to "false". | If you do not specify a value, the enricher tries to auto-detect whether it can make the service discoverable. If the enricher determines that it cannot make the service discoverable, 3scale will not try to discover this service. |