From 2f90c1461bb1939be2b432a7007b116e07393e71 Mon Sep 17 00:00:00 2001 From: Serge Bishyr Date: Wed, 16 Oct 2024 10:37:42 +0300 Subject: [PATCH 1/7] Add Flow CR documentation --- docs/modules/ROOT/examples/flow.yaml | 29 +++++++++++ docs/modules/ROOT/nav.adoc | 1 + docs/modules/ROOT/pages/flow.adoc | 72 ++++++++++++++++++++++++++++ 3 files changed, 102 insertions(+) create mode 100644 docs/modules/ROOT/examples/flow.yaml create mode 100644 docs/modules/ROOT/pages/flow.adoc diff --git a/docs/modules/ROOT/examples/flow.yaml b/docs/modules/ROOT/examples/flow.yaml new file mode 100644 index 00000000..29ed0c28 --- /dev/null +++ b/docs/modules/ROOT/examples/flow.yaml @@ -0,0 +1,29 @@ +apiVersion: hazelcast.com/v1alpha1 +kind: Flow +metadata: + labels: + app.kubernetes.io/name: hazelcast-platform-operator + name: flow +spec: + size: 3 + licenseKeySecretName: hazelcast-license-key + externalConnectivity: + ingress: + hostname: "" + ingressClassName: nginx + path: "/" + annotations: + kubernetes.io/ingress.class: "nginx" + nginx.ingress.kubernetes.io/ssl-redirect: "false" + nginx.ingress.kubernetes.io/enable-opentelemetry: "true" + database: + host: "flow-database" + secretName: flow-db-secret + env: + - name: OPTIONS + value: | + --flow.analytics.persistRemoteCallResponses=true + --flow.stream-server.enabled=false + --flow.analytics.persistResults=false + --flow.toggles.dashboard-enabled=true + --flow.config.custom.managementCenterUrl=http://233.252.0.158/mc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 1b28dafa..d52217fe 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -41,6 +41,7 @@ ** xref:management-center-persistence.adoc[Persistence] ** xref:management-center-jvm-args.adoc[JVM Arguments] ** xref:management-center-ldap.adoc[LDAP Security Provider] +* xref:flow.adoc[Flow] .Reference // Configuration options/spec files/any other reference docs diff --git a/docs/modules/ROOT/pages/flow.adoc b/docs/modules/ROOT/pages/flow.adoc new file mode 100644 index 00000000..83fd267c --- /dev/null +++ b/docs/modules/ROOT/pages/flow.adoc @@ -0,0 +1,72 @@ += Deploy Flow + +:description: In this tutorial, you'll deploy a Flow application using Hazelcast Platform Operator for Kubernetes. + +{description} + +== Prerequisites + +- Flow requires the Management Center application to run and be configured properly. The Management Center application should be configured to use FLow. + +[source,yaml] +---- +... +hazelcastClusters: +- address: flow <1> + name: flow <2> +jvm: + args: + - "-Dhazelcast.mc.flow.addresses=http://233.252.0.158/" <3> + - "-Dhazelcast.mc.internal.flowAddresses=http://flow:9021" <4> +... +---- + +<1> The service name of the Flow application. The same as the Flow CR name. +<2> Hazelcast cluster name. Should always be `flow`. +<3> Flow Ingress public address. +<4> The internal address of Flow in the format of `http://:9021`. The service name is the same as the Flow CR name. + +- To connect to the database you need create a `Secret` with the DB credentials: + +[source,shell] +---- +kubectl create secret generic flow-db-secret \ + --from-literal=database=flow \ + --from-literal=username=flow \ + --from-literal=password="strong-password" +---- + +In the created secret `username` and `password` are required, whereas `database` field is optional and will default to `flow` if not provided. + +== Run Flow + +To run Flow on Kubernetes using Hazelcast Platform Operator you need to create a Flow CR. + +[source,yaml,subs="attributes+"] +---- +include::ROOT:example$/flow.yaml[] +---- + +Additional flow configuration can be accheived by providing additional parameters via `OPTIONS` environment variable. + +NOTE: Parameters managed by the Hazelcat Platform Operator are not allowed in the `OPTIONS`. E.g., the Database configuration can only be done via `spec.database` in the Flow CR. + +=== Configure OpenID support + +You can enable OpenID support with Management Center deployment on Flow. In order to configure OpenID, you need to provide the required parameters to the `OPTIONS` environment variable: + +[source,yaml] +---- +... +- name: OPTIONS + value: | + --flow.security.openIdp.enabled=true + --flow.security.openIdp.jwks-uri=http://233.252.0.158/mc/oauth2/jwks + --flow.security.openIdp.issuerUrl=http://233.252.0.158/mc + --flow.security.openIdp.clientId=flow-client + --flow.security.openIdp.require-https=false + --flow.security.open-idp.roles.format=path + --flow.security.open-idp.roles.path=roles + --flow.security.open-idp.refreshTokensDisabled=true +... +---- From 8e48af29fb39ce687bb12b2819a2d028bc103e0e Mon Sep 17 00:00:00 2001 From: Serge Bishyr Date: Thu, 17 Oct 2024 11:08:08 +0300 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: Amanda Lindsay --- docs/modules/ROOT/pages/flow.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/modules/ROOT/pages/flow.adoc b/docs/modules/ROOT/pages/flow.adoc index 83fd267c..58d1b604 100644 --- a/docs/modules/ROOT/pages/flow.adoc +++ b/docs/modules/ROOT/pages/flow.adoc @@ -21,7 +21,7 @@ jvm: ... ---- -<1> The service name of the Flow application. The same as the Flow CR name. +<1> The service name of the Flow application. The same as the Flow Custom Resource (CR) name. <2> Hazelcast cluster name. Should always be `flow`. <3> Flow Ingress public address. <4> The internal address of Flow in the format of `http://:9021`. The service name is the same as the Flow CR name. @@ -47,13 +47,13 @@ To run Flow on Kubernetes using Hazelcast Platform Operator you need to create a include::ROOT:example$/flow.yaml[] ---- -Additional flow configuration can be accheived by providing additional parameters via `OPTIONS` environment variable. +Additional flow configuration can be achieved by providing additional parameters using the `OPTIONS` environment variable. -NOTE: Parameters managed by the Hazelcat Platform Operator are not allowed in the `OPTIONS`. E.g., the Database configuration can only be done via `spec.database` in the Flow CR. +NOTE: Parameters managed by the Hazelcast Platform Operator are not allowed in `OPTIONS`. E.g., the Database configuration can only be done via `spec.database` in the Flow CR. === Configure OpenID support -You can enable OpenID support with Management Center deployment on Flow. In order to configure OpenID, you need to provide the required parameters to the `OPTIONS` environment variable: +You can enable OpenID support with Management Center deployment on Flow. To configure OpenID, provide the required parameters to the `OPTIONS` environment variable: [source,yaml] ---- From 49270fe6d553a21bcc8499c239ab75cb433a683c Mon Sep 17 00:00:00 2001 From: Serge Bishyr Date: Thu, 17 Oct 2024 11:10:04 +0300 Subject: [PATCH 3/7] add MC Flow image --- docs/modules/ROOT/pages/flow.adoc | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/modules/ROOT/pages/flow.adoc b/docs/modules/ROOT/pages/flow.adoc index 58d1b604..5be92eb0 100644 --- a/docs/modules/ROOT/pages/flow.adoc +++ b/docs/modules/ROOT/pages/flow.adoc @@ -11,20 +11,23 @@ [source,yaml] ---- ... +image: docker.io/hazelcast/management-center-flow <1> +... hazelcastClusters: -- address: flow <1> - name: flow <2> +- address: flow <2> + name: flow <3> jvm: args: - - "-Dhazelcast.mc.flow.addresses=http://233.252.0.158/" <3> - - "-Dhazelcast.mc.internal.flowAddresses=http://flow:9021" <4> + - "-Dhazelcast.mc.flow.addresses=http://233.252.0.158/" <4> + - "-Dhazelcast.mc.internal.flowAddresses=http://flow:9021" <5> ... ---- -<1> The service name of the Flow application. The same as the Flow Custom Resource (CR) name. -<2> Hazelcast cluster name. Should always be `flow`. -<3> Flow Ingress public address. -<4> The internal address of Flow in the format of `http://:9021`. The service name is the same as the Flow CR name. +<1> Management Center Flow image. +<2> The service name of the Flow application. The same as the Flow Custom Resource (CR) name. +<3> Hazelcast cluster name. Should always be `flow`. +<4> Flow Ingress public address. +<5> The internal address of Flow in the format of `http://:9021`. The service name is the same as the Flow CR name. - To connect to the database you need create a `Secret` with the DB credentials: From 65516d56987793b48d201c99bfb2fc7d02b05ca5 Mon Sep 17 00:00:00 2001 From: Serge Bishyr Date: Thu, 17 Oct 2024 11:17:04 +0300 Subject: [PATCH 4/7] add links to flow docs --- docs/modules/ROOT/pages/flow.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/flow.adoc b/docs/modules/ROOT/pages/flow.adoc index 5be92eb0..2340a416 100644 --- a/docs/modules/ROOT/pages/flow.adoc +++ b/docs/modules/ROOT/pages/flow.adoc @@ -4,6 +4,8 @@ {description} +See xref:flow:introduction:index.adoc[Flow] for more detailed information. + == Prerequisites - Flow requires the Management Center application to run and be configured properly. The Management Center application should be configured to use FLow. @@ -50,7 +52,7 @@ To run Flow on Kubernetes using Hazelcast Platform Operator you need to create a include::ROOT:example$/flow.yaml[] ---- -Additional flow configuration can be achieved by providing additional parameters using the `OPTIONS` environment variable. +Additional flow configuration can be achieved by providing additional parameters using the `OPTIONS` environment variable. See xref:flow:introduction:index.adoc[Configure Flow] for detailed information. NOTE: Parameters managed by the Hazelcast Platform Operator are not allowed in `OPTIONS`. E.g., the Database configuration can only be done via `spec.database` in the Flow CR. From 687fb663e1faa44fa20b67bdb5abfc45545493cc Mon Sep 17 00:00:00 2001 From: Serge Bishyr Date: Fri, 18 Oct 2024 14:37:10 +0300 Subject: [PATCH 5/7] Add reference to PostgreSQL --- docs/modules/ROOT/pages/flow.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/flow.adoc b/docs/modules/ROOT/pages/flow.adoc index 2340a416..a650b0c4 100644 --- a/docs/modules/ROOT/pages/flow.adoc +++ b/docs/modules/ROOT/pages/flow.adoc @@ -31,7 +31,7 @@ jvm: <4> Flow Ingress public address. <5> The internal address of Flow in the format of `http://:9021`. The service name is the same as the Flow CR name. -- To connect to the database you need create a `Secret` with the DB credentials: +- To connect to PostgreSQL database you need create a `Secret` with the DB credentials: [source,shell] ---- From fc1cc0bfd372337b295460ea0e88a39a8e732e9e Mon Sep 17 00:00:00 2001 From: Serge Bishyr Date: Mon, 21 Oct 2024 15:53:40 +0300 Subject: [PATCH 6/7] change links --- docs/modules/ROOT/pages/flow.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/pages/flow.adoc b/docs/modules/ROOT/pages/flow.adoc index a650b0c4..b5f4282e 100644 --- a/docs/modules/ROOT/pages/flow.adoc +++ b/docs/modules/ROOT/pages/flow.adoc @@ -4,7 +4,7 @@ {description} -See xref:flow:introduction:index.adoc[Flow] for more detailed information. +See xref:flow:ROOT:index.adoc[Flow] for more detailed information. == Prerequisites @@ -58,7 +58,8 @@ NOTE: Parameters managed by the Hazelcast Platform Operator are not allowed in ` === Configure OpenID support -You can enable OpenID support with Management Center deployment on Flow. To configure OpenID, provide the required parameters to the `OPTIONS` environment variable: +You can enable OpenID support with Management Center deployment on Flow. To configure OpenID, provide the required parameters to the `OPTIONS` environment variable. +See xref:flow:deploy:security-recommendations.adoc[Security recommendations] to discover all available options. [source,yaml] ---- From 0ad40e5b7db2df96116f5c2c33d041269f3be3c0 Mon Sep 17 00:00:00 2001 From: Serge Bishyr Date: Mon, 21 Oct 2024 16:15:31 +0300 Subject: [PATCH 7/7] fix index link --- docs/modules/ROOT/pages/flow.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/flow.adoc b/docs/modules/ROOT/pages/flow.adoc index b5f4282e..81800dcb 100644 --- a/docs/modules/ROOT/pages/flow.adoc +++ b/docs/modules/ROOT/pages/flow.adoc @@ -4,7 +4,7 @@ {description} -See xref:flow:ROOT:index.adoc[Flow] for more detailed information. +See xref:flow:index.adoc[Flow] for more detailed information. == Prerequisites