[flink-kubernetes-operator] branch main updated: [FLINK-27097] Document custom validator implementations

[wa...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wangyang0918 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-kubernetes-operator.git


The following commit(s) were added to refs/heads/main by this push:
     new de75dcd  [FLINK-27097] Document custom validator implementations
de75dcd is described below

commit de75dcdc51ef3ee8e0477a8799ffe000088546f1
Author: SteNicholas <pr...@163.com>
AuthorDate: Wed May 4 14:07:28 2022 +0800

    [FLINK-27097] Document custom validator implementations
    
    This closes #192.
---
 docs/content/docs/operations/validator.md | 91 +++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/docs/content/docs/operations/validator.md b/docs/content/docs/operations/validator.md
new file mode 100644
index 0000000..587cc63
--- /dev/null
+++ b/docs/content/docs/operations/validator.md
@@ -0,0 +1,91 @@
+---
+title: "Validator"
+weight: 5
+type: docs
+aliases:
+- /operations/validator.html
+---
+<!--
+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.
+-->
+
+# Custom `FlinkResourceValidator` implementation
+
+`FlinkResourceValidator`, an interface for validating the resources of `FlinkDeployment` and `FlinkSessionJob`,  is a pluggable component based on the [Plugins](https://nightlies.apache.org/flink/flink-docs-master/docs/deployment/filesystems/plugins) mechanism. During development, we can customize the implementation of `FlinkResourceValidator` and make sure to retain the service definition in `META-INF/services`. 
+The following steps demonstrate how to develop and use a custom validator.
+
+1. Implement `FlinkResourceValidator` interface:
+    ```java
+    package org.apache.flink.kubernetes.operator.validation;
+   
+    import org.apache.flink.kubernetes.operator.crd.FlinkDeployment;
+    import org.apache.flink.kubernetes.operator.crd.FlinkSessionJob;
+   
+    import java.util.Optional;
+   
+    /** Custom validator implementation of {@link FlinkResourceValidator}. */
+    public class CustomValidator implements FlinkResourceValidator {
+   
+        @Override
+        public Optional<String> validateDeployment(FlinkDeployment deployment) {
+            if (deployment.getSpec().getFlinkVersion() == null) {
+              return Optional.of("Flink Version must be defined.");
+            }
+            return Optional.empty();
+        }
+   
+        @Override
+        public Optional<String> validateSessionJob(
+                 FlinkSessionJob sessionJob, Optional<FlinkDeployment> session) {
+            if (sessionJob.getSpec().getJob() == null) {
+              return Optional.of("The job spec should not be empty");
+            }
+            return Optional.empty();
+        }
+    }
+    ```
+
+2. Create service definition file `org.apache.flink.kubernetes.operator.validation.FlinkResourceValidator` in `META-INF/services`.   With custom `FlinkResourceValidator` implementation, the service definition describes as follows:
+    ```text
+    org.apache.flink.kubernetes.operator.validation.CustomValidator
+    ```
+
+3. Use the Maven tool to package the project and generate the custom validator JAR.
+
+4. Create Dockerfile to build a custom image from the `apache/flink-kubernetes-operator` official image and copy the generated JAR to custom validator plugin directory. 
+    `/opt/flink/plugins` is the value of `FLINK_PLUGINS_DIR` environment variable in the flink-kubernetes-operator helm chart. The structure of custom validator directory under `/opt/flink/plugins` is as follows:
+    ```text
+    /opt/flink/plugins
+        ├── custom-validator
+        │   ├── custom-validator.jar
+        └── ...
+    ```
+    
+    With the custom validator directory location, the Dockerfile is defined as follows:
+    ```shell script
+    FROM apache/flink-kubernetes-operator
+    ENV FLINK_PLUGINS_DIR=/opt/flink/plugins
+    ENV CUSTOM_VALIDATOR_DIR=custom-validator
+    RUN mkdir $FLINK_PLUGINS_DIR/$CUSTOM_VALIDATOR_DIR
+    COPY custom-validator.jar $FLINK_PLUGINS_DIR/$CUSTOM_VALIDATOR_DIR/
+    ```
+
+5. Install the flink-kubernetes-operator helm chart with the custom image and verify the `deploy/flink-kubernetes-operator` log has:
+    ```text
+    2022-05-04 14:01:46,551 o.a.f.k.o.u.FlinkUtils         [INFO ] Discovered resource validator from plugin directory[/opt/flink/plugins]: org.apache.flink.kubernetes.operator.validation.CustomValidator.
+    ```