diff --git a/docs/snapshot/main/search-index.json b/docs/snapshot/main/search-index.json index 7b009f26..6a5a01bc 100644 --- a/docs/snapshot/main/search-index.json +++ b/docs/snapshot/main/search-index.json @@ -2855,11 +2855,6 @@ "text": " The Coherence Operator supports running images that contain Spring Boot applications. Exactly how easy this is depends on how the image has been built. When the operator runs an image it overrides the default image entrypoint and uses its own launcher. This allows the operator to properly configure various Coherence properties that the launcher then uses to build the command line to actually run your application. With some types of image this is not a straight forward Java command line so the Operator requires a bit more information adding to the Coherence deployment yaml. Using JIB Images The simplest way to build an application image to run with the Coherence Operator (including Spring Boot applications) is to use the JIB tool. JIB images will work out of the box with the operator, even for a Spring Boot application, as described in Building Applications and Deploying Applications . If you have used the Spring Maven or Gradle plugins to build the application into a fat jar, but you then build the image using the JIB plugin then JIB will detect the fat jar and package the image in an exploded form that will run out of the box with the operator. Using an Exploded Spring Boot Image Another way to build a Spring Boot image is to explode the Spring Boot jar into a directory structure in the image. For example, if a Spring Boot jar has been exploded into a directory called /spring , the image contents might look like the diagram below; where you can see the /spring directory contains the Spring Boot application. ├── bin ├── boot ├── dev ├─⊕ etc ├─⊕ home ├─⊕ lib ├─⊕ lib64 ├── proc ├── root ├── run ├── sbin ├── spring │ ├── BOOT-INF │ │ ├─⊕ classes │ │ ├── classpath.idx │ │ └─⊕ lib │ ├── META-INF │ │ ├── MANIFEST.MF │ │ └─⊕ maven │ └── org │ └── springframework │ └─⊕ boot ├── sys ├── tmp ├─⊕ usr └─⊕ var This type of image can be run by the Coherence Operator by specifying an application type of spring in the spec.application.type field and by setting the working directory to the exploded directory, for example: apiVersion: coherence.oracle.com/v1 kind: Coherence metadata: name: test spec: image: my-spring-app:1.0.0 application: type: spring workingDir: /spring The type field set to spring tells the Operator that this is a Spring Boot application. The working directory has been set to the directory containing the exploded Spring Boot application. When the Operator starts the application it will then run a command equivalent to: cd /spring && java org.springframework.boot.loader.PropertiesLauncher Using a Spring Boot Fat Jar It is not recommended to build images containing fat jars for various reasons which can easily be found on the internet. If you feel that you must build your application as a Spring Boot fat jar then this can still work with the Coherence Operator. The Java command line to run a Spring Boot fat jar needs to be something like java -jar my-app.jar where my-app.jar is the fat jar. This means that the Operator’s launcher needs to know the location of the fat jar in the image, so this must be provided in the Coherence deployment yaml. For example, suppose that an application has been built into a fat jar names catalogue-1.0.0.jar which is in the /app/libs directory in the image, so the full path to the jar is /app/libs/catalogue-1.0.0.jar . This needs to be set in the spec.applicaton.springBootFatJar field of the Coherence yaml. The spec.application.type field also needs to be set to spring so that the Operator knows that this is a Spring Boot application apiVersion: coherence.oracle.com/v1 kind: Coherence metadata: name: test spec: image: catalogue:1.0.0 application: type: spring springBootFatJar: /app/libs/catalogue-1.0.0.jar The type field set to spring tells the Operator that this is a Spring Boot application. The location of the Spring Boot jar has been set. When the Operator starts the application it will then run a command equivalent to: java -cp /app/libs/catalogue-1.0.0.jar org.springframework.boot.loader.PropertiesLauncher The Operator does not run the fat jar using the java -jar command because it needs to add various other JVM arguments and append to the classpath, so it has to run the org.springframework.boot.loader.PropertiesLauncher class as opposed to the org.springframework.boot.loader.JarLauncher that java -jar would run. Using Could Native Buildpacks If the Spring Boot Maven or Gradle plugin has been used to produce an image using Cloud Native Buildpacks these images can work with the Coherence Operator. Warning Due to limitation on the way that arguments can be passed to the JVM when using Buildpacks images the Coherence operator will only work with images containing a JVM greater than Java 11. Although the Buildpacks launcher will honour the JAVA_OPTS or JAVA_TOOL_OPTIONS environment variables there appear to be size limitations for the values of these variables that make it impractical for the Operator to use them. The Operator therefore creates a JVM arguments file to pass the arguments to the JVM. At the time of writing these docs, Java 8 (which is the default version of Java used by the Spring Boot plugin) does not support the use of argument files for the JVM. It is simple to configure the version of the JVM used by the Spring Boot plugin, for example in Maven: <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <version>2.3.4.RELEASE</version> <configuration> <image> <env> <BP_JVM_VERSION>11.*</BP_JVM_VERSION> </env> </image> </configuration> </plugin> When creating a Coherence deployment for a Spring Boot Buildpacks image The application type must be set to spring . The Operator’s launcher will automatically detect that the image is a Buildpacks image and launch the application using the Buildpacks launcher. apiVersion: coherence.oracle.com/v1 kind: Coherence metadata: name: test spec: image: catalogue:1.0.0 application: type: spring The application type has been set to spring so that the operator knows that this is a Spring Boot application, and the fact that the image is a Buildpacks image will be auto-discovered. When the Operator starts the application it will then run the buildpacks launcher with a command equivalent to this: /cnb/lifecycle/launcher java @jvm-args-file org.springframework.boot.loader.PropertiesLauncher Buildpacks Detection If for some reason buildpacks auto-detection does not work properly the Coherence CRD contains a filed to force buildpacks to be enabled or disabled. The boolean field spec.application.cloudNativeBuildPack.enabled can be set to true to enable buildpacks or false to disable buildpack. apiVersion: coherence.oracle.com/v1 kind: Coherence metadata: name: test spec: image: catalogue:1.0.0 application: type: spring cloudNativeBuildPack: enabled: true The application type has been set to spring so that the operator knows that this is a Spring Boot application The cloudNativeBuildPack.enabled field has been set to true to force the Operator to use the Buildpacks launcher. Specify the Buildpacks Launcher A Cloud Native Buildpacks image uses a launcher mechanism to run the executable(s) in the image. The Coherence Operator launcher will configure the application and then invoke the same buildpacks launcher. The Coherence Operator assumes that the buildpacks launcher is in the image in the location /cnb/lifecycle/launcher . If a buildpacks image has been built with the launcher in a different location then the Coherence CRD contains a field to set the new location. The spec.application.cloudNativeBuildPack.enabled field. apiVersion: coherence.oracle.com/v1 kind: Coherence metadata: name: test spec: image: catalogue:1.0.0 application: type: spring cloudNativeBuildPack: launcher: /buildpack/launcher The application type has been set to spring so that the operator knows that this is a Spring Boot application The buildpacks launcher that the Operator will invoke is located at /buildpack/launcher . Buildpack JVM Arguments A typical Spring Boot buildpack launcher will attempt to configure options such as heap size based on the container resource limits configured, so this must be taken into account if using any of the memory options available in the Coherence CRD as there may be conflicting configurations. ", "title": "Spring Boot Applications" }, - { - "location": "/docs/installation/08_networking", - "text": " In order for Coherence clusters to form correctly, the conntrack library must be installed. Most Kubernetes distributions will do this for you. If you have issues with clusters not forming, then you should check that conntrack is installed using this command (or equivalent): rpm -qa | grep conntrack You should see output similar to that shown below. If you do not, then you should install conntrack using your operating system tools. libnetfilter_conntrack-1.0.6-1.el7_3.x86_64 conntrack-tools-1.4.4-4.el7.x86_64 ", - "title": "Operating System Library Requirements" - }, { "location": "/docs/installation/08_networking", "text": " The recommended way to make iptables updates permanent across reboots is to create a systemd service that applies the necessary updates during the startup process. Here is an example; you may need to adjust this to suit your own environment: Create a systemd service: echo 'Set up systemd service to fix iptables nat chain at each reboot (so Coherence will work)...' mkdir -p /etc/systemd/system/ cat > /etc/systemd/system/fix-iptables.service << EOF [Unit] Description=Fix iptables After=firewalld.service After=docker.service [Service] ExecStart=/sbin/fix-iptables.sh [Install] WantedBy=multi-user.target EOF Create the script to update iptables : cat > /sbin/fix-iptables.sh << EOF #!/bin/bash echo 'Fixing iptables rules for Coherence issue...' TIMES=$((`iptables -t nat -v -L POST_public_allow -n --line-number | wc -l` - 2)) COUNTER=1 while [ $COUNTER -le $TIMES ]; do iptables -t nat -v -D POST_public_allow 1 ((COUNTER++)) done EOF Start the service (or just reboot): echo 'Start the systemd service to fix iptables nat chain...' systemctl enable --now fix-iptables ", @@ -2872,7 +2867,7 @@ }, { "location": "/docs/installation/08_networking", - "text": " Operating System Library Requirements In order for Coherence clusters to form correctly, the conntrack library must be installed. Most Kubernetes distributions will do this for you. If you have issues with clusters not forming, then you should check that conntrack is installed using this command (or equivalent): rpm -qa | grep conntrack You should see output similar to that shown below. If you do not, then you should install conntrack using your operating system tools. libnetfilter_conntrack-1.0.6-1.el7_3.x86_64 conntrack-tools-1.4.4-4.el7.x86_64 Firewall (iptables) Requirements Some Kubernetes distributions create iptables rules that block some types of traffic that Coherence requires to form clusters. If you are not able to form clusters, then you can check for this issue using the following command: iptables -t nat -v -L POST_public_allow -n If you see output similar to the example below: Chain POST_public_allow (1 references) pkts bytes target prot opt in out source destination 164K 11M MASQUERADE all -- * !lo 0.0.0.0/0 0.0.0.0/0 0 0 MASQUERADE all -- * !lo 0.0.0.0/0 0.0.0.0/0 For example, if you see any entries in this chain, then you need to remove them. You can remove the entries using this command: iptables -t nat -v -D POST_public_allow 1 Note that you will need to run that command for each line. So in the example above, you would need to run it twice. After you are done, you can run the previous command again and verify that the output is now an empty list. After making this change, restart your domains and the Coherence cluster should now form correctly. Make iptables Updates Permanent Across Reboots The recommended way to make iptables updates permanent across reboots is to create a systemd service that applies the necessary updates during the startup process. Here is an example; you may need to adjust this to suit your own environment: Create a systemd service: echo 'Set up systemd service to fix iptables nat chain at each reboot (so Coherence will work)...' mkdir -p /etc/systemd/system/ cat > /etc/systemd/system/fix-iptables.service << EOF [Unit] Description=Fix iptables After=firewalld.service After=docker.service [Service] ExecStart=/sbin/fix-iptables.sh [Install] WantedBy=multi-user.target EOF Create the script to update iptables : cat > /sbin/fix-iptables.sh << EOF #!/bin/bash echo 'Fixing iptables rules for Coherence issue...' TIMES=$((`iptables -t nat -v -L POST_public_allow -n --line-number | wc -l` - 2)) COUNTER=1 while [ $COUNTER -le $TIMES ]; do iptables -t nat -v -D POST_public_allow 1 ((COUNTER++)) done EOF Start the service (or just reboot): echo 'Start the systemd service to fix iptables nat chain...' systemctl enable --now fix-iptables ", + "text": " Firewall (iptables) Requirements Some Kubernetes distributions create iptables rules that block some types of traffic that Coherence requires to form clusters. If you are not able to form clusters, then you can check for this issue using the following command: iptables -t nat -v -L POST_public_allow -n If you see output similar to the example below: Chain POST_public_allow (1 references) pkts bytes target prot opt in out source destination 164K 11M MASQUERADE all -- * !lo 0.0.0.0/0 0.0.0.0/0 0 0 MASQUERADE all -- * !lo 0.0.0.0/0 0.0.0.0/0 For example, if you see any entries in this chain, then you need to remove them. You can remove the entries using this command: iptables -t nat -v -D POST_public_allow 1 Note that you will need to run that command for each line. So in the example above, you would need to run it twice. After you are done, you can run the previous command again and verify that the output is now an empty list. After making this change, restart your domains and the Coherence cluster should now form correctly. Make iptables Updates Permanent Across Reboots The recommended way to make iptables updates permanent across reboots is to create a systemd service that applies the necessary updates during the startup process. Here is an example; you may need to adjust this to suit your own environment: Create a systemd service: echo 'Set up systemd service to fix iptables nat chain at each reboot (so Coherence will work)...' mkdir -p /etc/systemd/system/ cat > /etc/systemd/system/fix-iptables.service << EOF [Unit] Description=Fix iptables After=firewalld.service After=docker.service [Service] ExecStart=/sbin/fix-iptables.sh [Install] WantedBy=multi-user.target EOF Create the script to update iptables : cat > /sbin/fix-iptables.sh << EOF #!/bin/bash echo 'Fixing iptables rules for Coherence issue...' TIMES=$((`iptables -t nat -v -L POST_public_allow -n --line-number | wc -l` - 2)) COUNTER=1 while [ $COUNTER -le $TIMES ]; do iptables -t nat -v -D POST_public_allow 1 ((COUNTER++)) done EOF Start the service (or just reboot): echo 'Start the systemd service to fix iptables nat chain...' systemctl enable --now fix-iptables ", "title": "O/S Networking Configuration" }, { diff --git a/docs/snapshot/pages/docs/installation/08_networking.js b/docs/snapshot/pages/docs/installation/08_networking.js index e33c736d..c59c12d9 100644 --- a/docs/snapshot/pages/docs/installation/08_networking.js +++ b/docs/snapshot/pages/docs/installation/08_networking.js @@ -3,29 +3,6 @@

O/S Networking Configuration

-

Operating System Library Requirements

-
-

In order for Coherence clusters to form correctly, the conntrack library -must be installed. Most Kubernetes distributions will do this for you. -If you have issues with clusters not forming, then you should check that -conntrack is installed using this command (or equivalent):

- -rpm -qa | grep conntrack - -

You should see output similar to that shown below. If you do not, then you -should install conntrack using your operating system tools.

- -libnetfilter_conntrack-1.0.6-1.el7_3.x86_64 -conntrack-tools-1.4.4-4.el7.x86_64 - -
-

Firewall (iptables) Requirements

Some Kubernetes distributions create iptables rules that block some