Skip to content

Commit 3afae72

Browse files
lsholsho
authored
added Istio documentation (#479)
* added Istio documentation * Incorporated review comments from Janathan Knight and Harvey Raja * Incorporated Jonathan Knight's reivew comments
1 parent 6ca323d commit 3afae72

File tree

2 files changed

+206
-0
lines changed

2 files changed

+206
-0
lines changed

‎docs/examples/800_istio.adoc‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
= Istio Support
2+
3+
== Overview
4+
5+
Coherence Operator 3.1.6 and later works with Istio 1.9.1 and later. You can run the operator and Coherence cluster managed by the operator with Istio. Coherence caches can be accessed from outside the Coherence cluster via Coherence*Extend, REST, and other supported Coherence clients. Using Coherence clusters with Istio does not require the Coherence Operator to also be using Istio (and vice-versa) . The Coherence Operator can manage Coherence clusters independent of whether those clusters are using Istio or not.
6+
7+
== Prometheus
8+
9+
The coherence metrics that record and track the health of Coherence cluster using Prometheus are also available in Istio environment and can be viewed through Granfana. However, Coherence cluster traffic is not visible by Istio.
10+
11+
== Traffic Visualization
12+
13+
Istio provides traffic management capabilities, including the ability to visualize traffic in Kiali. You do not need to change your applications to use this feature. The Istio proxy (envoy) sidecar that is injected into your pods provides it. The image below shows an example with traffic flow. In this example, you can see how the traffic flows in from the Istio gateway on the left, to the cluster services, and then to the individual cluster members. This example has storage members (example-cluster-storage), a proxy member running proxy service (example-cluster-proxy), and a REST member running http server (example-cluster-rest). However, Coherence cluster traffic between members is not visible.
14+
15+
image::../images/istioKiali.png[width=1024,height=512]
16+
17+
To learn more, see https://istio.io/latest/docs/concepts/traffic-management/[Istio traffic management].
18+
19+
== Limitations
20+
21+
The current support for Istio has the following limitation:
22+
23+
* Ports that are exposed in the ports list of pod spec are intercepted by Envoy proxies, thus break Coherence cluster traffic. As a result, Coherence cluster traffic must passthrough Envoy proxies.
24+
25+
== Prerequisites
26+
27+
The instructions assume that you are using a Kubernetes cluster with Istio installed and configured already.
28+
29+
== Using the Coherence operator with Istio
30+
31+
To use Coherence operator with Istio, you can deploy the operator into a namespace which has Istio automatic sidecar injection enabled. Before installing the operator, create the namespace in which you want to run the Coherence operator and label it for automatic injection.
32+
33+
34+
[source,bash]
35+
----
36+
kubectl create namespace coherence
37+
kubectl label namespace coherence istio-injection=enabled
38+
----
39+
40+
Istio Sidecar AutoInjection is done automatically when you label the coherence namespace with istio-injection.
41+
42+
After the namespace is labeled, you can install the operator using your preferred method in the Operator https://oracle.github.io/coherence-operator/docs/latest/#/installation/01_installation[Installation Guide].
43+
44+
After installed operator, use the following command to confirm the operator is running:
45+
46+
[source,bash]
47+
----
48+
kubectl get pods -n coherence
49+
50+
NAME READY STATUS RESTARTS AGE
51+
coherence-operator-controller-manager-7d76f9f475-q2vwv 2/2 Running 1 17h
52+
----
53+
54+
2/2 in READY column means that there are 2 containers running in the operator Pod. One is Coherence operator and the other is Envoy Proxy.
55+
56+
== Creating a Coherence cluster with Istio
57+
58+
You can configure your cluster to run with Istio automatic sidecar injection enabled. Before creating your cluster, create the namespace in which you want to run the cluster and label it for automatic injection.
59+
60+
[source,bash]
61+
----
62+
kubectl create namespace coherence-example
63+
kubectl label namespace coherence-example istio-injection=enabled
64+
----
65+
66+
There is no other requirements to run Coherence in Istio environment.
67+
68+
The following is an example that creates a cluster named example-cluster-storage:
69+
70+
example.yaml
71+
[source,bash]
72+
----
73+
# Example
74+
apiVersion: coherence.oracle.com/v1
75+
kind: Coherence
76+
metadata:
77+
name: example-cluster-storage
78+
----
79+
80+
[source,bash]
81+
----
82+
$ kubectl -n coherence-example apply -f example.yaml
83+
----
84+
85+
After you installed the Coherence cluster, run the following command to view the pods:
86+
87+
[source,bash]
88+
----
89+
$ kubectl -n coherence-example get pods
90+
91+
NAME READY STATUS RESTARTS AGE
92+
example-cluster-storage-0 2/2 Running 0 45m
93+
example-cluster-storage-1 2/2 Running 0 45m
94+
example-cluster-storage-2 2/2 Running 0 45m
95+
----
96+
97+
You can see that 3 members in the cluster are running with 3 pods. 2/2 in READY column means that there are 2 containers running in each Pod. One is Coherence member and the other is Envoy Proxy.
98+
99+
== TLS
100+
101+
Coherence cluster works with mTLS. Coherence client can also support TLS through Istio Gateway with TLS termination to connect to Coherence cluster running inside kubernetes. For example, you can apply the following Istio Gateway and Virtual Service in the namespace of the Coherence cluster. Before applying the gateway, create a secret for the credential from the certiticate and key (e.g. server.crt and server.key) to be used by the Gateway:
102+
103+
[source,bash]
104+
----
105+
kubectl create -n istio-system secret tls extend-credential --key=server.key --cert=server.crt
106+
----
107+
108+
Then, create a keystore (server.jks) to be used by the Coherence Extend client, e.g.:
109+
[source,bash]
110+
----
111+
openssl pkcs12 -export -in server.crt -inkey server.key -chain -CAfile ca.crt -name "server" -out server.p12
112+
113+
keytool -importkeystore -deststorepass password -destkeystore server.jks -srckeystore server.p12 -srcstoretype PKCS12
114+
----
115+
116+
117+
tlsGateway.yaml
118+
[source,bash]
119+
----
120+
apiVersion: networking.istio.io/v1alpha3
121+
kind: Gateway
122+
metadata:
123+
name: tlsgateway
124+
spec:
125+
selector:
126+
istio: ingressgateway # use istio default ingress gateway
127+
servers:
128+
- port:
129+
number: 8043
130+
name: tls
131+
protocol: TLS
132+
tls:
133+
mode: SIMPLE
134+
credentialName: "extend-credential" # the secret created in the previous step
135+
maxProtocolVersion: TLSV1_3
136+
hosts:
137+
- "*"
138+
----
139+
140+
tlsVS.yaml
141+
[source,bash]
142+
----
143+
apiVersion: networking.istio.io/v1alpha3
144+
kind: VirtualService
145+
metadata:
146+
name: extend
147+
spec:
148+
hosts:
149+
- "*"
150+
gateways:
151+
- tlsgateway
152+
tcp:
153+
- match:
154+
route:
155+
- destination:
156+
host: example-cluster-proxy-proxy # the service name used to expose the Extend proxy port
157+
----
158+
159+
Apply the Gateway and VirtualService:
160+
161+
[source,bash]
162+
----
163+
kubectl apply -f tlsGateway.yaml -n coherence-example
164+
kubectl apply -f tlsVS.yaml -n coherence-example
165+
----
166+
167+
Then configure a Coherence*Extend client to connect to the proxy server via TLS protocol. Below is an example of a <remoce-cache-scheme> configuration of an Extend client using TLS port 8043 configured in the Gateway and server.jks created earlier in the example.
168+
169+
client-cache-config.xml
170+
----
171+
...
172+
<remote-cache-scheme>
173+
<scheme-name>extend-direct</scheme-name>
174+
<service-name>ExtendTcpProxyService</service-name>
175+
<initiator-config>
176+
<tcp-initiator>
177+
<socket-provider>
178+
<ssl>
179+
<protocol>TLS</protocol>
180+
<trust-manager>
181+
<algorithm>PeerX509</algorithm>
182+
<key-store>
183+
<url>file:server.jks</url>
184+
<password>password</password>
185+
</key-store>
186+
</trust-manager>
187+
</ssl>
188+
</socket-provider>
189+
<remote-addresses>
190+
<socket-address>
191+
<address>$INGRESS_HOST</address>
192+
<port>8043</port>
193+
</socket-address>
194+
</remote-addresses>
195+
</tcp-initiator>
196+
</initiator-config>
197+
</remote-cache-scheme>
198+
...
199+
----
200+
201+
If you are using Docker for Desktop, $INGRESS_HOST is 127.0.0.1 and you can use the Kubectl port-forward to allow the Extend client to access the Coherence cluster from your localhost:
202+
203+
[source,bash]
204+
----
205+
kubectl port-forward -n istio-system <istio-ingressgateway-pod> 8043:8043
206+
----

‎docs/images/istioKiali.png‎

311 KB
Loading

0 commit comments

Comments
 (0)