diff --git a/.github/workflows/coherence-matrix.yaml b/.github/workflows/coherence-matrix.yaml index 9742a23d1..821fe09a0 100644 --- a/.github/workflows/coherence-matrix.yaml +++ b/.github/workflows/coherence-matrix.yaml @@ -29,7 +29,7 @@ jobs: fail-fast: false matrix: coherenceVersion: - - "21.06.1" + - "21.06.2" - "20.12.2" - "14.1.2-0-0-SNAPSHOT" - "14.1.1-0-7-SNAPSHOT" @@ -39,8 +39,8 @@ jobs: - "12.2.1-4-11-SNAPSHOT" - "12.2.1-3-15-SNAPSHOT" include: - - coherenceVersion: "21.06.1" - coherence-image: "ghcr.io/oracle/coherence-ce:21.06.1" + - coherenceVersion: "21.06.2" + coherence-image: "ghcr.io/oracle/coherence-ce:21.06.2" - coherenceVersion: "20.12.2" coherence-image: "ghcr.io/oracle/coherence-ce:20.12.2" - coherenceVersion: "14.1.2-0-0-SNAPSHOT" diff --git a/Makefile b/Makefile index 082962ae2..8e31d9081 100644 --- a/Makefile +++ b/Makefile @@ -32,8 +32,8 @@ COMPATIBLE_SELECTOR = control-plane=coherence # ---------------------------------------------------------------------------------------------------------------------- # The Coherence image to use for deployments that do not specify an image # ---------------------------------------------------------------------------------------------------------------------- -COHERENCE_VERSION ?= 21.06.1 -COHERENCE_IMAGE ?= oraclecoherence/coherence-ce:21.06.1 +COHERENCE_VERSION ?= 21.06.2 +COHERENCE_IMAGE ?= oraclecoherence/coherence-ce:21.06.2 # This is the Coherence image that will be used in tests. # Changing this variable will allow test builds to be run against different Coherence versions # without altering the default image name. @@ -606,8 +606,7 @@ copyright: ## Check copyright headers org.glassfish.copyright.Copyright -C hack/copyright.txt \ -X .adoc \ -X bin/ \ - -X build/_output/ \ - -X build/tools/ \ + -X build/ \ -X clientset/ \ -X dashboards/ \ -X /Dockerfile \ @@ -622,6 +621,10 @@ copyright: ## Check copyright headers -X hack/sdk/ \ -X go.mod \ -X go.sum \ + -X .gradle/ \ + -X gradle/ \ + -X gradlew \ + -X gradlew.bat \ -X HEADER.txt \ -X helm-charts/coherence-operator/templates/NOTES.txt \ -X .iml \ @@ -629,6 +632,7 @@ copyright: ## Check copyright headers -X java/src/copyright/EXCLUDE.txt \ -X Jenkinsfile \ -X .jar \ + -X jib-cache/ \ -X .jks \ -X .json \ -X LICENSE.txt \ @@ -1482,7 +1486,7 @@ mvn-deploy: java-client # ---------------------------------------------------------------------------------------------------------------------- .PHONY: build-examples build-examples: - ./mvnw -B -f ./examples package -DskipTests -P docker $(MAVEN_BUILD_OPTS) + ./mvnw -B -f ./examples package jib:dockerBuild -DskipTests $(MAVEN_BUILD_OPTS) # ---------------------------------------------------------------------------------------------------------------------- # Build and test the examples @@ -1800,7 +1804,9 @@ docs: -Doperator.image=$(OPERATOR_IMAGE) \ -Doperator.utils.image=$(UTILS_IMAGE) \ $(MAVEN_OPTIONS) - + mkdir -p $(BUILD_OUTPUT)/docs/images/images + cp -r docs/images/ build/_output/docs/images/ + find examples/ -name \*.png -exec cp {} build/_output/docs/images/images/ \; # ---------------------------------------------------------------------------------------------------------------------- # Start a local web server to serve the documentation. diff --git a/api/v1/zz_generated.deepcopy.go b/api/v1/zz_generated.deepcopy.go index b9d7a6ac8..06c8ce62b 100644 --- a/api/v1/zz_generated.deepcopy.go +++ b/api/v1/zz_generated.deepcopy.go @@ -1,4 +1,3 @@ -//go:build !ignore_autogenerated // +build !ignore_autogenerated /* diff --git a/docs/about/01_overview.adoc b/docs/about/01_overview.adoc index 9830c2db8..0c0c65bac 100644 --- a/docs/about/01_overview.adoc +++ b/docs/about/01_overview.adoc @@ -51,14 +51,14 @@ Hints and tips to troubleshoot common issues. ==== [CARD] .Guides & Examples -[icon=explore,link=docs/examples/010_overview.adoc] +[icon=explore,link=examples/000_overview.adoc] -- There are a number of examples of using the Coherence Operator and different Coherence features in Kubernetes. -- [CARD] .Non-Operator Guides & Examples -[icon=fa-ban,link=docs/no-operator/010_overview.adoc] +[icon=fa-ban,link=examples/no-operator/000_overview.adoc] -- Examples for those in the unlucky situation of not being able to install Operators, CRDs, RBAC cluster roles etc, and therfore need to manage Coherence clusters manually. -- diff --git a/docs/examples/010_overview.adoc b/docs/examples/010_overview.adoc deleted file mode 100644 index 63fbd8f50..000000000 --- a/docs/examples/010_overview.adoc +++ /dev/null @@ -1,69 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Overview - -== Examples Overview - -There are a number of examples which show you how to build and deploy applications for the Coherence Operator. - -[PILLARS] -==== -[CARD] -.Deployment -[link=docs/examples/020_deployment.adoc] --- -This example showcases how to deploy Coherence applications using the Coherence Operator. --- - -[CARD] -.Federation -[link=docs/examples/030_federation.adoc] --- -This is a simple Coherence federation example. The federation feature requires Coherence Grid Edition. --- - - -[CARD] -.TLS -[link=docs/examples/100_tls.adoc] --- -Securing Coherence clusters using TLS. --- - -[CARD] -.Autoscaling -[link=docs/examples/500_autoscaler.adoc] --- -Scaling Coherence clusters using the horizontal Pod Autoscaler. --- - -[CARD] -.Istio -[link=docs/examples/800_istio.adoc] --- -Istio Support --- - -[CARD] -.Helm -[link=docs/examples/810_helm.adoc] --- -Manage Coherence resources using Helm. --- -==== - -[PILLARS] -==== -[CARD] -.Coherence Demo App -[link=docs/examples/900_demo.adoc] --- -Deploying the Coherence demo application. --- -==== diff --git a/docs/examples/020_deployment.adoc b/docs/examples/020_deployment.adoc deleted file mode 100644 index 70128b4cb..000000000 --- a/docs/examples/020_deployment.adoc +++ /dev/null @@ -1,14 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Coherence Deployment Example - - -// DO NOT EDIT THIS FILE -// This file imports the example README.adoc file. -include::../../examples/deployment/README.adoc[] diff --git a/docs/examples/030_federation.adoc b/docs/examples/030_federation.adoc deleted file mode 100644 index d4c99dd31..000000000 --- a/docs/examples/030_federation.adoc +++ /dev/null @@ -1,14 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Coherence Federation Example - - -// DO NOT EDIT THIS FILE -// This file imports the example README.adoc file. -include::../../examples/federation/README.adoc[] diff --git a/docs/examples/500_autoscaler.adoc b/docs/examples/500_autoscaler.adoc deleted file mode 100644 index 3c24867ab..000000000 --- a/docs/examples/500_autoscaler.adoc +++ /dev/null @@ -1,12 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// -= Autoscaling Coherence Cluster - -// DO NOT EDIT THIS FILE -// This file imports the example README.adoc file. -include::../../examples/autoscaler/README.adoc[] diff --git a/docs/images/GitHub-Mark-32px.png b/docs/images/GitHub-Mark-32px.png new file mode 100644 index 000000000..663841a24 Binary files /dev/null and b/docs/images/GitHub-Mark-32px.png differ diff --git a/docs/metrics/020_metrics.adoc b/docs/metrics/020_metrics.adoc index f985e44c6..7e98127b5 100644 --- a/docs/metrics/020_metrics.adoc +++ b/docs/metrics/020_metrics.adoc @@ -13,19 +13,14 @@ Since version 12.2.1.4 Coherence has had the ability to expose a http endpoint that can be used to scrape metrics. This would typically be used to expose metrics to something like Prometheus. -NOTE: The description below is only applicable if metrics will be served by Coherence using the -`coherence-metrics` module. If Coherence metrics will be served from a different endpoint, for -example from a Helidon web-server using `coherence-mp-metrics` or using Coherence Micrometer integration, -then the documentation below does not apply. - NOTE: The default metrics endpoint is *disabled* by default in Coherence clusters but can be enabled and configured by -setting the relevant fields in the `Coherence` CRD. This assumes that your application has included the -`coherence-metrics` module as a dependency. See the Coherence product documentation for more details on enabling metrics +setting the relevant fields in the `Coherence` CRD. +If your Coherence version is before CE 21.06.2 this example assumes that your application has included the +`coherence-metrics` module as a dependency. +See the Coherence product documentation for more details on enabling metrics in your application. -The example below shows how to enable and access Coherence metrics when served by the endpoint provided by the -`coherence-metrics` module. For the example below to work the application deployed must have the `coherence-metrics` -jar file and its dependencies on the classpath. +The example below shows how to enable and access Coherence metrics. Once the metrics port has been exposed, for example via a load balancer or port-forward command, the metrics endpoint is available at `http://host:port/metrics`. diff --git a/docs/no-operator/010_overview.adoc b/docs/no-operator/010_overview.adoc deleted file mode 100644 index 9f4ce7961..000000000 --- a/docs/no-operator/010_overview.adoc +++ /dev/null @@ -1,68 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Overview - -== Non-Operator Examples Overview - -Although this documentation is all about the Coherence Kubernetes Operator, not everyone can use the Operator in their Kubernetes cluster. For example, some corporate or cloud security policies ban the use of CRDs, or have very restrictive RBAC policies that ultimately make it impossible to run Operators that uses their own CRDs or require RBAC cluster roles (and in some cases, even disallowing namespace roles). - -These examples show how to run Coherence clusters and use some Coherence features in Kubernetes manually. -Obviously the features of the Operator such as safe scaling, safe rolling upgrades, etc. will not be available. -Some Operator examples show features that can also be used without the Operator, for example the Operator -https://oracle.github.io/coherence-operator/docs/latest/docs/examples/100_tls[TLS] and -https://oracle.github.io/coherence-operator/docs/latest/docs/examples/800_istio[Istio] -examples hae a lot of general information. - -The source for the non-operator examples is in the GitHub repo, in the https://github.com/oracle/coherence-operator/tree/master/examples/no-operator[examples/no-operator/] directory - -=== Common Prerequisites - -[PILLARS] -==== -[CARD] -.Example Server Image -[link=docs/no-operator/015_server.adoc] --- -Building the example Coherence server image used by the rest of the examples below. --- - -[CARD] -.Extend Client -[link=docs/no-operator/016_client.adoc] --- -The Extend client used by the rest of the examples below. --- -==== - -=== The Examples - -[PILLARS] -==== -[CARD] -.Simple Cluster -[link=docs/no-operator/020_simple.adoc] --- -How to deploy a simple Coherence cluster using a `StatefulSet`. --- - -[CARD] -.Metrics -[link=docs/no-operator/030_metrics.adoc] --- -How to enable Coherence metrics and scrape them with Prometheus (where Prometheus is inside or outside Kubernetes). --- - - -[CARD] -.Coherence Extend with TLS -[link=docs/no-operator/040_tls.adoc] --- -Securing external Coherence Extend clients using TLS. --- -==== diff --git a/docs/no-operator/015_server.adoc b/docs/no-operator/015_server.adoc deleted file mode 100644 index d1d7c6c5f..000000000 --- a/docs/no-operator/015_server.adoc +++ /dev/null @@ -1,14 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Example Server Image - - -// DO NOT EDIT THIS FILE -// This file imports the example README.adoc file. -include::../../examples/no-operator/server-image/README.adoc[] diff --git a/docs/no-operator/016_client.adoc b/docs/no-operator/016_client.adoc deleted file mode 100644 index 38dae1852..000000000 --- a/docs/no-operator/016_client.adoc +++ /dev/null @@ -1,14 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Example Extend Client - - -// DO NOT EDIT THIS FILE -// This file imports the example README.adoc file. -include::../../examples/no-operator/test-client/README.adoc[] diff --git a/docs/no-operator/020_simple.adoc b/docs/no-operator/020_simple.adoc deleted file mode 100644 index ca63b7ea4..000000000 --- a/docs/no-operator/020_simple.adoc +++ /dev/null @@ -1,14 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Simple Coherence Cluster - - -// DO NOT EDIT THIS FILE -// This file imports the example README.adoc file. -include::../../examples/no-operator/01_simple_server/README.adoc[] diff --git a/docs/no-operator/030_metrics.adoc b/docs/no-operator/030_metrics.adoc deleted file mode 100644 index b1ae5d774..000000000 --- a/docs/no-operator/030_metrics.adoc +++ /dev/null @@ -1,14 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Coherence Metrics - - -// DO NOT EDIT THIS FILE -// This file imports the example README.adoc file. -include::../../examples/no-operator/02_metrics/README.adoc[] diff --git a/docs/no-operator/040_tls.adoc b/docs/no-operator/040_tls.adoc deleted file mode 100644 index 0f1837848..000000000 --- a/docs/no-operator/040_tls.adoc +++ /dev/null @@ -1,14 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// - -= Coherence Extend with TLS - - -// DO NOT EDIT THIS FILE -// This file imports the example README.adoc file. -include::../../examples/no-operator/03_extend_tls/README.adoc[] diff --git a/docs/sitegen.yaml b/docs/sitegen.yaml index d0a63ecfc..1a17511d6 100644 --- a/docs/sitegen.yaml +++ b/docs/sitegen.yaml @@ -19,19 +19,17 @@ assets: - target: "/" includes: - "docs/css/*.css" - - target: "/" - includes: - - "docs/images/**/*" header: favicon: - path: "docs/images/logo.png" + path: "images/logo.png" type: "png" stylesheets: - path: "docs/css/styles.css" pages: - includes: - "docs/**/*.adoc" - excludes: + - "examples/**/*.adoc" + - excludes: backend: name: "vuetify" homePage: "docs/about/01_overview.adoc" @@ -41,7 +39,7 @@ backend: title: "Coherence Operator" glyph: type: "image" - value: "docs/images/logo.png" + value: "images/logo.png" items: - title: "Core documentation" items: @@ -148,7 +146,10 @@ backend: value: "explore" items: - includes: - - "docs/examples/*.adoc" + - "examples/**/*.adoc" + excludes: + - "examples/README.adoc" + - "examples/no-operator/**/*" - title: "Non-Operator Examples" pathprefix: "/no-operator" glyph: @@ -156,7 +157,9 @@ backend: value: "fa-ban" items: - includes: - - "docs/no-operator/*.adoc" + - "examples/no-operator/**/*.adoc" + excludes: + - "examples/no-operator/README.adoc" - title: "Troubleshooting" pathprefix: "/troubleshooting" glyph: diff --git a/docs/examples/100_tls.adoc b/examples/000_overview.adoc similarity index 85% rename from docs/examples/100_tls.adoc rename to examples/000_overview.adoc index d3fbda27d..75c13bd1a 100644 --- a/docs/examples/100_tls.adoc +++ b/examples/000_overview.adoc @@ -5,8 +5,9 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// -= Secure Coherence Using TLS + += Overview // DO NOT EDIT THIS FILE // This file imports the example README.adoc file. -include::../../examples/tls/README.adoc[] +include::README.adoc[lines=9..-1] diff --git a/examples/autoscaler/.mvn/wrapper/MavenWrapperDownloader.java b/examples/015_simple_image/.mvn/wrapper/MavenWrapperDownloader.java similarity index 100% rename from examples/autoscaler/.mvn/wrapper/MavenWrapperDownloader.java rename to examples/015_simple_image/.mvn/wrapper/MavenWrapperDownloader.java diff --git a/examples/autoscaler/.mvn/wrapper/maven-wrapper.jar b/examples/015_simple_image/.mvn/wrapper/maven-wrapper.jar similarity index 100% rename from examples/autoscaler/.mvn/wrapper/maven-wrapper.jar rename to examples/015_simple_image/.mvn/wrapper/maven-wrapper.jar diff --git a/examples/autoscaler/.mvn/wrapper/maven-wrapper.properties b/examples/015_simple_image/.mvn/wrapper/maven-wrapper.properties similarity index 100% rename from examples/autoscaler/.mvn/wrapper/maven-wrapper.properties rename to examples/015_simple_image/.mvn/wrapper/maven-wrapper.properties diff --git a/examples/015_simple_image/README.adoc b/examples/015_simple_image/README.adoc new file mode 100644 index 000000000..222f3da06 --- /dev/null +++ b/examples/015_simple_image/README.adoc @@ -0,0 +1,258 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2021, Oracle and/or its affiliates. + Licensed under the Universal Permissive License v 1.0 as shown at + http://oss.oracle.com/licenses/upl. + +/////////////////////////////////////////////////////////////////////////////// += Build a Coherence Server Image + +== Example Coherence Server Image + +This example shows how to build a simple Coherence server image using +https://github.com/GoogleContainerTools/jib/blob/master/README.md[JIB] with either Maven or Gradle. +When building with Maven the project uses the https://github.com/GoogleContainerTools/jib/blob/master/jib-maven-plugin[JIB Maven Plugin]. +When building with Gradle the project uses the https://github.com/GoogleContainerTools/jib/tree/master/jib-gradle-plugin[JIB Gradle Plugin]. + +The Coherence Operator has out of the box support for images built with JIB, for example it can automatically detect the class path to use and run the correct main class. + +This simple application does not actually contain any code, a real application would obviously contain code and other resources. + +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for this example is in the https://github.com/oracle/coherence-operator/tree/master/examples/015_simple_image[Coherence Operator GitHub] repository. +==== + +=== Add Dependencies + +To build a Coherence application there will obviously be at a minimum a dependency on `coherence.jar`. +Optionally we can also add dependencies on other Coherence modules. +In this example we're going to add management over REST to the application by adding a dependency on `coherence-management`. + +In the example we use the `coherence-bom` which ensures that we have consistent use of other Coherence modules. +In the `pom.xml` we have a `dependencyManagement` section. +[source,xml] +.pom.xml +---- + + + + com.oracle.coherence.ce + coherence-bom + ${coherence.version} + pom + import + + + +---- + +In the `build.gradle` file we add the bom as a platform dependency. +[source,groovy] +.build.gradle +---- +dependencies { + implementation platform("com.oracle.coherence.ce:coherence-bom:21.06.2") +---- + +We can then add the `coherence` and `coherence-management` modules as dependencies + +[source,xml] +.pom.xml +---- + + + com.oracle.coherence.ce + coherence + + + com.oracle.coherence.ce + coherence-management + + +---- + +In the `build.gradle` file we add the bom as a platform dependency. +[source,groovy] +.build.gradle +---- +dependencies { + implementation platform("com.oracle.coherence.ce:coherence-bom:21.06.2") + + implementation "com.oracle.coherence.ce:coherence" + implementation "com.oracle.coherence.ce:coherence-management" +} +---- + +=== Add the JIB Plugin + +To build the image using JIB we need to add the JIB plugin to the project. + +In the `pom.xml` file we add JIB to the `plugins` section. + +[source,xml] +.pom.xml +---- + + + + com.google.cloud.tools + jib-maven-plugin + 3.1.4 + + + +---- + +In the `build.gradle` file we add JIB to the `plugins` section. +[source,groovy] +.build.gradle +---- +plugins { + id 'java' + id 'com.google.cloud.tools.jib' version '3.1.4' +} +---- + +=== Configure the JIB Plugin + +Now we can configure the JIB plugin with the properties specific to our image. +In this example the configuration is very simple, the JIB plugin documentation shows many more options. + +We are going to set the following options: +* The name and tags for the image we will build. +* The main class that we will run as the entry point to the image - in this case `com.tangosol.net.Coherence`. +* The base image. In this example we will us a distroless Java 11 image. A distroless image is more secure as it contains nothing more than core linux and a JRE. There is no shell or other tools to introduce CVEs. The downside of this is that there is no shell, so you cannot exec into the running container, or use a shell script as an entry point. If you don;t need those things a distroless image is a great choice. + +==== Maven Configuration + +In the `pom.xml` file we configure the plugin where it is declared in the `plugins` section: +[source,xml] +.pom.xml +---- + + com.google.cloud.tools + jib-maven-plugin + ${version.plugin.jib} + + + gcr.io/distroless/java:11 <1> + + + ${project.artifactId} <2> + + ${project.version} <3> + latest + + + + com.tangosol.net.Coherence <4> + OCI <5> + + + +---- +<1> The base image will be `gcr.io/distroless/java:11` +<2> The image name is set to the Maven module name using the property `${project.artifactId}` +<3> There will be two tags for the image, `latest` and the project version taken from the `${project.version}` property. +<4> The main class to use when the image is run is set to `com.tangosol.net.Coherence` +<5> The image type is set to `OCI` + +==== Gradle Configuration + +In the `build.gradle` file we configure JIB in the `jib` section: +[source,groovy] +.build.gradle +---- +jib { + from { + image = 'gcr.io/distroless/java:11' // <1> + } + to { + image = "${project.name}" // <2> + tags = ["${version}", 'latest'] // <3> + } + container { + mainClass = 'com.tangosol.net.Coherence' // <4> + format = 'OCI' // <5> + } +} +---- +<1> The base image will be `gcr.io/distroless/java:11` +<2> The image name is set to the Maven module name using the property `${project.artifactId}` +<3> There will be two tags for the image, `latest` and the project version taken from the `${project.version}` property. +<4> The main class to use when the image is run is set to `com.tangosol.net.Coherence` +<5> The image type is set to `OCI` + + +=== Build the Image + +To create the server image run the relevant commands as documented in the JIB plugin documentation. +In this case we're going to build the image using Docker, although JIB offers other alternatives. + +Using Maven we run: +[source,bash] +---- +./mvnw compile jib:dockerBuild +---- + +Using Gradle we run: +[source,bash] +---- +./gradlew compileJava jibDockerBuild +---- + +The command above will create an image named `simple-coherence` with two tags, `latest` and `1.0.0`. +Listing the local images should show the new images. +[source,bash] +---- +$ docker images | grep simple +simple-coherence 1.0.0 1613cd3b894e 51 years ago 227MB +simple-coherence latest 1613cd3b894e 51 years ago 227MB +---- + +=== Run the Image + +The image just built can be run using Docker (or your chosen container tool). +In this example we'll run it interactively, just to prove it runs and starts Coherence. +[source,bash] +---- +docker run -it --rm simple-coherence:latest +---- + +The console output should display Coherence starting and finally show the Coherence service list, which will look something like this: +[source,bash] +---- +Services + ( + ClusterService{Name=Cluster, State=(SERVICE_STARTED, STATE_JOINED), Id=0, OldestMemberId=1} + TransportService{Name=TransportService, State=(SERVICE_STARTED), Id=1, OldestMemberId=1} + InvocationService{Name=Management, State=(SERVICE_STARTED), Id=2, OldestMemberId=1} + PartitionedCache{Name=$SYS:Config, State=(SERVICE_STARTED), Id=3, OldestMemberId=1, LocalStorage=enabled, PartitionCount=257, BackupCount=1, AssignedPartitions=257, BackupPartitions=0, CoordinatorId=1} + PartitionedCache{Name=PartitionedCache, State=(SERVICE_STARTED), Id=4, OldestMemberId=1, LocalStorage=enabled, PartitionCount=257, BackupCount=1, AssignedPartitions=257, BackupPartitions=0, CoordinatorId=1} + PartitionedCache{Name=PartitionedTopic, State=(SERVICE_STARTED), Id=5, OldestMemberId=1, LocalStorage=enabled, PartitionCount=257, BackupCount=1, AssignedPartitions=257, BackupPartitions=0, CoordinatorId=1} + ProxyService{Name=Proxy, State=(SERVICE_STARTED), Id=6, OldestMemberId=1} + ) +---- + +Press `ctrl-C` to exit the container, the `--rm` option we used above wil automatically delete the stopped container. + +We now have a simple Coherence image we can use in other examples and when trying out the Coherence Operator. + +=== Configuring the Image at Runtime + +With recent Coherence versions, Coherence configuration items that can be set using system properties prefixed with `coherence.` can also be set using environment variables. This makes it simple to set those properties when running containers because environment variables can be set from the commandline. + +To set a property the system property name needs to be converted to an environment variable name. +This is done by converting the name to uppercase and replacing dots ('.') with underscores ('_'). + +For example, to set the cluster name we would set the `coherence.cluster` system property. +To run the image and set cluster name with an environment variable we convert `coherence.cluster` to `COHERENCE_CLUSTER` and run: + +[source,bash] +---- +docker run -it --rm -e COHERENCE_CLUSTER=my-cluster simple-coherence:latest +---- + +This is much simpler than trying to change the Java commandline the image entrypoint uses. + diff --git a/examples/015_simple_image/build.gradle b/examples/015_simple_image/build.gradle new file mode 100644 index 000000000..d7b84a790 --- /dev/null +++ b/examples/015_simple_image/build.gradle @@ -0,0 +1,40 @@ +/* + * Copyright (c) 2021, Oracle and/or its affiliates. + * Licensed under the Universal Permissive License v 1.0 as shown at + * http://oss.oracle.com/licenses/upl. + */ + +plugins { + id 'java' + id 'com.google.cloud.tools.jib' version '3.1.4' +} + +group = 'com.oracle.coherence.examples' +version = '1.0.0' +sourceCompatibility = '1.8' + +repositories { + mavenCentral() + mavenLocal() +} + +dependencies { + implementation platform("com.oracle.coherence.ce:coherence-bom:21.06.2") + + implementation "com.oracle.coherence.ce:coherence" + implementation "com.oracle.coherence.ce:coherence-management" +} + +jib { + from { + image = 'gcr.io/distroless/java:11' + } + to { + image = "${project.name}" + tags = ["${version}", 'latest'] + } + container { + mainClass = 'com.tangosol.net.Coherence' + format = 'OCI' + } +} diff --git a/examples/015_simple_image/gradle/wrapper/gradle-wrapper.jar b/examples/015_simple_image/gradle/wrapper/gradle-wrapper.jar new file mode 100644 index 000000000..e708b1c02 Binary files /dev/null and b/examples/015_simple_image/gradle/wrapper/gradle-wrapper.jar differ diff --git a/examples/015_simple_image/gradle/wrapper/gradle-wrapper.properties b/examples/015_simple_image/gradle/wrapper/gradle-wrapper.properties new file mode 100644 index 000000000..be52383ef --- /dev/null +++ b/examples/015_simple_image/gradle/wrapper/gradle-wrapper.properties @@ -0,0 +1,5 @@ +distributionBase=GRADLE_USER_HOME +distributionPath=wrapper/dists +distributionUrl=https\://services.gradle.org/distributions/gradle-6.7-bin.zip +zipStoreBase=GRADLE_USER_HOME +zipStorePath=wrapper/dists diff --git a/examples/015_simple_image/gradlew b/examples/015_simple_image/gradlew new file mode 100755 index 000000000..4f906e0c8 --- /dev/null +++ b/examples/015_simple_image/gradlew @@ -0,0 +1,185 @@ +#!/usr/bin/env sh + +# +# Copyright 2015 the original author or authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +############################################################################## +## +## Gradle start up script for UN*X +## +############################################################################## + +# Attempt to set APP_HOME +# Resolve links: $0 may be a link +PRG="$0" +# Need this for relative symlinks. +while [ -h "$PRG" ] ; do + ls=`ls -ld "$PRG"` + link=`expr "$ls" : '.*-> \(.*\)$'` + if expr "$link" : '/.*' > /dev/null; then + PRG="$link" + else + PRG=`dirname "$PRG"`"/$link" + fi +done +SAVED="`pwd`" +cd "`dirname \"$PRG\"`/" >/dev/null +APP_HOME="`pwd -P`" +cd "$SAVED" >/dev/null + +APP_NAME="Gradle" +APP_BASE_NAME=`basename "$0"` + +# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' + +# Use the maximum available, or set MAX_FD != -1 to use that value. +MAX_FD="maximum" + +warn () { + echo "$*" +} + +die () { + echo + echo "$*" + echo + exit 1 +} + +# OS specific support (must be 'true' or 'false'). +cygwin=false +msys=false +darwin=false +nonstop=false +case "`uname`" in + CYGWIN* ) + cygwin=true + ;; + Darwin* ) + darwin=true + ;; + MINGW* ) + msys=true + ;; + NONSTOP* ) + nonstop=true + ;; +esac + +CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar + + +# Determine the Java command to use to start the JVM. +if [ -n "$JAVA_HOME" ] ; then + if [ -x "$JAVA_HOME/jre/sh/java" ] ; then + # IBM's JDK on AIX uses strange locations for the executables + JAVACMD="$JAVA_HOME/jre/sh/java" + else + JAVACMD="$JAVA_HOME/bin/java" + fi + if [ ! -x "$JAVACMD" ] ; then + die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." + fi +else + JAVACMD="java" + which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." +fi + +# Increase the maximum file descriptors if we can. +if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then + MAX_FD_LIMIT=`ulimit -H -n` + if [ $? -eq 0 ] ; then + if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then + MAX_FD="$MAX_FD_LIMIT" + fi + ulimit -n $MAX_FD + if [ $? -ne 0 ] ; then + warn "Could not set maximum file descriptor limit: $MAX_FD" + fi + else + warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT" + fi +fi + +# For Darwin, add options to specify how the application appears in the dock +if $darwin; then + GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\"" +fi + +# For Cygwin or MSYS, switch paths to Windows format before running java +if [ "$cygwin" = "true" -o "$msys" = "true" ] ; then + APP_HOME=`cygpath --path --mixed "$APP_HOME"` + CLASSPATH=`cygpath --path --mixed "$CLASSPATH"` + + JAVACMD=`cygpath --unix "$JAVACMD"` + + # We build the pattern for arguments to be converted via cygpath + ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null` + SEP="" + for dir in $ROOTDIRSRAW ; do + ROOTDIRS="$ROOTDIRS$SEP$dir" + SEP="|" + done + OURCYGPATTERN="(^($ROOTDIRS))" + # Add a user-defined pattern to the cygpath arguments + if [ "$GRADLE_CYGPATTERN" != "" ] ; then + OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)" + fi + # Now convert the arguments - kludge to limit ourselves to /bin/sh + i=0 + for arg in "$@" ; do + CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -` + CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option + + if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition + eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"` + else + eval `echo args$i`="\"$arg\"" + fi + i=`expr $i + 1` + done + case $i in + 0) set -- ;; + 1) set -- "$args0" ;; + 2) set -- "$args0" "$args1" ;; + 3) set -- "$args0" "$args1" "$args2" ;; + 4) set -- "$args0" "$args1" "$args2" "$args3" ;; + 5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;; + 6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;; + 7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;; + 8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;; + 9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;; + esac +fi + +# Escape application args +save () { + for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done + echo " " +} +APP_ARGS=`save "$@"` + +# Collect all arguments for the java command, following the shell quoting and substitution rules +eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS" + +exec "$JAVACMD" "$@" diff --git a/examples/015_simple_image/gradlew.bat b/examples/015_simple_image/gradlew.bat new file mode 100644 index 000000000..107acd32c --- /dev/null +++ b/examples/015_simple_image/gradlew.bat @@ -0,0 +1,89 @@ +@rem +@rem Copyright 2015 the original author or authors. +@rem +@rem Licensed under the Apache License, Version 2.0 (the "License"); +@rem you may not use this file except in compliance with the License. +@rem You may obtain a copy of the License at +@rem +@rem https://www.apache.org/licenses/LICENSE-2.0 +@rem +@rem Unless required by applicable law or agreed to in writing, software +@rem distributed under the License is distributed on an "AS IS" BASIS, +@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +@rem See the License for the specific language governing permissions and +@rem limitations under the License. +@rem + +@if "%DEBUG%" == "" @echo off +@rem ########################################################################## +@rem +@rem Gradle startup script for Windows +@rem +@rem ########################################################################## + +@rem Set local scope for the variables with windows NT shell +if "%OS%"=="Windows_NT" setlocal + +set DIRNAME=%~dp0 +if "%DIRNAME%" == "" set DIRNAME=. +set APP_BASE_NAME=%~n0 +set APP_HOME=%DIRNAME% + +@rem Resolve any "." and ".." in APP_HOME to make it shorter. +for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi + +@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m" + +@rem Find java.exe +if defined JAVA_HOME goto findJavaFromJavaHome + +set JAVA_EXE=java.exe +%JAVA_EXE% -version >NUL 2>&1 +if "%ERRORLEVEL%" == "0" goto execute + +echo. +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. +echo. +echo Please set the JAVA_HOME variable in your environment to match the +echo location of your Java installation. + +goto fail + +:findJavaFromJavaHome +set JAVA_HOME=%JAVA_HOME:"=% +set JAVA_EXE=%JAVA_HOME%/bin/java.exe + +if exist "%JAVA_EXE%" goto execute + +echo. +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% +echo. +echo Please set the JAVA_HOME variable in your environment to match the +echo location of your Java installation. + +goto fail + +:execute +@rem Setup the command line + +set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar + + +@rem Execute Gradle +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %* + +:end +@rem End local scope for the variables with windows NT shell +if "%ERRORLEVEL%"=="0" goto mainEnd + +:fail +rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of +rem the _cmd.exe /c_ return code! +if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 +exit /b 1 + +:mainEnd +if "%OS%"=="Windows_NT" endlocal + +:omega diff --git a/examples/autoscaler/mvnw b/examples/015_simple_image/mvnw similarity index 100% rename from examples/autoscaler/mvnw rename to examples/015_simple_image/mvnw diff --git a/examples/autoscaler/mvnw.cmd b/examples/015_simple_image/mvnw.cmd similarity index 100% rename from examples/autoscaler/mvnw.cmd rename to examples/015_simple_image/mvnw.cmd diff --git a/examples/no-operator/server-image/pom.xml b/examples/015_simple_image/pom.xml similarity index 56% rename from examples/no-operator/server-image/pom.xml rename to examples/015_simple_image/pom.xml index 1578f87e4..89c9b2ee9 100644 --- a/examples/no-operator/server-image/pom.xml +++ b/examples/015_simple_image/pom.xml @@ -16,45 +16,39 @@ jar 1.0.0 - Oracle Coherence Simple Kubernetes Example - Simple Coherence + Simple Coherence Image + Simple Coherence Image UTF-8 8 8 - - 21.06.1 + 21.06.2 - 1.0-b01-ea 3.1.4 + + + + com.oracle.coherence.ce + coherence-bom + ${coherence.version} + pom + import + + + + - com.oracle.coherence.ce coherence - ${coherence.version} - com.oracle.coherence.ce coherence-management - ${coherence.version} - - - - com.oracle.coherence.ce - coherence-metrics - ${coherence.version} - - - - org.glassfish.external - opendmk_jmxremote_optional_jar - ${version.lib.glassfish.jmxmp} @@ -66,16 +60,16 @@ ${version.plugin.jib} - gcr.io/distroless/java:11 - - ${project.artifactId}:${project.version} + ${project.artifactId} + + ${project.version} + latest + - com.tangosol.net.Coherence OCI diff --git a/examples/015_simple_image/settings.gradle b/examples/015_simple_image/settings.gradle new file mode 100644 index 000000000..0446acdd9 --- /dev/null +++ b/examples/015_simple_image/settings.gradle @@ -0,0 +1,7 @@ +/* + * Copyright (c) 2021, Oracle and/or its affiliates. + * Licensed under the Universal Permissive License v 1.0 as shown at + * http://oss.oracle.com/licenses/upl. + */ + +rootProject.name = 'simple-coherence' \ No newline at end of file diff --git a/examples/no-operator/server-image/src/main/java/com/oracle/coherence/examples/tls/FileBasedPasswordProvider.java b/examples/015_simple_image/src/main/java/com/oracle/coherence/examples/tls/FileBasedPasswordProvider.java similarity index 97% rename from examples/no-operator/server-image/src/main/java/com/oracle/coherence/examples/tls/FileBasedPasswordProvider.java rename to examples/015_simple_image/src/main/java/com/oracle/coherence/examples/tls/FileBasedPasswordProvider.java index 5ad71ced8..132e45ea7 100644 --- a/examples/no-operator/server-image/src/main/java/com/oracle/coherence/examples/tls/FileBasedPasswordProvider.java +++ b/examples/015_simple_image/src/main/java/com/oracle/coherence/examples/tls/FileBasedPasswordProvider.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019, 2021 Oracle and/or its affiliates. + * Copyright (c) 2021, Oracle and/or its affiliates. * Licensed under the Universal Permissive License v 1.0 as shown at * http://oss.oracle.com/licenses/upl. */ diff --git a/examples/no-operator/server-image/src/main/resources/tangosol-coherence-override.xml b/examples/015_simple_image/src/main/resources/tangosol-coherence-override.xml similarity index 100% rename from examples/no-operator/server-image/src/main/resources/tangosol-coherence-override.xml rename to examples/015_simple_image/src/main/resources/tangosol-coherence-override.xml diff --git a/examples/no-operator/server-image/src/main/resources/test-cache-config.xml b/examples/015_simple_image/src/main/resources/test-cache-config.xml similarity index 100% rename from examples/no-operator/server-image/src/main/resources/test-cache-config.xml rename to examples/015_simple_image/src/main/resources/test-cache-config.xml diff --git a/examples/020_hello_world/README.adoc b/examples/020_hello_world/README.adoc new file mode 100644 index 000000000..2574d4a76 --- /dev/null +++ b/examples/020_hello_world/README.adoc @@ -0,0 +1,151 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2021, Oracle and/or its affiliates. + Licensed under the Universal Permissive License v 1.0 as shown at + http://oss.oracle.com/licenses/upl. + +/////////////////////////////////////////////////////////////////////////////// += A "Hello World" Operator Example + +== A "Hello World" Operator Example + +This is the most basic example of how to deploy a simple Coherence cluster to Kubernetes using the Coherence Operator. + +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for this example is in the https://github.com/oracle/coherence-operator/tree/master/examples/020_hello_world[Coherence Operator GitHub] repository. +==== + +=== Install the Operator + +If you have not already done so, you need to install the Coherence Operator. +There are a few simple ways to do this as described in the <> + +=== A Default Coherence Cluster + +All the fields in the Coherence CRD spec are optional, the Operator will apply default values, if required, for fields not specified. + +For example, this is the minimum required yaml to run a Coherence cluster: +[source,yaml] +.default-coherence.yaml +---- +apiVersion: coherence.oracle.com/v1 +kind: Coherence +metadata: + name: test +---- + +The yaml above could be installed into Kubernetes using kubectl: +[source,bash] +---- +kubectl create -f default-coherence.yaml +---- + +The command above will create a Coherence cluster named `test` in the `default` Kubernetes namespace. + +Because no `spec` was specified in the yaml, the Operator will use its defaults for certain fields. + +* The `replicas` field, which controls the number of Pods in the cluster, will default to `3`. +* The image used to run Coherence will be the default for this version of the Operator, +typically this is the latest Coherence CE image released at the time the Operator version was released. +* No ports will be exposed on the container, and no additional services will be created. + +We can list the resources that have been created by the Operator. +[source,bash] +---- +kubectl get all +---- + +Which should display something like this: +[source,bash] +---- +NAME READY STATUS RESTARTS AGE +pod/test-0 1/1 Running 0 81s +pod/test-1 1/1 Running 0 81s +pod/test-2 1/1 Running 0 81s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/test-sts ClusterIP None 7/TCP 81s +service/test-wka ClusterIP None 7/TCP 81s + +NAME READY AGE +statefulset.apps/test 3/3 81s +---- +* We can see that the Operator has created a `StatefulSet`, with three `Pods` and there are two `Services`. +* The `test-sts` service is the headless service required for the `StatefulSet`. +* The `test-wka` service is the headless service that Coherence will use for well known address cluster discovery. + +We can now undeploy the cluster: +[source,bash] +---- +kubectl delete -f default-coherence.yaml +---- + + +=== Deploy the Simple Server Image + +We can deploy a specific image by setting the `spec.image` field in the yaml. +In this example we'll deploy the `simple-coherence:1.0.0` image built in the +<> example. + +To deploy a specific image we just need to set the `spec.image` field. +[source,yaml] +.simple.yaml +---- +apiVersion: coherence.oracle.com/v1 +kind: Coherence +metadata: + name: simple +spec: + image: simple-coherence:1.0.0 <1> + replicas: 6 <2> + ports: + - name: extend <3> + port: 20000 +---- +<1> We have set the image to use to the <> example `simple-coherence:1.0.0`. +<2> We have set the `replicas` field to `6`, so this time there should only be six Pods. +<3> The simple image starts a Coherence Extend proxy on port `20000`, so we expose this port in the `Coherence` spec. The Operator will then expose the port on the Coherence container and create a Service for the port. + +We can deploy the simple cluster into Kubernetes using kubectl: +[source,bash] +---- +kubectl create -f simple.yaml +---- + +Now list the resources the Operator has created. +[source,bash] +---- +kubectl get all +---- + +Which this time should look something like this: +[source,bash] +---- +NAME READY STATUS RESTARTS AGE +pod/test-0 1/1 Running 0 4m49s +pod/test-1 1/1 Running 0 4m49s +pod/test-2 1/1 Running 0 4m49s +pod/test-3 1/1 Running 0 4m49s +pod/test-4 1/1 Running 0 4m49s +pod/test-5 1/1 Running 0 4m49s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/kubernetes ClusterIP 10.96.0.1 443/TCP 164d +service/test-extend ClusterIP 10.108.166.193 20000/TCP 4m49s +service/test-sts ClusterIP None 7/TCP 4m49s +service/test-wka ClusterIP None 7/TCP 4m49s + +NAME READY AGE +statefulset.apps/test 6/6 4m49s +---- +* We can see that the Operator has created a `StatefulSet`, with six `Pods` and there are three `Services`. +* The `simple-sts` service is the headless service required for the `StatefulSet`. +* The `simple-wka` service is the headless service that Coherence will use for well known address cluster discovery. +* The `simple-extend` service is the service that exposes the Extend port `20000`, and could be used by Extend clients to connect to the cluster. + +We can now delete the simple cluster: +[source,bash] +---- +kubectl delete -f simple.yaml +---- diff --git a/examples/020_hello_world/default-coherence.yaml b/examples/020_hello_world/default-coherence.yaml new file mode 100644 index 000000000..de2efc941 --- /dev/null +++ b/examples/020_hello_world/default-coherence.yaml @@ -0,0 +1,4 @@ +apiVersion: coherence.oracle.com/v1 +kind: Coherence +metadata: + name: test diff --git a/examples/020_hello_world/simple.yaml b/examples/020_hello_world/simple.yaml new file mode 100644 index 000000000..febc9fb53 --- /dev/null +++ b/examples/020_hello_world/simple.yaml @@ -0,0 +1,10 @@ +apiVersion: coherence.oracle.com/v1 +kind: Coherence +metadata: + name: test +spec: + image: simple-coherence:1.0.0 + replicas: 6 + ports: + - name: extend + port: 20000 diff --git a/examples/deployment/.mvn/wrapper/MavenWrapperDownloader.java b/examples/021_deployment/.mvn/wrapper/MavenWrapperDownloader.java similarity index 100% rename from examples/deployment/.mvn/wrapper/MavenWrapperDownloader.java rename to examples/021_deployment/.mvn/wrapper/MavenWrapperDownloader.java diff --git a/examples/deployment/.mvn/wrapper/maven-wrapper.jar b/examples/021_deployment/.mvn/wrapper/maven-wrapper.jar similarity index 100% rename from examples/deployment/.mvn/wrapper/maven-wrapper.jar rename to examples/021_deployment/.mvn/wrapper/maven-wrapper.jar diff --git a/examples/deployment/.mvn/wrapper/maven-wrapper.properties b/examples/021_deployment/.mvn/wrapper/maven-wrapper.properties similarity index 100% rename from examples/deployment/.mvn/wrapper/maven-wrapper.properties rename to examples/021_deployment/.mvn/wrapper/maven-wrapper.properties diff --git a/examples/deployment/README.adoc b/examples/021_deployment/README.adoc similarity index 97% rename from examples/deployment/README.adoc rename to examples/021_deployment/README.adoc index 0a3c15f1e..24acf6c4d 100644 --- a/examples/deployment/README.adoc +++ b/examples/021_deployment/README.adoc @@ -1,9 +1,15 @@ += Coherence Deployment Example + == Coherence Operator Deployment Example This example showcases how to deploy Coherence applications using the Coherence Operator. This example shows how to use the Kubernetes Horizontal Pod Autoscaler to scale Coherence clusters. -You can find the source code in the https://github.com/oracle/coherence-operator/tree/master/examples/deployment[Operator GitHub Repo] + +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for this example is in the https://github.com/oracle/coherence-operator/tree/master/examples/021_deployment[Coherence Operator GitHub] repository. +==== The following scenarios are covered: @@ -59,7 +65,7 @@ to match your selected namespace when running the examples. [#clone-the-github-repository] == Clone the GitHub repository -These examples exist in the `examples/deployment` directory in the +These examples exist in the `examples/021_deployment` directory in the https://github.com/oracle/coherence-operator[Coherence Operator GitHub repository]. Clone the repository: @@ -68,7 +74,7 @@ Clone the repository: ---- git clone https://github.com/oracle/coherence-operator -cd coherence-operator/examples/deployment +cd coherence-operator/examples/021_deployment ---- Ensure you have Docker running and JDK 11+ build environment set and use the @@ -125,7 +131,7 @@ coherence-operator-controller-manager-74d49cd9f9-sgzjr 1/1 Running 1 [#examples] == Run the Examples -Ensure you are in the `examples/deployment` directory to run the following commands. +Ensure you are in the `examples/021_deployment` directory to run the following commands. [#ex1] === Example 1 - Coherence cluster only @@ -340,7 +346,7 @@ Ensure the `example-cluster-proxy-0` pod is Running and READY before continuing. ==== Connect via CohQL and add data -In a separate terminal, change to the `examples/deployments` directory and run the following to +In a separate terminal, change to the `examples/021_deployments` directory and run the following to start Coherence Query Language (CohQL): [source,bash] diff --git a/examples/deployment/mvnw b/examples/021_deployment/mvnw similarity index 100% rename from examples/deployment/mvnw rename to examples/021_deployment/mvnw diff --git a/examples/deployment/mvnw.cmd b/examples/021_deployment/mvnw.cmd similarity index 100% rename from examples/deployment/mvnw.cmd rename to examples/021_deployment/mvnw.cmd diff --git a/examples/deployment/pom.xml b/examples/021_deployment/pom.xml similarity index 93% rename from examples/deployment/pom.xml rename to examples/021_deployment/pom.xml index cf0ac7cbd..851af6fac 100644 --- a/examples/deployment/pom.xml +++ b/examples/021_deployment/pom.xml @@ -16,11 +16,11 @@ com.oracle.coherence.ce - 21.06 + 21.06.2 1.3.1 - 2.8.0 + 3.1.4 ${project.version} @@ -44,12 +44,6 @@ ${coherence.version} - - ${coherence.group.id} - coherence-metrics - ${coherence.version} - - io.helidon.bundles helidon-bundles-webserver diff --git a/examples/deployment/scripts/README.md b/examples/021_deployment/scripts/README.md similarity index 100% rename from examples/deployment/scripts/README.md rename to examples/021_deployment/scripts/README.md diff --git a/examples/deployment/scripts/port-forward-es.sh b/examples/021_deployment/scripts/port-forward-es.sh similarity index 100% rename from examples/deployment/scripts/port-forward-es.sh rename to examples/021_deployment/scripts/port-forward-es.sh diff --git a/examples/deployment/scripts/port-forward-grafana.sh b/examples/021_deployment/scripts/port-forward-grafana.sh similarity index 100% rename from examples/deployment/scripts/port-forward-grafana.sh rename to examples/021_deployment/scripts/port-forward-grafana.sh diff --git a/examples/deployment/scripts/port-forward-kibana.sh b/examples/021_deployment/scripts/port-forward-kibana.sh similarity index 100% rename from examples/deployment/scripts/port-forward-kibana.sh rename to examples/021_deployment/scripts/port-forward-kibana.sh diff --git a/examples/deployment/scripts/port-forward-prometheus.sh b/examples/021_deployment/scripts/port-forward-prometheus.sh similarity index 100% rename from examples/deployment/scripts/port-forward-prometheus.sh rename to examples/021_deployment/scripts/port-forward-prometheus.sh diff --git a/examples/deployment/src/main/java/com/oracle/coherence/examples/Main.java b/examples/021_deployment/src/main/java/com/oracle/coherence/examples/Main.java similarity index 98% rename from examples/deployment/src/main/java/com/oracle/coherence/examples/Main.java rename to examples/021_deployment/src/main/java/com/oracle/coherence/examples/Main.java index d8e77f5d6..f414c716b 100644 --- a/examples/deployment/src/main/java/com/oracle/coherence/examples/Main.java +++ b/examples/021_deployment/src/main/java/com/oracle/coherence/examples/Main.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, Oracle and/or its affiliates. + * Copyright (c) 2020, 2021, Oracle and/or its affiliates. * Licensed under the Universal Permissive License v 1.0 as shown at * http://oss.oracle.com/licenses/upl. */ diff --git a/examples/deployment/src/main/java/com/oracle/coherence/examples/Person.java b/examples/021_deployment/src/main/java/com/oracle/coherence/examples/Person.java similarity index 98% rename from examples/deployment/src/main/java/com/oracle/coherence/examples/Person.java rename to examples/021_deployment/src/main/java/com/oracle/coherence/examples/Person.java index 702f4a4f6..1ca436a1d 100644 --- a/examples/deployment/src/main/java/com/oracle/coherence/examples/Person.java +++ b/examples/021_deployment/src/main/java/com/oracle/coherence/examples/Person.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, Oracle and/or its affiliates. + * Copyright (c) 2020, 2021, Oracle and/or its affiliates. * Licensed under the Universal Permissive License v 1.0 as shown at * http://oss.oracle.com/licenses/upl. */ diff --git a/examples/deployment/src/main/java/com/oracle/coherence/examples/package-info.java b/examples/021_deployment/src/main/java/com/oracle/coherence/examples/package-info.java similarity index 76% rename from examples/deployment/src/main/java/com/oracle/coherence/examples/package-info.java rename to examples/021_deployment/src/main/java/com/oracle/coherence/examples/package-info.java index a629aff9c..f955fd078 100644 --- a/examples/deployment/src/main/java/com/oracle/coherence/examples/package-info.java +++ b/examples/021_deployment/src/main/java/com/oracle/coherence/examples/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, Oracle and/or its affiliates. + * Copyright (c) 2020, 2021, Oracle and/or its affiliates. * Licensed under the Universal Permissive License v 1.0 as shown at * http://oss.oracle.com/licenses/upl. */ diff --git a/examples/deployment/src/main/resources/client-cache-config.xml b/examples/021_deployment/src/main/resources/client-cache-config.xml similarity index 95% rename from examples/deployment/src/main/resources/client-cache-config.xml rename to examples/021_deployment/src/main/resources/client-cache-config.xml index 5e96b845b..61183abe8 100644 --- a/examples/deployment/src/main/resources/client-cache-config.xml +++ b/examples/021_deployment/src/main/resources/client-cache-config.xml @@ -1,6 +1,6 @@ diff --git a/examples/deployment/src/main/resources/helidon-logging.properties b/examples/021_deployment/src/main/resources/helidon-logging.properties similarity index 94% rename from examples/deployment/src/main/resources/helidon-logging.properties rename to examples/021_deployment/src/main/resources/helidon-logging.properties index b74936ab6..3fa279ae2 100644 --- a/examples/deployment/src/main/resources/helidon-logging.properties +++ b/examples/021_deployment/src/main/resources/helidon-logging.properties @@ -1,4 +1,4 @@ -# Copyright (c) 2019, 2020, Oracle and/or its affiliates. +# Copyright (c) 2020, 2021, Oracle and/or its affiliates. # Licensed under the Universal Permissive License v 1.0 as shown at # http://oss.oracle.com/licenses/upl. diff --git a/examples/deployment/src/main/resources/proxy-cache-config.xml b/examples/021_deployment/src/main/resources/proxy-cache-config.xml similarity index 97% rename from examples/deployment/src/main/resources/proxy-cache-config.xml rename to examples/021_deployment/src/main/resources/proxy-cache-config.xml index 3814953bf..5fe11401d 100644 --- a/examples/deployment/src/main/resources/proxy-cache-config.xml +++ b/examples/021_deployment/src/main/resources/proxy-cache-config.xml @@ -1,7 +1,7 @@ diff --git a/examples/autoscaler/src/main/resources/coherence-cache-config.xml b/examples/200_autoscaler/src/main/resources/coherence-cache-config.xml similarity index 97% rename from examples/autoscaler/src/main/resources/coherence-cache-config.xml rename to examples/200_autoscaler/src/main/resources/coherence-cache-config.xml index bce2e2cc7..f66c80154 100644 --- a/examples/autoscaler/src/main/resources/coherence-cache-config.xml +++ b/examples/200_autoscaler/src/main/resources/coherence-cache-config.xml @@ -1,6 +1,6 @@ diff --git a/examples/autoscaler/src/main/resources/custom-mbeans.xml b/examples/200_autoscaler/src/main/resources/custom-mbeans.xml similarity index 91% rename from examples/autoscaler/src/main/resources/custom-mbeans.xml rename to examples/200_autoscaler/src/main/resources/custom-mbeans.xml index a4b47b519..4756e6ccd 100644 --- a/examples/autoscaler/src/main/resources/custom-mbeans.xml +++ b/examples/200_autoscaler/src/main/resources/custom-mbeans.xml @@ -1,6 +1,6 @@ diff --git a/examples/helm/README.adoc b/examples/300_helm/README.adoc similarity index 98% rename from examples/helm/README.adoc rename to examples/300_helm/README.adoc index 987749215..e68a78c52 100644 --- a/examples/helm/README.adoc +++ b/examples/300_helm/README.adoc @@ -5,12 +5,19 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// += Manage Coherence using Helm + == Manage Coherence Resources using Helm Occasionally there is a requirement to manage Coherence resources using Helm instead of Kubernetes tools such as `kubectl`. There is no Helm chart for a Coherence resource as it is a single resource and any Helm chart and values file would need to replicate the entire Coherence CRD if it was to be of generic enough use for everyone. For this reason, anyone wanting to manage Coherence resource using Helm will need to create their own chart, which can then be specific to their needs. This example shows some ways that Helm can be used to manage Coherence resources. +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for this example is in the https://github.com/oracle/coherence-operator/tree/master/examples/300_helm[Coherence Operator GitHub] repository. +==== + === A Simple Generic Helm Chart This example contains the most basic Helm chart possible to support managing a Coherence resource locate in the `chart/` directory. The chart is actually completely generic and would support any configuration of Coherence resource. diff --git a/examples/helm/chart/Chart.yaml b/examples/300_helm/chart/Chart.yaml similarity index 100% rename from examples/helm/chart/Chart.yaml rename to examples/300_helm/chart/Chart.yaml diff --git a/examples/helm/chart/README.md b/examples/300_helm/chart/README.md similarity index 100% rename from examples/helm/chart/README.md rename to examples/300_helm/chart/README.md diff --git a/examples/helm/chart/templates/NOTES.txt b/examples/300_helm/chart/templates/NOTES.txt similarity index 100% rename from examples/helm/chart/templates/NOTES.txt rename to examples/300_helm/chart/templates/NOTES.txt diff --git a/examples/helm/chart/templates/_helpers.tpl b/examples/300_helm/chart/templates/_helpers.tpl similarity index 100% rename from examples/helm/chart/templates/_helpers.tpl rename to examples/300_helm/chart/templates/_helpers.tpl diff --git a/examples/helm/chart/templates/coherence.yaml b/examples/300_helm/chart/templates/coherence.yaml similarity index 100% rename from examples/helm/chart/templates/coherence.yaml rename to examples/300_helm/chart/templates/coherence.yaml diff --git a/examples/helm/chart/templates/hook.yaml b/examples/300_helm/chart/templates/hook.yaml similarity index 100% rename from examples/helm/chart/templates/hook.yaml rename to examples/300_helm/chart/templates/hook.yaml diff --git a/examples/helm/chart/values.yaml b/examples/300_helm/chart/values.yaml similarity index 100% rename from examples/helm/chart/values.yaml rename to examples/300_helm/chart/values.yaml diff --git a/docs/examples/800_istio.adoc b/examples/400_Istio/README.adoc similarity index 79% rename from docs/examples/800_istio.adoc rename to examples/400_Istio/README.adoc index ce5d8a738..4cc833083 100644 --- a/docs/examples/800_istio.adoc +++ b/examples/400_Istio/README.adoc @@ -5,11 +5,15 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// -= Istio Support += Using Coherence with Istio -== Istio Support +== Using Coherence with Istio -You can run the Coherence cluster and manage then using the Coherence Operator alongside Istio. Coherence clusters managed with the Coherence Operator 3.2.0 and later work with Istio 1.9.1 and later. 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. +You can run the Coherence cluster and manage then using the Coherence Operator alongside https://istio.io[Istio]. +Coherence clusters managed with the Coherence Operator 3.2.0 and later work with Istio 1.9.1 and later. +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. [IMPORTANT] ==== @@ -35,7 +39,7 @@ kubectl label namespace coherence istio-injection=enabled Istio Sidecar AutoInjection is done automatically when you label the coherence namespace with istio-injection. -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]. +After the namespace is labeled, you can install the operator using your preferred method in the Operator <>. After installed operator, use the following command to confirm the operator is running: @@ -94,7 +98,7 @@ You can see that 3 members in the cluster are running with 3 pods. 2/2 in READY === TLS -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: +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 certificate and key (e.g. server.crt and server.key) to be used by the Gateway: [source,bash] ---- @@ -160,7 +164,7 @@ kubectl apply -f tlsGateway.yaml -n coherence-example kubectl apply -f tlsVS.yaml -n coherence-example ---- -Then configure a Coherence*Extend client to connect to the proxy server via TLS protocol. Below is an example of a configuration of an Extend client using TLS port 8043 configured in the Gateway and server.jks created earlier in the example. +Then configure a Coherence*Extend client to connect to the proxy server via TLS protocol. Below is an example of a configuration of an Extend client using TLS port 8043 configured in the Gateway and server.jks created earlier in the example. client-cache-config.xml ---- @@ -194,7 +198,7 @@ client-cache-config.xml ... ---- -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: +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: [source,bash] ---- @@ -203,12 +207,12 @@ kubectl port-forward -n istio-system 8043:8043 === Prometheus -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. +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 Grafana. However, Coherence cluster traffic is not visible by Istio. === Traffic Visualization -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. +Istio provides traffic management capabilities, including the ability to visualize traffic in https://kiali.io[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. -image::../images/istioKiali.png[width=1024,height=512] +image::images/istioKiali.png[width=1024,height=512] To learn more, see https://istio.io/latest/docs/concepts/traffic-management/[Istio traffic management]. diff --git a/docs/images/istioKiali.png b/examples/400_Istio/images/istioKiali.png similarity index 100% rename from docs/images/istioKiali.png rename to examples/400_Istio/images/istioKiali.png diff --git a/docs/examples/900_demo.adoc b/examples/900_demo/README.adoc similarity index 75% rename from docs/examples/900_demo.adoc rename to examples/900_demo/README.adoc index a17d5e657..265a7eba4 100644 --- a/docs/examples/900_demo.adoc +++ b/examples/900_demo/README.adoc @@ -14,10 +14,9 @@ can run stand alone but can also be installed on the Coherence Operator. When installed using the Coherence Operator, the setup includes two Coherence Clusters, in the same Kubernetes cluster, which are configured with Active/Active Federation. -image::../images/coherence-demo.png[Service Details,width="950",align="center"] +image::images/coherence-demo.png[Service Details,width="950",align="center"] -image::../images/GitHub-Mark-64px.png[GitHub,width="32"] -Please see https://github.com/coherence-community/coherence-demo[The Coherence Demo GitHub project] for full instructions. +image:GitHub-Mark-32px.png[] Please see https://github.com/coherence-community/coherence-demo[The Coherence Demo GitHub project] for full instructions. diff --git a/examples/900_demo/images/GitHub-Mark-64px.png b/examples/900_demo/images/GitHub-Mark-64px.png new file mode 100644 index 000000000..182a1a3f7 Binary files /dev/null and b/examples/900_demo/images/GitHub-Mark-64px.png differ diff --git a/docs/images/coherence-demo.png b/examples/900_demo/images/coherence-demo.png similarity index 100% rename from docs/images/coherence-demo.png rename to examples/900_demo/images/coherence-demo.png diff --git a/examples/README.adoc b/examples/README.adoc index f1a28584a..dc2e2988d 100644 --- a/examples/README.adoc +++ b/examples/README.adoc @@ -1,13 +1,89 @@ -= Coherence Operator Examples +/////////////////////////////////////////////////////////////////////////////// -The examples provide demonstrations of how to accomplish common tasks. These examples are provided for educational and -demonstration purposes only; they are not intended to be used in production deployments or -to be depended upon to create production environments. + Copyright (c) 2021, Oracle and/or its affiliates. + Licensed under the Universal Permissive License v 1.0 as shown at + http://oss.oracle.com/licenses/upl. -== Table of Contents +/////////////////////////////////////////////////////////////////////////////// += Examples Overview -* <> +== Examples Overview -* <> +There are a number of examples which show you how to build and deploy applications for the Coherence Operator. -* <> +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for the examples is in the https://github.com/oracle/coherence-operator/tree/master/examples/[Coherence Operator GitHub] repository. +==== + +[PILLARS] +==== +[CARD] +.Hello World +[link=examples/020_hello_world/README.adoc] +-- +Deploying the most basic Coherence cluster using the Operator. +-- + +[CARD] +.Simple Coherence Image +[link=examples/015_simple_image/README.adoc] +-- +Building a simple Coherence image with JIB using Maven or Gradle. +-- +==== + +[PILLARS] +==== +[CARD] +.Deployment +[link=examples/020_deployment.adoc] +-- +This example showcases how to deploy Coherence applications using the Coherence Operator. +-- + +[CARD] +.TLS +[link=examples/090_tls/README.adoc] +-- +Securing Coherence clusters using TLS. +-- + +[CARD] +.Federation +[link=examples/100_federation/README.adoc] +-- +This is a simple Coherence federation example. The federation feature requires Coherence Grid Edition. +-- + +[CARD] +.Autoscaling +[link=examples/200_autoscaler/README.adoc] +-- +Scaling Coherence clusters using the horizontal Pod Autoscaler. +-- + +[CARD] +.Helm +[link=examples/300_helm/README.adoc] +-- +Manage Coherence resources using Helm. +-- + +[CARD] +.Istio +[link=examples/400_Istio/README.adoc] +-- +Istio Support +-- +==== + +[PILLARS] +==== +[CARD] +.Coherence Demo App +[link=examples/900_demo.adoc] +-- +Deploying the Coherence demo application. +-- +==== diff --git a/docs/examples/810_helm.adoc b/examples/no-operator/000_overview.adoc similarity index 84% rename from docs/examples/810_helm.adoc rename to examples/no-operator/000_overview.adoc index 7a3ba4494..75c13bd1a 100644 --- a/docs/examples/810_helm.adoc +++ b/examples/no-operator/000_overview.adoc @@ -5,8 +5,9 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// -= Manage Coherence using Helm + += Overview // DO NOT EDIT THIS FILE // This file imports the example README.adoc file. -include::../../examples/helm/README.adoc[] +include::README.adoc[lines=9..-1] diff --git a/examples/no-operator/01_simple_server/README.adoc b/examples/no-operator/01_simple_server/README.adoc index 90e7db64e..6cd7049fa 100644 --- a/examples/no-operator/01_simple_server/README.adoc +++ b/examples/no-operator/01_simple_server/README.adoc @@ -5,10 +5,17 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// += A Simple Coherence Cluster + == A Simple Coherence Cluster in Kubernetes This example shows how to deploy a simple Coherence cluster in Kubernetes manually, without using the Coherence Operator. +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for this example is in the https://github.com/oracle/coherence-operator/tree/master/examples/no-operator/01_simple_server[Coherence Operator GitHub] repository. +==== + *Prerequisites* This example assumes that you have already built the example server image. @@ -260,8 +267,8 @@ Map (?): cache test We should see output something like this: [source] ---- -2021-09-17 12:25:12.143/14.600 Oracle Coherence CE 21.06.1 (thread=com.tangosol.net.CacheFactory.main(), member=1): Loaded cache configuration from "file:/Users/jonathanknight/dev/Projects/GitOracle/coherence-operator-3.0/examples/no-operator/test-client/target/classes/client-cache-config.xml" -2021-09-17 12:25:12.207/14.664 Oracle Coherence CE 21.06.1 (thread=com.tangosol.net.CacheFactory.main(), member=1): Created cache factory com.tangosol.net.ExtensibleConfigurableCacheFactory +2021-09-17 12:25:12.143/14.600 Oracle Coherence CE 21.06.2 (thread=com.tangosol.net.CacheFactory.main(), member=1): Loaded cache configuration from "file:/Users/jonathanknight/dev/Projects/GitOracle/coherence-operator-3.0/examples/no-operator/test-client/target/classes/client-cache-config.xml" +2021-09-17 12:25:12.207/14.664 Oracle Coherence CE 21.06.2 (thread=com.tangosol.net.CacheFactory.main(), member=1): Created cache factory com.tangosol.net.ExtensibleConfigurableCacheFactory Cache Configuration: test SchemeName: remote diff --git a/examples/no-operator/02_metrics/README.adoc b/examples/no-operator/02_metrics/README.adoc index 3580fb034..c26e16c92 100644 --- a/examples/no-operator/02_metrics/README.adoc +++ b/examples/no-operator/02_metrics/README.adoc @@ -5,11 +5,18 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// += Enabling Coherence Metrics + == Enabling Coherence Metrics This example shows how to deploy a simple Coherence cluster in Kubernetes manually, and enabling the Pods in that cluster to expose a http endpoint to allow access to Coherence metrics. This example expands on the `StatefulSet` used in the first simple deployment example. +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for this example is in the https://github.com/oracle/coherence-operator/tree/master/examples/no-operator/02_metrics[Coherence Operator GitHub] repository. +==== + *Prerequisites* This example assumes that you have already built the example server image. @@ -138,9 +145,9 @@ curl -X GET http://127.0.0.1:9612/metrics/Coherence.Cluster.Size which will display something like this: [source,bash] ---- -vendor:coherence_cluster_size{cluster="storage", version="21.06.1"} 3 +vendor:coherence_cluster_size{cluster="storage", version="21.06.2"} 3 ---- -This displays the metric name in Prometheus format `vendor:coherence_cluster_size`, the metric labels `cluster="storage", version="21.06.1"` and the metric value, in this case `3` as there are three cluster members because we specified a replicas value of 3 in the `StatefulSet`. +This displays the metric name in Prometheus format `vendor:coherence_cluster_size`, the metric labels `cluster="storage", version="21.06.2"` and the metric value, in this case `3` as there are three cluster members because we specified a replicas value of 3 in the `StatefulSet`. We can also receive the same response as `json` by using either the accepted media type header `"Accept: application/json"`: [source,bash] @@ -156,7 +163,7 @@ curl -X GET http://127.0.0.1:9612/metrics/Coherence.Cluster.Size.json Both requests will display something like this: [source,bash] ---- -[{"name":"Coherence.Cluster.Size","tags":{"cluster":"storage","version":"21.06.1"},"scope":"VENDOR","value":3}] +[{"name":"Coherence.Cluster.Size","tags":{"cluster":"storage","version":"21.06.2"},"scope":"VENDOR","value":3}] ---- We have now verified that the `Pods` in the cluster are producing metrics. diff --git a/examples/no-operator/03_extend_tls/README.adoc b/examples/no-operator/03_extend_tls/README.adoc index a9f70b4c2..2e04d260a 100644 --- a/examples/no-operator/03_extend_tls/README.adoc +++ b/examples/no-operator/03_extend_tls/README.adoc @@ -5,17 +5,24 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// += Secure Coherence Extend with TLS + == Secure Coherence Extend with TLS This example shows how to deploy a simple Coherence cluster in Kubernetes manually, and secure the Extend endpoint using TLS. This example expands on the `StatefulSet` used in the first simple deployment example. +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for this example is in the https://github.com/oracle/coherence-operator/tree/master/examples/no-operator/03_extend_tls[Coherence Operator GitHub] repository. +==== + *Prerequisites* This example assumes that you have already built the example server image. There are a number of ways to use TLS to secure ingress in Kubernetes. We could use a load balancer `Service` and terminate TLS at the load balance, or we could use an add-on such as Istio to manage TLS ingress. Both of those approaches would require no changes to the Coherence server, as the server would not know TLS was being used. -The https://oracle.github.io/coherence-operator/docs/latest/#/docs/examples/010_overview[Coherence Operator Examples] +The https://oracle.github.io/coherence-operator/docs/latest/#/examples/010_overview[Coherence Operator Examples] contains examples of using TLS with Coherence and using Istio. The TLS example also shows how to use Kubernetes built in certificate management to create keys and certificates. In this example we are going to actually change the server to use TLS for its Extend endpoints. @@ -340,7 +347,7 @@ Map (?): cache test This will not throw an exception because the client is not using TLS so the server rejected the connection. [source] ---- -2021-09-17 18:19:39.182/12.090 Oracle Coherence CE 21.06.1 (thread=com.tangosol.net.CacheFactory.main(), member=1): Error while starting service "RemoteCache": com.tangosol.net.messaging.ConnectionException: could not establish a connection to one of the following addresses: [127.0.0.1:20000] +2021-09-17 18:19:39.182/12.090 Oracle Coherence CE 21.06.2 (thread=com.tangosol.net.CacheFactory.main(), member=1): Error while starting service "RemoteCache": com.tangosol.net.messaging.ConnectionException: could not establish a connection to one of the following addresses: [127.0.0.1:20000] at com.tangosol.coherence.component.util.daemon.queueProcessor.service.peer.initiator.TcpInitiator.openConnection(TcpInitiator.CDB:139) at com.tangosol.coherence.component.util.daemon.queueProcessor.service.peer.Initiator.ensureConnection(Initiator.CDB:11) at com.tangosol.coherence.component.net.extend.remoteService.RemoteCacheService.openChannel(RemoteCacheService.CDB:7) diff --git a/examples/no-operator/README.adoc b/examples/no-operator/README.adoc index 747db74f9..798434a64 100644 --- a/examples/no-operator/README.adoc +++ b/examples/no-operator/README.adoc @@ -5,68 +5,61 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// += Coherence in Kubernetes Without the Operator + == Coherence in Kubernetes Without the Operator Although this project is all about the Coherence Kubernetes Operator, there are occasions where using an Operator is not possible. For example, some corporate or cloud security policies ban the use of CRDs, or have very restrictive RBAC policies that ultimately make it impossible to run Operators that uses their own CRDs or require cluster roles (or even just namespace roles). - -This example shows how to run a simple Coherence cluster in Kubernetes manually. +These example shows how to run a Coherence clusters in Kubernetes manually. Obviously the features of the Operator such as safe scaling, safe rolling upgrades, etc. will not be available. -There are various parts to the example, each described below: +[NOTE] +==== +We really recommend that you try and use the Coherence Operator for managing Coherence clusters in Kubernetes. +It is possible to run the Operator with fewer RBAC permissions, for example without `ClusterRoles` and only using `Roles` restricted to a single namespace. The Operator can also run without installing its web-hooks. Ultimately though it requires the CRD to be installed, which could be done manually instead of allowing the Operator to install it. +If you really cannot change the minds of those dictating policies that mean you cannot use the Operator then these examples may be useful. +==== -=== Prerequisites +[TIP] +==== +image:GitHub-Mark-32px.png[] The complete source code for the examples is in the https://github.com/oracle/coherence-operator/tree/master/examples/no-operator/[Coherence Operator GitHub] repository. +==== +=== Prerequisites There are some common prerequisites used by all the examples. -==== The Server Image - -The `server-image/` directory contains a simple Maven project that builds an image containing a very simple Coherence application. -This application is nothing more than a cache configuration file that has an Extend proxy along with Coherence metrics and management over REST. We will use this image in the various examples we cover here. When we run the image it will start a simple storage enabled Coherence server. +* *The Server Image* -The server image Maven project, in the `server-image/` directory, uses the -https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin[JIB Maven plugin] -to build an image we can use in these examples. JIB is simple to use and configure and creates reasonably secure images based on distroless Java base images. These images contain the core Linux runtime and a JVM, there are no command line shells or other utilities to introduce security concerns. The down-side is that you cannot exec into a running container, but with the introduction of ephemeral containers in Kubernetes, this is not such an issue. +These examples use the image built in the <> example. +The image is nothing more than a cache configuration file that has an Extend proxy along with Coherence metrics and management over REST. +We will use this image in the various examples we cover here. When we run the image it will start a simple storage enabled Coherence server. -To create the server image run the following command from the `server-image/` directory: -[source,bash] ----- -mvn clean compile jib:dockerBuild ----- -The command above will create an image named `simple-coherence:1.0.0` which we use in the examples. - -==== The Test Client - -In the `test-client/` directory is a simple Maven project that we will use to run a simple Extend client. -This will allow us to show connectivity to our test cluster from outside of Kubernetes. - -To run the test client we can run this command from the `test-client/` directory: -[source,bash] ----- -mvn exec:java ----- -This will start a Coherence interactive console as an Extend client. -We can then run various commands to test Extend connectivity. +* *The Test Client* +In the <> directory is a simple Maven project that we will use to run a simple Extend client. == The Examples -There are a number of examples where we cover different configuration options and functionality. -Each example is in its own source directory with its own README instructions. - -|=== -|Directory |Description - -|`01_simple_server/` -|Run a simple Coherence storage enabled cluster as a `StatefulSet` and connect an Extend client to it. - -|`02_metrics/` -|Expands the simple storage enabled server to expose metrics that can be scraped by Prometheus. - -|`03_extend_tls/` -|Expands the simple storage enabled server to secure Extend using TLS. -|=== - - - - - +[PILLARS] +==== +[CARD] +.Simple Server +[link=examples/no-operator/01_simple_server/README.adoc] +-- +Run a simple Coherence storage enabled cluster as a StatefulSet and connect an Extend client to it. +-- + +[CARD] +.Simple Server with Metrics +[link=examples/no-operator/02_metrics/README.adoc] +-- +Expands the simple storage enabled server to expose metrics that can be scraped by Prometheus. +-- + +[CARD] +.Securing Extend with TLS +[link=examples/no-operator/03_extend_tls/README.adoc] +-- +Expands the simple storage enabled server to secure Extend using TLS. +-- +==== diff --git a/examples/no-operator/server-image/README.adoc b/examples/no-operator/server-image/README.adoc deleted file mode 100644 index 5359770f2..000000000 --- a/examples/no-operator/server-image/README.adoc +++ /dev/null @@ -1,24 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2021, Oracle and/or its affiliates. - Licensed under the Universal Permissive License v 1.0 as shown at - http://oss.oracle.com/licenses/upl. - -/////////////////////////////////////////////////////////////////////////////// -== Example Coherence Server Image - -The `examples/no-operator/server-image/` directory contains a simple Maven project that builds an image containing a very simple Coherence application. -This application is nothing more than a cache configuration file that has an Extend proxy along with Coherence metrics and management over REST. We will use this image in the various examples we cover here. When we run the image it will start a simple storage enabled Coherence server. - -The server image Maven project, in the `server-image/` directory, uses the -https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin[JIB Maven plugin] -to build an image we can use in these examples. JIB is simple to use and configure and creates reasonably secure images based on distroless Java base images. These images contain the core Linux runtime and a JVM, there are no command line shells or other utilities to introduce security concerns. The down-side is that you cannot exec into a running container, but with the introduction of ephemeral containers in Kubernetes, this is not such an issue. - -To create the server image run the following command from the `server-image/` directory: -[source,bash] ----- -mvn clean compile jib:dockerBuild ----- -The command above will create an image named `simple-coherence:1.0.0` which we use in some of the Non-Operator examples. - - diff --git a/examples/no-operator/test-client/README.adoc b/examples/no-operator/test-client/README.adoc index ac6e83ad2..8bb02d02c 100644 --- a/examples/no-operator/test-client/README.adoc +++ b/examples/no-operator/test-client/README.adoc @@ -5,6 +5,7 @@ http://oss.oracle.com/licenses/upl. /////////////////////////////////////////////////////////////////////////////// += Example Extend Client == Example Extend Client In the `examples/no-operator/test-client/` directory is a simple Maven project that we will use to run a simple Extend client. diff --git a/examples/no-operator/test-client/pom.xml b/examples/no-operator/test-client/pom.xml index 7805a4336..0a051b0a7 100644 --- a/examples/no-operator/test-client/pom.xml +++ b/examples/no-operator/test-client/pom.xml @@ -25,7 +25,7 @@ 8 - 21.06.1 + 21.06.2 ${project.basedir} diff --git a/examples/pom.xml b/examples/pom.xml index cf82cd921..8d4bda345 100644 --- a/examples/pom.xml +++ b/examples/pom.xml @@ -18,10 +18,24 @@ Oracle Coherence Operator Examples Parent - deployment - autoscaler - tls + 015_simple_image + 021_deployment + 200_autoscaler + 090_tls + + + + + com.google.cloud.tools + jib-maven-plugin + 3.1.4 + + true + + + + diff --git a/java/pom.xml b/java/pom.xml index d2b395dd0..879d9baac 100644 --- a/java/pom.xml +++ b/java/pom.xml @@ -40,7 +40,7 @@ 8 - 21.06.1 + 21.06.2 com.oracle.coherence.ce ${coherence.version} @@ -84,7 +84,7 @@ 3.0.0 2.0.0-M3 3.1.1 - 3.1.1 + 3.1.4 3.1.1 3.7.0 3.2.0