You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by mm...@apache.org on 2021/01/21 18:38:30 UTC
[ignite] branch master updated: IGNITE-13796 Update documentation
and examples for the kubernetes module (#8532)
This is an automated email from the ASF dual-hosted git repository.
mmuzaf pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/master by this push:
new 8f06256 IGNITE-13796 Update documentation and examples for the kubernetes module (#8532)
8f06256 is described below
commit 8f06256453fb4099f759f3ce4f0f8b7fafeb93e7
Author: Maksim Timonin <ti...@gmail.com>
AuthorDate: Thu Jan 21 21:38:09 2021 +0300
IGNITE-13796 Update documentation and examples for the kubernetes module (#8532)
---
.../org/apache/ignite/snippets/JavaThinClient.java | 24 +++++++-
.../java/org/apache/ignite/snippets/k8s/K8s.java | 21 +++++++
docs/_docs/code-snippets/k8s/service.yaml | 8 +--
.../k8s/stateful/node-configuration.xml | 12 ++--
.../k8s/stateless/node-configuration.xml | 8 ++-
docs/_docs/includes/partition-awareness.adoc | 2 +-
.../kubernetes/generic-configuration.adoc | 14 ++++-
docs/_docs/thin-clients/java-thin-client.adoc | 17 +++++-
examples/pom.xml | 6 ++
.../client/ClientKubernetesPutGetExample.java | 70 ++++++++++++++++++++++
modules/kubernetes/{DEVNOTES.txt => DEVNOTES.md} | 6 +-
modules/kubernetes/{README.txt => README.md} | 0
modules/kubernetes/config/Dockerfile | 18 +++---
.../config/example-kube-persistence-and-wal.xml | 9 ++-
.../kubernetes/config/example-kube-persistence.xml | 9 ++-
modules/kubernetes/config/example-kube-rbac.xml | 10 +++-
modules/kubernetes/config/example-kube.xml | 5 +-
parent/pom.xml | 1 +
18 files changed, 204 insertions(+), 36 deletions(-)
diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/JavaThinClient.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/JavaThinClient.java
index 5c3a855..a6bdf2b 100644
--- a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/JavaThinClient.java
+++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/JavaThinClient.java
@@ -83,7 +83,7 @@ public class JavaThinClient {
// Start a node
Ignite ignite = Ignition.start(cfg);
// end::clusterConfiguration[]
-
+
ignite.close();
}
@@ -318,7 +318,7 @@ public class JavaThinClient {
// end::results-to-map[]
}
-
+
void veiwsystemview() {
//tag::system-views[]
ClientConfiguration cfg = new ClientConfiguration().setAddresses("127.0.0.1:10800");
@@ -360,6 +360,26 @@ public class JavaThinClient {
//end::partition-awareness[]
}
+ void clientAddressFinder() throws Exception {
+ //tag::client-address-finder[]
+ ClientAddressFinder finder = () -> {
+ String[] dynamicServerAddresses = fetchServerAddresses();
+
+ return dynamicServerAddresses;
+ };
+
+ ClientConfiguration cfg = new ClientConfiguration()
+ .setAddressFinder(finder)
+ .setPartitionAwarenessEnabled(true);
+
+ try (IgniteClient client = Ignition.startClient(cfg)) {
+ ClientCache<Integer, String> cache = client.cache("myCache");
+ // Put, get, or remove data from the cache...
+ } catch (ClientException e) {
+ System.err.println(e.getMessage());
+ }
+ //end::client-address-finder[]
+ }
@Test
void cientCluster() throws Exception {
diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/k8s/K8s.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/k8s/K8s.java
index 7068076..856ac0e 100644
--- a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/k8s/K8s.java
+++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/k8s/K8s.java
@@ -37,4 +37,25 @@ public class K8s {
client.close();
// end::connectThinClient[]
}
+
+ public static void connectThinClientWithConfiguration() throws Exception {
+ // tag::connectThinClientWithKubernetesConfiguration[]
+ KubernetesConnectionConfiguration kcfg = new KubernetesConnectionConfiguration();
+ kcfg.setNamespace("ignite");
+ kcfg.setServiceName("ignite-service");
+
+ ClientConfiguration ccfg = new ClientConfiguration();
+ ccfg.setAddressesFinder(new ThinClientKubernetesAddressFinder(kcfg));
+
+ IgniteClient client = Ignition.startClient(cfg);
+
+ ClientCache<Integer, String> cache = client.getOrCreateCache("test_cache");
+
+ cache.put(1, "first test value");
+
+ System.out.println(cache.get(1));
+
+ client.close();
+ // end::connectThinClientWithKubernetesConfiguration[]
+ }
}
diff --git a/docs/_docs/code-snippets/k8s/service.yaml b/docs/_docs/code-snippets/k8s/service.yaml
index 6858bb7..cb7983e 100644
--- a/docs/_docs/code-snippets/k8s/service.yaml
+++ b/docs/_docs/code-snippets/k8s/service.yaml
@@ -16,10 +16,10 @@
#tag::config-block[]
apiVersion: v1
kind: Service
-metadata:
- # The name must be equal to TcpDiscoveryKubernetesIpFinder.serviceName
+metadata:
+ # The name must be equal to KubernetesConnectionConfiguration.serviceName
name: ignite-service
- # The name must be equal to TcpDiscoveryKubernetesIpFinder.namespace
+ # The name must be equal to KubernetesConnectionConfiguration.namespace
namespace: ignite
labels:
app: ignite
@@ -34,7 +34,7 @@ spec:
targetPort: 10800
# Optional - remove 'sessionAffinity' property if the cluster
# and applications are deployed within Kubernetes
- # sessionAffinity: ClientIP
+ # sessionAffinity: ClientIP
selector:
# Must be equal to the label set for pods.
app: ignite
diff --git a/docs/_docs/code-snippets/k8s/stateful/node-configuration.xml b/docs/_docs/code-snippets/k8s/stateful/node-configuration.xml
index d4d6292..562fb23 100644
--- a/docs/_docs/code-snippets/k8s/stateful/node-configuration.xml
+++ b/docs/_docs/code-snippets/k8s/stateful/node-configuration.xml
@@ -16,8 +16,8 @@
limitations under the License.
-->
<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://www.springframework.org/schema/beans
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<!-- tag::config-block[] -->
@@ -43,8 +43,12 @@
<bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi">
<property name="ipFinder">
<bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.kubernetes.TcpDiscoveryKubernetesIpFinder">
- <property name="namespace" value="ignite"/>
- <property name="serviceName" value="ignite-service"/>
+ <constructor-arg>
+ <bean class="org.apache.ignite.kubernetes.configuration.KubernetesConnectionConfiguration">
+ <property name="namespace" value="default" />
+ <property name="serviceName" value="ignite" />
+ </bean>
+ </constructor-arg>
</bean>
</property>
</bean>
diff --git a/docs/_docs/code-snippets/k8s/stateless/node-configuration.xml b/docs/_docs/code-snippets/k8s/stateless/node-configuration.xml
index d0f56f0..3464595 100644
--- a/docs/_docs/code-snippets/k8s/stateless/node-configuration.xml
+++ b/docs/_docs/code-snippets/k8s/stateless/node-configuration.xml
@@ -28,8 +28,12 @@
<bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi">
<property name="ipFinder">
<bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.kubernetes.TcpDiscoveryKubernetesIpFinder">
- <property name="namespace" value="ignite"/>
- <property name="serviceName" value="ignite-service"/>
+ <constructor-arg>
+ <bean class="org.apache.ignite.kubernetes.configuration.KubernetesConnectionConfiguration">
+ <property name="namespace" value="default" />
+ <property name="serviceName" value="ignite" />
+ </bean>
+ </constructor-arg>
</bean>
</property>
</bean>
diff --git a/docs/_docs/includes/partition-awareness.adoc b/docs/_docs/includes/partition-awareness.adoc
index 1d1389e..8358e9c 100644
--- a/docs/_docs/includes/partition-awareness.adoc
+++ b/docs/_docs/includes/partition-awareness.adoc
@@ -30,7 +30,7 @@ image::images/partitionawareness02.png[With Partition Awareness]
[WARNING]
====
[discrete]
-Note that presently you need to provide addresses of all the server nodes in the connection properties.
+Note that for non-Java clients presently you need to provide addresses of all the server nodes in the connection properties.
This also means that if a new server node joins the cluster, you should add the server's address to the connection properties and reconnect the thin client.
Otherwise, the thin client will not be able to send direct requests to this server.
This limitation is planned to be addressed before the GA release of the feature.
diff --git a/docs/_docs/installation/kubernetes/generic-configuration.adoc b/docs/_docs/installation/kubernetes/generic-configuration.adoc
index 3dc9f3f..6e6724b 100644
--- a/docs/_docs/installation/kubernetes/generic-configuration.adoc
+++ b/docs/_docs/installation/kubernetes/generic-configuration.adoc
@@ -146,7 +146,7 @@ include::{configDir}/stateful/node-configuration.xml[tag=config-block]
--
-The `namespace` and `serviceName` properties of the IP finder must be the same as specified in the <<Creating Service,service configuration>>.
+The `namespace` and `serviceName` properties of the IP finder configuration must be the same as specified in the <<Creating Service,service configuration>>.
Add other properties as required for your use case.
To create the ConfigMap, run the following command in the directory with the `node-configuration.xml` file.
@@ -388,6 +388,18 @@ Note that we use the external IP address (LoadBalancer Ingress) of the service.
include::{javaFile}[tags=connectThinClient, indent=0]
----
+== Partition Awareness
+
+include::../../includes/partition-awareness.adoc[]
+
+To enable the partition awareness feature within scaling Kubernetes enviroment, one should start a client within the cluster and configure it with `KubernetesConnectionConfiguration`.
+In this case, a client can connect to every pod in a cluster.
+
+[source, java]
+----
+include::{javaFile}[tags=connectThinClientWithKubernetesConfiguration, indent=0]
+----
+
=== Connecting to REST API
Connect to the cluster's REST API as follows:
diff --git a/docs/_docs/thin-clients/java-thin-client.adoc b/docs/_docs/thin-clients/java-thin-client.adoc
index 81f1a86..e77cf9c 100644
--- a/docs/_docs/thin-clients/java-thin-client.adoc
+++ b/docs/_docs/thin-clients/java-thin-client.adoc
@@ -86,6 +86,22 @@ The following code sample illustrates how to use the partition awareness feature
include::{sourceCodeFile}[tag=partition-awareness,indent=0]
----
+If a list of server nodes is dynamically changing or scaling, then it is possible to configure the connection with custom implementation of `ClientAddressFinder`. It should provide a number of current server addresses every time a client asks for them.
+The following code sample illustrates how to use it.
+
+[source, java]
+----
+include::{sourceCodeFile}[tag=client-address-finder,indent=0]
+----
+
+The code snippet shows how an example implementation might look like if you want clients to retrieve server addresses dynamically.
+
+* The `ClientAddressFinder` is a functional interface that provides the only method `getAddresses()`.
+* The `fetchServerAddress()` is a custom function that dynamically provides server addresses.
+* Configure client with `ClientConfiguration.setAddressFinder(finder)`.
+
+Also, you can check a real example of the interface implementation. `ThinClientKubernetesAddressFinder` is created to handle scalable Kubernetes environment.
+
== Using Key-Value API
The Java thin client supports most of the key-value operations available in the thick client.
@@ -326,4 +342,3 @@ Configure link:security/authentication[authentication on the cluster side] and p
include::{sourceCodeFile}[tag=client-authentication,indent=0]
-------------------------------------------------------------------------------
-
diff --git a/examples/pom.xml b/examples/pom.xml
index 19e8962..38eb35b 100644
--- a/examples/pom.xml
+++ b/examples/pom.xml
@@ -139,6 +139,12 @@
</dependency>
<dependency>
+ <groupId>org.apache.ignite</groupId>
+ <artifactId>ignite-kubernetes</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+
+ <dependency>
<groupId>commons-cli</groupId>
<artifactId>commons-cli</artifactId>
<version>1.2</version>
diff --git a/examples/src/main/java/org/apache/ignite/examples/client/ClientKubernetesPutGetExample.java b/examples/src/main/java/org/apache/ignite/examples/client/ClientKubernetesPutGetExample.java
new file mode 100644
index 0000000..b775176
--- /dev/null
+++ b/examples/src/main/java/org/apache/ignite/examples/client/ClientKubernetesPutGetExample.java
@@ -0,0 +1,70 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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
+ *
+ * http://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.
+ */
+
+package org.apache.ignite.examples.client;
+
+import org.apache.ignite.Ignition;
+import org.apache.ignite.client.ClientCache;
+import org.apache.ignite.client.IgniteClient;
+import org.apache.ignite.client.ThinClientKubernetesAddressFinder;
+import org.apache.ignite.configuration.ClientConfiguration;
+import org.apache.ignite.examples.model.Address;
+import org.apache.ignite.kubernetes.configuration.KubernetesConnectionConfiguration;
+
+/**
+ * Demonstrates how to use Ignite thin client within the Kubernetes cluster using KubernetesConnectionConfiguration.
+ * <p>
+ * Prerequisites:
+ * <ul>
+ * <li>Running Ignite Kubernetes cluster. Check modules/kubernetes/DEVNOTES.md as an example of how to run a cluster locally.</li>
+ * <li>A thin client application should be run within the cluster to have access to Ignite nodes pods.</li>
+ * <li>KubernetesConnectionConfiguration must be in sync with the Ignite nodes configuration.</li>
+ * </ul>
+ * </p>
+ */
+public class ClientKubernetesPutGetExample {
+ /** Entry point. */
+ public static void main(String[] args) throws Exception {
+ KubernetesConnectionConfiguration kcfg = new KubernetesConnectionConfiguration();
+ kcfg.setNamespace("ignite");
+
+ ClientConfiguration cfg = new ClientConfiguration();
+ cfg.setAddressesFinder(new ThinClientKubernetesAddressFinder(kcfg));
+
+ try (IgniteClient igniteClient = Ignition.startClient(cfg)) {
+ System.out.println();
+ System.out.println(">>> Thin client put-get example started.");
+
+ final String CACHE_NAME = "put-get-example";
+
+ ClientCache<Integer, Address> cache = igniteClient.getOrCreateCache(CACHE_NAME);
+
+ System.out.format(">>> Created cache [%s].\n", CACHE_NAME);
+
+ Integer key = 1;
+ Address val = new Address("1545 Jackson Street", 94612);
+
+ cache.put(key, val);
+
+ System.out.format(">>> Saved [%s] in the cache.\n", val);
+
+ Address cachedVal = cache.get(key);
+
+ System.out.format(">>> Loaded [%s] from the cache.\n", cachedVal);
+ }
+ }
+}
diff --git a/modules/kubernetes/DEVNOTES.txt b/modules/kubernetes/DEVNOTES.md
similarity index 91%
rename from modules/kubernetes/DEVNOTES.txt
rename to modules/kubernetes/DEVNOTES.md
index a7440e4..06878a3 100644
--- a/modules/kubernetes/DEVNOTES.txt
+++ b/modules/kubernetes/DEVNOTES.md
@@ -31,10 +31,10 @@ Create a folder for all the files to be placed in the Docker image and copy the
- Apache Ignite binary in a zip form built at the step above.
- Dockerfile from `ignite-kubernetes/config/Dockerfile`.
- Ignite configuration with enabled Kubernetes IP finder from `ignite-kubernetes/config/example-kube.xml`.
- - The executable file that will start an Ignite node process from `ignite-kubernetes/config/run.sh`
+ - The executable file that starts the Ignite node process from `ignite-kubernetes/config/run.sh`
-Go to the folder and execute a command below to prepare the image:
- docker build -t ignite-kube:v1 .
+To prepare the image, navigate to the folder and execute the following command:
+ docker build -t ignite-kube:v1 --build-arg IGNITE_VERSION=2.10.0-SNAPSHOT .
Creating containerized Ignite pods and Ignite lookup service
============================================================
diff --git a/modules/kubernetes/README.txt b/modules/kubernetes/README.md
similarity index 100%
rename from modules/kubernetes/README.txt
rename to modules/kubernetes/README.md
diff --git a/modules/kubernetes/config/Dockerfile b/modules/kubernetes/config/Dockerfile
index 13114b2..f920251 100644
--- a/modules/kubernetes/config/Dockerfile
+++ b/modules/kubernetes/config/Dockerfile
@@ -18,16 +18,19 @@
# Use Java 8 image as default one.
FROM openjdk:8
+# Set Apache Ignite configuration file name.
+ARG IGNITE_CFG_XML="example-kube.xml"
+
# Set Apache Ignite version.
-ENV IGNITE_VERSION 2.0.0-SNAPSHOT
+ARG IGNITE_VERSION="2.0.0"
# Set IGNITE_HOME variable.
ENV IGNITE_HOME /opt/ignite/apache-ignite-${IGNITE_VERSION}-bin
-# Setting a path to an Apache Ignite configuration file. Used by run.sh script below.
-ENV CONFIG_URI ${IGNITE_HOME}/config/example-kube.xml
+# Set a path to the Apache Ignite configuration file. Use the run.sh script below:
+ENV CONFIG_URI ${IGNITE_HOME}/config/$IGNITE_CFG_XML
-# Make sure kubernetes lib is copied to 'libs' folder.
+# Make sure the Kubernetes lib is copied to the 'libs' folder.
ENV OPTION_LIBS ignite-kubernetes
# Disabling quiet mode.
@@ -50,13 +53,12 @@ RUN rm apache-ignite-${IGNITE_VERSION}-bin.zip
COPY ./run.sh $IGNITE_HOME/
RUN chmod +x $IGNITE_HOME/run.sh
-# Copying the configuration.
-COPY ./example-kube.xml $IGNITE_HOME/config
+# Copy the configuration.
+COPY ./$IGNITE_CFG_XML $IGNITE_HOME/config
-# Starting an Apache Ignite node.
+# Start an Apache Ignite node.
CMD $IGNITE_HOME/run.sh
# Exposing the ports.
EXPOSE 11211 47100 47500 49112
-
diff --git a/modules/kubernetes/config/example-kube-persistence-and-wal.xml b/modules/kubernetes/config/example-kube-persistence-and-wal.xml
index 8f27b9b..04cd813 100644
--- a/modules/kubernetes/config/example-kube-persistence-and-wal.xml
+++ b/modules/kubernetes/config/example-kube-persistence-and-wal.xml
@@ -67,10 +67,15 @@
Enables Kubernetes IP finder and setting custom namespace and service names.
-->
<bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.kubernetes.TcpDiscoveryKubernetesIpFinder">
- <property name="namespace" value="ignite"/>
+ <constructor-arg>
+ <bean class="org.apache.ignite.kubernetes.configuration.KubernetesConnectionConfiguration">
+ <!-- Assumed that you have RBAC configured and `ignite` namespace created for it. -->
+ <property name="namespace" value="ignite" />
+ </bean>
+ </constructor-arg>
</bean>
</property>
</bean>
</property>
</bean>
-</beans>
\ No newline at end of file
+</beans>
diff --git a/modules/kubernetes/config/example-kube-persistence.xml b/modules/kubernetes/config/example-kube-persistence.xml
index d83f721..8425b57 100644
--- a/modules/kubernetes/config/example-kube-persistence.xml
+++ b/modules/kubernetes/config/example-kube-persistence.xml
@@ -47,10 +47,15 @@
Enables Kubernetes IP finder and setting custom namespace and service names.
-->
<bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.kubernetes.TcpDiscoveryKubernetesIpFinder">
- <property name="namespace" value="ignite"/>
+ <constructor-arg>
+ <bean class="org.apache.ignite.kubernetes.configuration.KubernetesConnectionConfiguration">
+ <!-- Assumed that you have RBAC configured and `ignite` namespace created for it. -->
+ <property name="namespace" value="ignite" />
+ </bean>
+ </constructor-arg>
</bean>
</property>
</bean>
</property>
</bean>
-</beans>
\ No newline at end of file
+</beans>
diff --git a/modules/kubernetes/config/example-kube-rbac.xml b/modules/kubernetes/config/example-kube-rbac.xml
index 7ab94da..d7f8c8d 100644
--- a/modules/kubernetes/config/example-kube-rbac.xml
+++ b/modules/kubernetes/config/example-kube-rbac.xml
@@ -36,11 +36,15 @@
Enables Kubernetes IP finder with default settings.
-->
<bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.kubernetes.TcpDiscoveryKubernetesIpFinder">
- <!-- Assumed that you have RBAC configured and `ignite` namespace created for it. -->
- <property name="namespace" value="ignite"/>
+ <constructor-arg>
+ <bean class="org.apache.ignite.kubernetes.configuration.KubernetesConnectionConfiguration">
+ <!-- Assumed that you have RBAC configured and `ignite` namespace created for it. -->
+ <property name="namespace" value="ignite" />
+ </bean>
+ </constructor-arg>
</bean>
</property>
</bean>
</property>
</bean>
-</beans>
\ No newline at end of file
+</beans>
diff --git a/modules/kubernetes/config/example-kube.xml b/modules/kubernetes/config/example-kube.xml
index 2565174..884ea77 100644
--- a/modules/kubernetes/config/example-kube.xml
+++ b/modules/kubernetes/config/example-kube.xml
@@ -35,10 +35,9 @@
<!--
Enables Kubernetes IP finder with default settings.
-->
- <bean
- class="org.apache.ignite.spi.discovery.tcp.ipfinder.kubernetes.TcpDiscoveryKubernetesIpFinder"/>
+ <bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.kubernetes.TcpDiscoveryKubernetesIpFinder" />
</property>
</bean>
</property>
</bean>
-</beans>
\ No newline at end of file
+</beans>
diff --git a/parent/pom.xml b/parent/pom.xml
index 625d70a..ab73a51 100644
--- a/parent/pom.xml
+++ b/parent/pom.xml
@@ -864,6 +864,7 @@
<exclude>**/*README*.txt</exclude><!--readme files-->
<exclude>**/*README*.md</exclude><!--readme files-->
<exclude>**/*CONTRIBUTING*.md</exclude><!--readme files-->
+ <exclude>**/*DEVNOTES*.md</exclude><!--readme files-->
<exclude>**/*index*.md</exclude><!--readme files-->
<exclude>**/*.timestamp</exclude><!--tmp-files-->
<exclude>**/*.iml</exclude><!--IDEA files-->