Skip to content

Commit 9099abd

Browse files
Dennis-MirceaDennis-Mircea
authored
[FLINK-39501] Logback Support in Flink Kubernetes Operator
1 parent 90a7faf commit 9099abd

19 files changed

Lines changed: 631 additions & 21 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,3 +235,24 @@ jobs:
235235
flink-version: ${{ matrix.flink-version }}
236236
test: ${{ matrix.test }}
237237
mode: ${{ matrix.mode }}
238+
e2e_logging:
239+
name: Logging framework tests
240+
needs: e2e_smoke_test
241+
strategy:
242+
matrix:
243+
flink-version:
244+
- "v2_2"
245+
- "v2_1"
246+
- "v2_0"
247+
- "v1_20"
248+
mode:
249+
- "native"
250+
- "standalone"
251+
test:
252+
- test_logback_logging.sh
253+
uses: ./.github/workflows/e2e.yaml
254+
with:
255+
java-version: 17
256+
flink-version: ${{ matrix.flink-version }}
257+
test: ${{ matrix.test }}
258+
mode: ${{ matrix.mode }}

‎.github/workflows/e2e.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,9 @@ jobs:
7878
if [[ "${{ inputs.test }}" == "test_dynamic_config.sh" ]]; then
7979
sed -i "s/flink-conf.yaml: |+/config.yaml: |+/" helm/flink-kubernetes-operator/values.yaml
8080
fi
81+
if [[ "${{ inputs.test }}" == "test_logback_logging.sh" ]]; then
82+
sed -i 's/framework: "log4j2"/framework: "logback"/' helm/flink-kubernetes-operator/values.yaml
83+
fi
8184
helm --debug install flink-kubernetes-operator -n ${{ inputs.namespace }} helm/flink-kubernetes-operator --set image.repository=flink-kubernetes-operator --set image.tag=ci-latest ${{ steps.namespace-creator.outputs.EXTRA_HELM_INSTALL_ARGS }}
8285
kubectl wait --for=condition=Available --timeout=120s -n ${{ inputs.namespace }} deploy/flink-kubernetes-operator
8386
kubectl get pods -n ${{ inputs.namespace }}

‎Dockerfile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,8 @@ ENV WEBHOOK_JAR=flink-kubernetes-webhook-$OPERATOR_VERSION-shaded.jar
4444
ENV KUBERNETES_STANDALONE_JAR=flink-kubernetes-standalone-$OPERATOR_VERSION.jar
4545

4646
ENV OPERATOR_LIB=$FLINK_HOME/operator-lib
47-
RUN mkdir -p $OPERATOR_LIB
47+
ENV OPERATOR_LOG=$FLINK_HOME/log
48+
RUN mkdir -p $OPERATOR_LIB $OPERATOR_LOG/log4j $OPERATOR_LOG/logback
4849

4950
WORKDIR /flink-kubernetes-operator
5051
RUN groupadd --system --gid=9999 flink && \
@@ -56,6 +57,8 @@ COPY --chown=flink:flink --from=build /app/flink-kubernetes-operator/target/$OPE
5657
COPY --chown=flink:flink --from=build /app/flink-kubernetes-webhook/target/$WEBHOOK_JAR .
5758
COPY --chown=flink:flink --from=build /app/flink-kubernetes-standalone/target/$KUBERNETES_STANDALONE_JAR .
5859
COPY --chown=flink:flink --from=build /app/flink-kubernetes-operator/target/plugins $FLINK_HOME/plugins
60+
COPY --chown=flink:flink --from=build /app/flink-kubernetes-operator/target/log4j/ $FLINK_HOME/log/log4j/
61+
COPY --chown=flink:flink --from=build /app/flink-kubernetes-operator/target/logback/ $FLINK_HOME/log/logback/
5962
COPY --chown=flink:flink --from=build /app/tools/license/licenses-output/NOTICE .
6063
COPY --chown=flink:flink --from=build /app/tools/license/licenses-output/licenses ./licenses
6164
COPY --chown=flink:flink --from=build /app/LICENSE ./LICENSE

‎docker-entrypoint.sh‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,19 +43,29 @@ maybe_enable_jemalloc() {
4343

4444
maybe_enable_jemalloc
4545

46+
# Select the logging framework JARs to put on the classpath.
47+
# Supported values: "log4j2" (default), "logback".
48+
OPERATOR_LOG=${FLINK_HOME:-/opt/flink}/log
49+
LOGGING_FRAMEWORK="${LOGGING_FRAMEWORK:-log4j2}"
50+
if [ "$LOGGING_FRAMEWORK" = "logback" ]; then
51+
LOG_CLASSPATH="$OPERATOR_LOG/logback/*"
52+
else
53+
LOG_CLASSPATH="$OPERATOR_LOG/log4j/*"
54+
fi
55+
4656
if [ "$1" = "help" ]; then
4757
printf "Usage: $(basename "$0") (operator|webhook)\n"
4858
printf " Or $(basename "$0") help\n\n"
4959
exit 0
5060
elif [ "$1" = "operator" ]; then
5161
echo "Starting Operator"
5262

53-
exec java -cp "./$KUBERNETES_STANDALONE_JAR:./$OPERATOR_JAR:$OPERATOR_LIB/*" $LOG_CONFIG $JVM_ARGS org.apache.flink.kubernetes.operator.FlinkOperator
63+
exec java -cp "./$KUBERNETES_STANDALONE_JAR:./$OPERATOR_JAR:$LOG_CLASSPATH:$OPERATOR_LIB/*" $LOG_CONFIG $JVM_ARGS org.apache.flink.kubernetes.operator.FlinkOperator
5464
elif [ "$1" = "webhook" ]; then
5565
echo "Starting Webhook"
5666

5767
# Adds the operator shaded jar on the classpath when the webhook starts
58-
exec java -cp "./$KUBERNETES_STANDALONE_JAR:./$OPERATOR_JAR:./$WEBHOOK_JAR:$OPERATOR_LIB/*" $LOG_CONFIG $JVM_ARGS org.apache.flink.kubernetes.operator.admission.FlinkOperatorWebhook
68+
exec java -cp "./$KUBERNETES_STANDALONE_JAR:./$OPERATOR_JAR:./$WEBHOOK_JAR:$LOG_CLASSPATH:$OPERATOR_LIB/*" $LOG_CONFIG $JVM_ARGS org.apache.flink.kubernetes.operator.admission.FlinkOperatorWebhook
5969
fi
6070

6171
args=("${args[@]}")

‎docs/content.zh/docs/operations/helm.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,8 @@ The configurable parameters of the Helm chart and which default values as detail
7676
| defaultConfiguration.flink-conf.yaml | The default configuration of flink-conf.yaml. | kubernetes.operator.metrics.reporter.slf4j.factory.class: org.apache.flink.metrics.slf4j.Slf4jReporterFactory<br/>kubernetes.operator.metrics.reporter.slf4j.interval: 5 MINUTE<br/>kubernetes.operator.reconcile.interval: 15 s<br/>kubernetes.operator.observer.progress-check.interval: 5 s |
7777
| defaultConfiguration.log4j-console.properties | The default configuration of log4j-console.properties. | |
7878
| defaultConfiguration.log4j-operator.properties | The default configuration of log4j-operator.properties. | |
79+
| defaultConfiguration.logback-operator.xml | The default configuration of logback-operator.xml. Used when `logging.framework` is set to `logback`. | |
80+
| defaultConfiguration.logback-console.xml | The default configuration of logback-console.xml. Used when `logging.framework` is set to `logback`. | |
7981
| fullnameOverride | Overrides the fullname with the specified full name. | |
8082
| image.digest | The image tag of flink-kubernetes-operator. If set then it takes precedence and the image tag will be ignored. | |
8183
| image.pullPolicy | The image pull policy of flink-kubernetes-operator. | IfNotPresent |
@@ -87,6 +89,7 @@ The configurable parameters of the Helm chart and which default values as detail
8789
| jobServiceAccount.name | The name of job service account. | flink |
8890
| jvmArgs.operator | The JVM start up options for operator. | |
8991
| jvmArgs.webhook | The JVM start up options for webhook. | |
92+
| logging.framework | The logging framework to use for the operator. Supported values: `log4j2`, `logback`. Controls which config files are mounted and which JVM flag is passed. | log4j2 |
9093
| metrics.port | The metrics port on the container for default configuration. | |
9194
| nameOverride | Overrides the name with the specified name. | |
9295
| operatorHealth.livenessProbe | Liveness probe configuration for the operator using the health endpoint. Only time settings should be configured, endpoint is set automatically based on port. | |

‎docs/content.zh/docs/operations/metrics-logging.md‎

Lines changed: 94 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -616,7 +616,33 @@ Once the custom resource is created in the Kubernetes environment the operator m
616616
## Logging
617617
The Operator controls the logging behaviour for Flink applications and the Operator itself using configuration files mounted externally via ConfigMaps. [Configuration files](https://github.com/apache/flink-kubernetes-operator/tree/main/helm/flink-kubernetes-operator/conf) with default values are shipped in the Helm chart. It is recommended to review and adjust them if needed in the `values.yaml` file before deploying the Operator in production environments.
618618

619-
To append/override the default log configuration properties for the operator and Flink deployments define the `log4j-operator.properties` and `log4j-console.properties` keys respectively:
619+
The operator supports two logging frameworks: **Log4j2** (default) and **Logback**. Both sets of configuration files are shipped in the Helm chart and Docker image. The active framework is selected at install time via the `logging.framework` Helm value, either in `values.yaml` or on the command line:
620+
621+
```shell
622+
# Use the default Log4j2 framework (explicit, same as omitting the flag)
623+
helm install flink-operator helm/flink-kubernetes-operator --set logging.framework=log4j2
624+
625+
# Switch to Logback
626+
helm install flink-operator helm/flink-kubernetes-operator --set logging.framework=logback
627+
```
628+
629+
This controls three things:
630+
1. Which logging configuration files are mounted into `/opt/flink/conf/`
631+
2. Which JVM system property is passed to select the framework (`log4j.configurationFile` or `logback.configurationFile`)
632+
3. Which SLF4J binding JAR is placed on the classpath at runtime
633+
634+
{{< hint info >}}
635+
Logging in the operator is intentionally succinct and does not include contextual information such as namespace or name of the FlinkDeployment objects.
636+
We rely on the MDC provided by the operator-sdk to access this information and use it directly in the log layout.
637+
638+
See the [Java Operator SDK docs](https://javaoperatorsdk.io/docs/features#contextual-info-for-logging-with-mdc) for more detail.
639+
{{< /hint >}}
640+
641+
To learn more about accessing the job logs or changing the log level dynamically check the corresponding [section](https://nightlies.apache.org/flink/flink-docs-master/docs/deployment/resource-providers/native_kubernetes/#logging) of the core documentation.
642+
643+
### Log4j2
644+
645+
Log4j2 is the default logging framework. To append/override the default log configuration properties for the operator and Flink deployments define the `log4j-operator.properties` and `log4j-console.properties` keys respectively:
620646

621647
```yaml
622648
defaultConfiguration:
@@ -634,18 +660,60 @@ defaultConfiguration:
634660
# monitorInterval = 30
635661
```
636662

637-
{{< hint info >}}
638-
Logging in the operator is intentionally succinct and does not include contextual information such as namespace or name of the FlinkDeployment objects.
639-
We rely on the MDC provided by the operator-sdk to access this information and use it directly in the log layout.
663+
### Logback
640664

641-
See the [Java Operator SDK docs](https://javaoperatorsdk.io/docs/features#contextual-info-for-logging-with-mdc) for more detail.
665+
When using Logback, the equivalent configuration keys are `logback-operator.xml` and `logback-console.xml`:
666+
667+
```yaml
668+
logging:
669+
framework: logback
670+
671+
defaultConfiguration:
672+
create: true
673+
append: true
674+
logback-operator.xml: |+
675+
<!-- Flink Operator Logback Overrides -->
676+
<!-- <configuration>
677+
<appender name="ConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
678+
<encoder>
679+
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level %-60logger{26} %X - %msg%n</pattern>
680+
</encoder>
681+
</appender>
682+
<root level="DEBUG">
683+
<appender-ref ref="ConsoleAppender" />
684+
</root>
685+
</configuration> -->
686+
logback-console.xml: |+
687+
<!-- Flink Deployment Logback Overrides -->
688+
<!-- <configuration>
689+
<appender name="ConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
690+
<encoder>
691+
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level %-60logger{26} %X - %msg%n</pattern>
692+
</encoder>
693+
</appender>
694+
<root level="DEBUG">
695+
<appender-ref ref="ConsoleAppender" />
696+
</root>
697+
</configuration> -->
698+
```
699+
700+
{{< hint warning >}}
701+
**Logback XML overrides replace the entire default configuration.** Unlike Log4j2 `.properties` files where user entries are appended, XML files cannot be concatenated (two `<configuration>` root elements produce invalid XML). Ensure your custom `logback-operator.xml` or `logback-console.xml` is complete and self-contained. Logback supports only XML-based configuration and does not provide native support for `.properties` configuration files.
642702
{{< /hint >}}
643703

644-
To learn more about accessing the job logs or changing the log level dynamically check the corresponding [section](https://nightlies.apache.org/flink/flink-docs-master/docs/deployment/resource-providers/native_kubernetes/#logging) of the core documentation.
704+
### Logging Library Version Overrides
705+
706+
The operator ships with **Logback 1.2.x** and **SLF4J 1.7.x**. These versions are bundled in the Docker image and the SLF4J 1.7.x API is shaded into the operator JAR.
707+
708+
{{< hint warning >}}
709+
**Upgrading to Logback 1.4+/1.5+ or SLF4J 2.x is not supported.** SLF4J 2.x uses a `ServiceLoader`-based binding mechanism that is incompatible with the SLF4J 1.7.x API shaded inside the operator. Replacing the JARs at runtime will result in `ClassNotFoundException: org.slf4j.impl.StaticLoggerBinder`.
710+
{{< /hint >}}
645711

646712
### FlinkDeployment Logging Configuration
647713

648-
Users have the freedom to override the default `log4j-console.properties` settings on a per-deployment level by putting the entire log configuration into `spec.logConfiguration`:
714+
Users have the freedom to override the default logging settings on a per-deployment level by putting the entire log configuration into `spec.logConfiguration`.
715+
716+
For Log4j2:
649717

650718
```yaml
651719
spec:
@@ -656,3 +724,22 @@ spec:
656724
rootLogger.appenderRef.file.ref = LogFile
657725
...
658726
```
727+
728+
For Logback:
729+
730+
```yaml
731+
spec:
732+
...
733+
logConfiguration:
734+
logback-console.xml: |+
735+
<configuration>
736+
<appender name="ConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
737+
<encoder>
738+
<pattern>%d{yyyy-MM-dd HH:mm:ss,SSS} %-5level %-60.60logger{60} %X - %msg%n</pattern>
739+
</encoder>
740+
</appender>
741+
<root level="DEBUG">
742+
<appender-ref ref="ConsoleAppender" />
743+
</root>
744+
</configuration>
745+
```

0 commit comments

Comments
 (0)