Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: ZNode management requires connectivity between the operator and the ZookeeperCluster #765

Merged
merged 1 commit into from
Feb 1, 2024
Merged

docs: ZNode management requires connectivity between the operator and the ZookeeperCluster #765

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/modules/zookeeper/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ The Stackable Operator for Apache ZooKeeper is a Kubernetes Operator for deployi
https://zookeeper.apache.org/[Apache ZooKeeper] ensembles. Apache ZooKeeper is an open-source distributed coordination
service that facilitates synchronization, configuration management and leader election in distributed systems. ZooKeeper
is often used for these tasks in the Apache Hadoop ecosystem. Within the Stackable Platform, the Stackable Operators for
xref:hbase:index.adoc[Apache HBase], xref:hdfs:index.adoc[Apache Hadoop HDFS], xref:kafka:index.adoc[Apache Kafka] and
xref:nifi:index.adoc[Apache NiFi] depend on the ZooKeeper Operator.
xref:hbase:index.adoc[Apache HBase], xref:hdfs:index.adoc[Apache Hadoop HDFS], xref:kafka:index.adoc[Apache Kafka],
xref:nifi:index.adoc[Apache NiFi] and xref:druid:index.adoc[Apache Druid] depend on the ZooKeeper Operator.

== Getting started

Expand All @@ -29,7 +29,7 @@ role group is accessible through its own Service, and there is a Service for the

The Operator creates a xref:concepts:service_discovery.adoc[service discovery ConfigMap] for the ZooKeeper instance, as
well as for each ZNode. The discovery ConfigMaps contain information on how to connect to ZooKeeper. The ZNode discovery
ConfigMap give access information for the ZNode. xref:zookeeper:znodes.adoc[learn more about ZNodes].
ConfigMap give access information for the ZNode. xref:zookeeper:znodes.adoc[Learn more about ZNodes].

== Dependencies

Expand Down
26 changes: 21 additions & 5 deletions docs/modules/zookeeper/pages/znodes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,19 @@

The Stackable Operator for Apache ZooKeeper manages ZNodes using the _ZookeeperZnode_ resource.

IMPORTANT: The Operator connects directly to ZooKeeper to manage the ZNodes inside of the ZooKeeper ensemble. This means that network access to the ZooKeeper pods is necessary. If your Kubernetes cluster restricts network acess, you need to configure a NetworkPolicy to allow the operator to connect to ZooKeeper.

Check notice on line 11 in docs/modules/zookeeper/pages/znodes.adoc

View workflow job for this annotation

GitHub Actions / LanguageTool

[LanguageTool] docs/modules/zookeeper/pages/znodes.adoc#L11 

This phrase is redundant. Consider using “inside”. (OUTSIDE_OF[1])
Suggestions: `inside`
URL: https://languagetool.org/insights/post/wordiness/ 
Rule: https://community.languagetool.org/rule/show/OUTSIDE_OF?lang=en-US&subId=1
Category: REDUNDANCY
Raw output 
docs/modules/zookeeper/pages/znodes.adoc:11:76: This phrase is redundant. Consider using “inside”. (OUTSIDE_OF[1])
 Suggestions: `inside`
 URL: https://languagetool.org/insights/post/wordiness/ 
 Rule: https://community.languagetool.org/rule/show/OUTSIDE_OF?lang=en-US&subId=1
 Category: REDUNDANCY

== Configuring ZNodes

ZNodes are configured with the ZookeeperZnode CustomResource.
If a ZookeeperZnode resource is created, the operator will create the respective tree in ZooKeeper.
Also, if the resource in Kubernetes is deleted, so is the data in ZooKeeper.

CAUTION: The operator automatically deletes the ZNode from the ZooKeeper cluster if the Kubernetes `ZookeeperZnode` object is deleted. Recreating the
`ZookeeperZnode` object will not restore access to the data.

Here is an example of a ZookeeperZnode:

[source,yaml]
----
include::example$example-znode.yaml[]
Expand All @@ -16,14 +29,17 @@
<2> Reference to the `ZookeeperCluster` object where the ZNode should be created.
<3> The namespace of the `ZookeeperCluster`. Can be omitted and will default to the namespace of the ZNode object.

NOTE: It is the responsibility of the user to ensure that ZNodes are not shared between products. For example, a Kafka and a Hadoop cluster should not share the same ZNode.

When a ZNode is created, the operator creates the required tree in ZooKeeper and a xref:concepts:service_discovery.adoc[discovery ConfigMap] with a xref:discovery.adoc[] for this ZNode. This discovery ConfigMap is used by other operators to configure clients with access to the ZNode.

The operator _does not_ manage the contents of the ZNode.

CAUTION: The operator automatically deletes the ZNode from the ZooKeeper cluster if the Kubernetes `ZookeeperZnode` object is deleted. Recreating the
`ZookeeperZnode` object will not restore access to the data.

== Creating a ZNode per dependant

To ensure that a product that uses ZooKeeper is running smoothly, you should make sure that each Stacklet or product instance is operating with its own ZNode.
For example, a Kafka and a Hadoop cluster should not share the same ZNode. Also no two Kafka instances should share the same ZNode.

Check notice on line 40 in docs/modules/zookeeper/pages/znodes.adoc

View workflow job for this annotation

GitHub Actions / LanguageTool

[LanguageTool] docs/modules/zookeeper/pages/znodes.adoc#L40 

A comma may be missing after the conjunctive/linking adverb ‘Also’. (SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA[1])
Suggestions: `Also,`
URL: https://languagetool.org/insights/post/linking-words/ 
Rule: https://community.languagetool.org/rule/show/SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA?lang=en-US&subId=1
Category: PUNCTUATION
Raw output 
docs/modules/zookeeper/pages/znodes.adoc:40:75: A comma may be missing after the conjunctive/linking adverb ‘Also’. (SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA[1])
 Suggestions: `Also,`
 URL: https://languagetool.org/insights/post/linking-words/ 
 Rule: https://community.languagetool.org/rule/show/SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA?lang=en-US&subId=1
 Category: PUNCTUATION

Check notice on line 41 in docs/modules/zookeeper/pages/znodes.adoc

View workflow job for this annotation

GitHub Actions / LanguageTool

[LanguageTool] docs/modules/zookeeper/pages/znodes.adoc#L41 

In American English, “take a look” is more commonly used. (HAVE_A_LOOK[5])
Suggestions: `Take a look`
Rule: https://community.languagetool.org/rule/show/HAVE_A_LOOK?lang=en-US&subId=5
Category: BRITISH_ENGLISH
Raw output 
docs/modules/zookeeper/pages/znodes.adoc:41:1: In American English, “take a look” is more commonly used. (HAVE_A_LOOK[5])
 Suggestions: `Take a look`
 Rule: https://community.languagetool.org/rule/show/HAVE_A_LOOK?lang=en-US&subId=5
 Category: BRITISH_ENGLISH
Have a look at the xref:usage_guide/isolating_clients_with_znodes.adoc[] guide for hands-on instructions on how to set up multiple ZNodes for different Stacklets.

== Split responsibilities for ZooKeeper and ZNodes

Expand All @@ -35,4 +51,4 @@

== What's next

Have a look at the usage guide for ZNodes: xref:usage_guide/isolating_clients_with_znodes.adoc[]
Have a look at the usage guide for ZNodes: xref:usage_guide/isolating_clients_with_znodes.adoc[] or the CRD reference for the {crd-docs}/zookeeper.stackable.tech/zookeeperznode/v1alpha1/[ZookeeperZnode {external-link-icon}^] CustomResource.
Loading