Merge pull request #74 from oracle/COH-29462

Coh-29462 Update Spring Coherence Sock Shop documentation related to Kubernetes deployment

README.md

@@ -163,14 +163,14 @@ If you wish to scale the back-end you can issue the following command
 Scale only the orders microservice:
 
 ```bash
-$ kubectl --namespace sockshop scale coherence orders --replicas=3
+$ kubectl --namespace sockshop scale coherence/orders --replicas=3
 ```
 
 Or alternatively scale all the microservices:
 
 ```bash
 $ for name in carts catalog orders payment shipping users
-    do kubectl --namespace sockshop scale coherence $name --replicas=3
+    do kubectl --namespace sockshop scale coherence/$name --replicas=3
 done
 ```
 

carts/pom.xml

@@ -78,6 +78,11 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-aop</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.opentracing.contrib</groupId>
+            <artifactId>opentracing-spring-jaeger-cloud-starter</artifactId>
+            <version>${version.lib.opentracing-spring-jaeger}</version>
+        </dependency>
 
         <!-- test dependencies -->
         <dependency>

carts/src/main/resources/application.yaml

@@ -31,3 +31,6 @@ logging:
     "Coherence": info
     org.springframework.web: info
     com.oracle.coherence.spring: info
+coherence:
+  tracing:
+    ratio: -1

catalog/pom.xml

@@ -77,6 +77,11 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-aop</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.opentracing.contrib</groupId>
+            <artifactId>opentracing-spring-jaeger-cloud-starter</artifactId>
+            <version>${version.lib.opentracing-spring-jaeger}</version>
+        </dependency>
 
         <!-- test dependencies -->
         <dependency>

catalog/src/main/resources/application.yaml

@@ -31,3 +31,6 @@ logging:
     "Coherence": info
     org.springframework.web: info
     com.oracle.coherence.spring: info
+coherence:
+  tracing:
+    ratio: -1

doc/complete-application-deployment.md

@@ -34,6 +34,10 @@ Prometheus can then be accessed as documented in the
 If installing Prometheus into a RBAC enabled k8s cluster you may need to create the required RBAC resources
 as described in the [Prometheus RBAC](https://prometheus-operator.dev/docs/operator/rbac/) documentation.
 
+In some environments, installation can fail with the error message "path /sys is not shared or slave mount".
+For this demo, if necessary, it will be sufficient to comment out `mountPropagation: HostToContainer` in the
+`manifests/nodeExporter-daemonset.yaml` file.
+
 **IMPORTANT**
 If you installed the Sock Shop back-end into K8s before you installed Prometheus Operator, you must
 run the following to delete and re-add the deployments for Prometheus to pick up the Pods. This is because the Coherence Operator will not have been able to create Prometheus `ServiceMonitor` resources before Prometheus was installed.
@@ -60,6 +64,16 @@ of the Grafana documentation.
 > Note: This is assuming you have deployed the back-ends via the instructions in
 > the previous section.
 
+> Note: This step can be skipped if one wants to access application and Grafana/Prometheus/Jaeger services
+> just by using `localhost`.
+> In that case add port forwarding setup for each service:
+>```bash
+> $ kubectl --namespace sockshop port-forward svc/front-end 8079:80
+> $ kubectl --namespace monitoring port-forward svc/prometheus-k8s 9090
+> $ kubectl --namespace monitoring port-forward svc/alertmanager-main 9093
+> $ kubectl --namespace monitoring port-forward svc/grafana 3000
+>```
+
 1. Create the Load Balancer
 
     ```bash
@@ -139,12 +153,17 @@ of the Grafana documentation.
 
 5. Access the application
 
-   Access the application via the endpoint http://coherence.sockshop.mycompany.com/
+   Access the application via the endpoint http://coherence.sockshop.mycompany.com/ (or http://localhost:8079)
 
 ### Install the Jaeger Operator
 
 1. Install the Jaeger Operator
 
+   The Jaeger Operator requires `cert-manager` to be installed. If it's missing, `cert-manager`
+   can be installed with the following command:
+   ```bash
+   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.2/cert-manager.yaml
+   ```
 
    If you have not done, yet, create the `monitoring` namespace:
 
@@ -165,6 +184,21 @@ of the Grafana documentation.
     kubectl create -f k8s/optional/jaeger.yaml --namespace sockshop
     ```
 
+   > Note: To access Jaeger UI over localhost add port forwarding setup:
+   > ```bash
+   > $ kubectl --namespace sockshop port-forward svc/jaeger-query 16686
+   >```
+
+   > Note: to view not just Sockshop traces but also Coherence traces
+   > edit `application.yaml` and set `coherence.tracing.ratio` to 1.
+   >```yaml
+   > coherence:
+   >   tracing:
+   >     ratio: 1
+   >```
+   > Due to known issues between Coherence and Spring, Coherence traces will not
+   > be properly associated with the Spring traces.
+
 3. Enable Jaeger tracing in the `app.yaml` files and rebuild and redeploy services
 
     Set `management.tracing.enabled` to `true`, e.g.:

k8s/coherence/carts/app.yaml

@@ -22,6 +22,10 @@ spec:
       value: "1"
     - name: COHERENCE_SERVICE_NAME
       value: "Carts"
+    - name: JAEGER_SERVICE_NAME
+      value: carts
+    - name: JAEGER_ENDPOINT
+      value: "http://jaeger-collector:14268/api/traces"
   application:
     main: com.oracle.coherence.examples.sockshop.spring.carts.CartsApp
     args:

k8s/coherence/catalog/app.yaml

@@ -22,6 +22,10 @@ spec:
       value: "1"
     - name: COHERENCE_SERVICE_NAME
       value: "Catalog"
+    - name: JAEGER_SERVICE_NAME
+      value: catalog
+    - name: JAEGER_ENDPOINT
+      value: "http://jaeger-collector:14268/api/traces"
   application:
     main: com.oracle.coherence.examples.sockshop.spring.catalog.CatalogApp
     args:

k8s/coherence/orders/app.yaml

@@ -22,6 +22,10 @@ spec:
       value: "1"
     - name: COHERENCE_SERVICE_NAME
       value: "Orders"
+    - name: JAEGER_SERVICE_NAME
+      value: orders
+    - name: JAEGER_ENDPOINT
+      value: "http://jaeger-collector:14268/api/traces"
   application:
     main: com.oracle.coherence.examples.sockshop.spring.orders.OrdersApp
     args:

k8s/coherence/payment/app.yaml

@@ -22,6 +22,10 @@ spec:
       value: "1"
     - name: COHERENCE_SERVICE_NAME
       value: "Payment"
+    - name: JAEGER_SERVICE_NAME
+      value: payment
+    - name: JAEGER_ENDPOINT
+      value: "http://jaeger-collector:14268/api/traces"
   application:
     main: com.oracle.coherence.examples.sockshop.spring.payment.PaymentApp
     args:

k8s/coherence/shipping/app.yaml

@@ -22,6 +22,10 @@ spec:
       value: "1"
     - name: COHERENCE_SERVICE_NAME
       value: "Shipping"
+    - name: JAEGER_SERVICE_NAME
+      value: shipping
+    - name: JAEGER_ENDPOINT
+      value: "http://jaeger-collector:14268/api/traces"
   application:
     main: com.oracle.coherence.examples.sockshop.spring.shipping.ShippingApp
     args:

k8s/coherence/users/app.yaml

@@ -23,6 +23,10 @@ spec:
       value: "1"
     - name: COHERENCE_SERVICE_NAME
       value: "Users"
+    - name: JAEGER_SERVICE_NAME
+      value: users
+    - name: JAEGER_ENDPOINT
+      value: "http://jaeger-collector:14268/api/traces"
   application:
     main: com.oracle.coherence.examples.sockshop.spring.users.UsersApp
     args:

orders/pom.xml

@@ -86,6 +86,11 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-aop</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.opentracing.contrib</groupId>
+            <artifactId>opentracing-spring-jaeger-cloud-starter</artifactId>
+            <version>${version.lib.opentracing-spring-jaeger}</version>
+        </dependency>
 
         <!-- test dependencies -->
         <dependency>

orders/src/main/resources/application.yaml

@@ -36,4 +36,7 @@ logging:
     org.apache.http: debug
 feign:
   httpclient:
-    enabled: true
+    enabled: true
+coherence:
+  tracing:
+    ratio: -1

payment/pom.xml

@@ -77,6 +77,11 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-aop</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.opentracing.contrib</groupId>
+            <artifactId>opentracing-spring-jaeger-cloud-starter</artifactId>
+            <version>${version.lib.opentracing-spring-jaeger}</version>
+        </dependency>
 
         <dependency>
             <groupId>org.apache.httpcomponents.client5</groupId>

payment/src/main/resources/application.yaml

@@ -32,3 +32,6 @@ logging:
     org.springframework.web: info
     com.oracle.coherence.spring: info
     org.apache.http: debug
+coherence:
+  tracing:
+    ratio: -1

pom.xml

@@ -40,6 +40,7 @@
         <version.lib.spring-boot>3.2.3</version.lib.spring-boot>
         <version.lib.spring-cloud>2023.0.0</version.lib.spring-cloud>
         <version.lib.springdoc-openapi>2.4.0</version.lib.springdoc-openapi>
+        <version.lib.opentracing-spring-jaeger>3.3.1</version.lib.opentracing-spring-jaeger>
 
         <version.plugin.dependency-check-maven>9.0.10</version.plugin.dependency-check-maven>
         <version.plugin.jib>3.4.1</version.plugin.jib>

shipping/pom.xml

@@ -77,6 +77,11 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-aop</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.opentracing.contrib</groupId>
+            <artifactId>opentracing-spring-jaeger-cloud-starter</artifactId>
+            <version>${version.lib.opentracing-spring-jaeger}</version>
+        </dependency>
 
         <!-- test dependencies -->
         <dependency>

shipping/src/main/resources/application.yaml

@@ -32,4 +32,6 @@ logging:
     org.springframework.web: info
     com.oracle.coherence.spring: info
     org.apache.http: info # set to debug to see logging of http payloads
-
+coherence:
+  tracing:
+    ratio: -1

users/pom.xml

@@ -99,6 +99,11 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-aop</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>io.opentracing.contrib</groupId>
+			<artifactId>opentracing-spring-jaeger-cloud-starter</artifactId>
+			<version>${version.lib.opentracing-spring-jaeger}</version>
+		</dependency>
 
 		<!-- -->
 		<dependency>

users/src/main/resources/application.yaml

@@ -34,3 +34,6 @@ logging:
     org.springframework.security: info
     org.springframework.web: info
     com.oracle.coherence.spring: info
+coherence:
+  tracing:
+    ratio: -1