Skip to content

Commit 413528d

Browse files
fhennigNickLarsenNZ
fhennig
and
NickLarsenNZ
authored
Adding descriptions (#662)
* first batch of descriptions * more descriptions * pre-commit fixes * more descriptions * linter fixes * linter fixes * more descriptions * more descriptions * linter fixes * Add description bit to style guide * Add more descriptions * Add more descriptions * Remove trailing whitespace * Update modules/ROOT/pages/licenses.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * Update modules/reference/pages/glossary.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * Update modules/reference/pages/duration.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * Update modules/guides/pages/viewing-and-verifying-sboms.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * Update modules/concepts/pages/s3.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * Add info about description usage * Update modules/concepts/pages/tls-server-verification.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * Update modules/concepts/pages/stacklet.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> --------- Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com>
1 parent b876795 commit 413528d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+67
-26
lines changed

‎modules/ROOT/pages/export.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Export Control
2+
:description: Stackable Data Platform is exempt from US EAR export controls due to its publicly available status and use of standard encryption. Code is open source on GitHub.
23

34
== USA
45

‎modules/ROOT/pages/getting-started.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Getting Started
22
:page-aliases: getting_started.adoc
3+
:description: Learn how to set up and test a Stackable Data Platform with Apache ZooKeeper, Kafka, and NiFi using Kubernetes. Ideal for lab environments.
34

45
One of the best ways of getting started with a new platform is to try it out. Any big data platform has a lot of moving parts and getting some hands on keyboard time with it helps reinforce learning.
56

‎modules/ROOT/pages/index.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
= Stackable Documentation
22
:page-layout: landing
3-
43
:k8s-operators: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
54
:docs-discussion: https://github.com/stackabletech/community/discussions
65
:docs-issues: https://github.com/stackabletech/documentation/issues
76
:docs-repo: https://github.com/stackabletech/documentation
7+
:description: User Documentation for the Stackable Data Platform.
88

99
++++
1010
<style>
@@ -82,7 +82,7 @@ Run a demo data processing pipeline or follow a tutorial to learn about the plat
8282
<h3>Concept explanation</h3>
8383
++++
8484

85-
Read concept explanation to gain a better understanding of how the Stackable Data platform works,
85+
Read concept explanation to gain a better understanding of how the Stackable Data platform works,
8686
or how a specific feature works.
8787

8888
xref:concepts:index.adoc[]

‎modules/ROOT/pages/kubernetes/index.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Kubernetes
2+
:description: Learn how to install Kubernetes for the Stackable Data Platform. Supported production distributions and local setup options with Kind and K3s.
23

34
The Stackable Data Platform runs on Kubernetes, a Kubernetes cluster is a prerequisite to running the platform.
45
On this page you will find information on the supported Kubernetes distributions for production as well as how to set up a local test installation to try out parts of the platform right away.

‎modules/ROOT/pages/licenses.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Licenses for the Stackable Data Platform
2+
:description: Find licenses for all Stackable Data Platform components available on GitHub including operators, stackablectl, and Docker images.
23

34
The Stackable Data Platform is open source, and the source code of all the components can be found on GitHub. Licenses are also provided alongside the source code, in a file called `LICENSE`.
45

‎modules/ROOT/pages/policies.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Lifecycle policies
2+
:description: Detailed lifecycle policies for Stackable Data Platform, covering SDP, CRD versioning, product support, and compatibility with Kubernetes & OpenShift.
23

34
This page details our lifecycle policies around various parts of our product - the Stackable Data Platform (SDP).
45

‎modules/ROOT/pages/product-information.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
= Product information
2+
:description: Learn about concrete specifications of the Stackable Data Platform (SDP) as a product, which components are
3+
included, how they are supplied and which external dependencies exist that you as a customer need to take care of.
24

35
This page contains concrete specifications about the Stackable Data Platform (SDP) as a product, which components are
46
included, how they are supplied and which external dependencies exist that you as a customer need to take care of.

‎modules/ROOT/pages/quickstart.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
= Quickstart
2-
32
:latest-release: https://github.com/stackabletech/stackable-cockpit/releases/tag/stackablectl-1.0.0-rc2
43
:cockpit-releases: https://github.com/stackabletech/stackable-cockpit/releases
4+
:description: Quickstart guide for Stackable: Install stackablectl, set up a demo, and connect to services like Superset and Trino with easy commands and links.
55

66
This is the super-short getting started guide that should enable you to get something up and running in less than three
77
minutes (excluding download times).

‎modules/ROOT/pages/release-notes.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Release notes for the Stackable Data Platform
22
:page-aliases: release_notes.adoc
3+
:description: Learn about the latest features and changes in the release notes for the Stackable Data Platform.
34

45
The Stackable platform consists of multiple operators that work together. Periodically a platform release is made,
56
including all components of the platform at a specific version.

‎modules/concepts/pages/authentication.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Authentication
22
:keycloak: https://www.keycloak.org/
3+
:description: Overview of Stackable’s user authentication methods and configuration for LDAP, OIDC, TLS, and Static providers.
34

45
The Stackable Platform uses the AuthenticationClass as a central mechanism to handle user authentication across supported products.
56
The authentication mechanism needs to be configured only in the AuthenticationClass which is then referenced in the xref:stacklet.adoc[Stacklet] definition.

‎modules/concepts/pages/container-images.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
:ubi: https://catalog.redhat.com/software/base-images
33
:stackable-image-registry: https://repo.stackable.tech/#browse/browse
44
:stackable-sboms: https://sboms.stackable.tech/
5+
:description: Overview of Stackable’s container images, including structure, multi-platform support, and why upstream images are not used.
56

67
The core artifacts of the Stackable Data Platform are container images of Kubernetes operators and the products that these operators deploy.
78

@@ -37,7 +38,7 @@ See our documentation xref:concepts:multi-platform-support.adoc[on multi-platfor
3738
[#signatures]
3839
== Image signatures
3940

40-
All Stackable images are signed.
41+
All Stackable images are signed.
4142
Image signatures help to ensure the authenticity and integrity of container images.
4243
You can xref:guides:enabling-verification-of-image-signatures.adoc[verify image signatures automatically] in your cluster to make sure that the images you are running are authentic and intact.
4344

‎modules/concepts/pages/index.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Concepts
2+
:description: Explore Stackable Data Platform concepts like Stacklets, configuration mechanisms, resources, connectivity, security, and observability.
23

34
== Overview
45

@@ -17,7 +18,7 @@ Learn about how to access xref:experimental-arm64-support[ARM64-support].
1718

1819
== Connectivity
1920

20-
Many Platform components depend on other components or expose functionality that you can connect to.
21+
Many Platform components depend on other components or expose functionality that you can connect to.
2122
This connectivity is achived with xref:service-discovery.adoc[service discovery ConfigMaps].
2223
To access your Stackable operated products from outside the Kuberenetes cluster learn more about xref:service-exposition.adoc[].
2324

‎modules/concepts/pages/labels.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Labels
22
:common-labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/
3+
:description: Understand resource labeling by Stackable operators and tools like stackablectl and Helm for better management and organization.
34

45
Labels are key/value pairs in the metadata of Kubernetes objects that add identifying information to the object.
56
They do not have direct semantic implications but can be used to organize and manage resources.

‎modules/concepts/pages/logging.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
:vector-agg-install: https://vector.dev/docs/setup/installation/package-managers/helm/#aggregator
99
:vector-source-vector: https://vector.dev/docs/reference/configuration/sources/vector/
1010
:vector-topology-centralized: https://vector.dev/docs/setup/deployment/topologies/#centralized
11+
:description: Learn Stackable's logging setup: human-readable and aggregated logs with Vector, consistent configuration across Stacklets, and custom overrides.
1112

1213
Logging is important for observability of the platform.
1314
Stackable provides human-readable plaintext logs for each running container, as well as aggregated and persisted logs with identical structure across the whole platform.
@@ -93,7 +94,7 @@ spec:
9394
level: NONE
9495
sidecar-container:
9596
console:
96-
level: ERROR
97+
level: ERROR
9798
----
9899
<1> The discovery ConfigMap of the Vector aggregator to publish the logs to. This is set at cluster level.
99100
<2> The role or role group config containing the logging configuration.

‎modules/concepts/pages/multi-platform-support.adoc

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,14 @@
11
= Multi-platform for SDP
2-
:description: This page describes multi-platform support for AMD64 and ARM64
32
:keywords: Multi-Architecture, infrastructure, docker, image, tags
43
:multi-platform-images: https://docs.docker.com/build/building/multi-platform/
4+
:description: Starting with Stackable 24.7, all images support AMD64 and ARM64 architectures, enabling mixed clusters with architecture-specific tags and automated selection.
55

66
WARNING: This status is still experimental, as we work to fine-tune the necessary workflows.
77

8-
== Description
9-
10-
Starting with Stackable release 24.7, all images are {multi-platform-images}[multi-platform images], supporting the AMD64 and ARM64 architectures.
8+
Starting with the Stackable Data Platform release 24.7, all images are {multi-platform-images}[multi-platform images], supporting the AMD64 and ARM64 architectures.
119
Each product image is built for each platform with an architecture-specific tag.
1210
For example, the Airflow images with tags `airflow:2.9.2-stackable24.7.0-amd64` and `airflow:2.9.2-stackable24.7.0-arm64` are bundled in the manifest list `airflow:2.9.2-stackable24.7.0` using an automated workflow.
1311
The appropriate image will then be transparently selected for the active platform/architecture.
1412
This also enables mixed Kubernetes clusters, with AMD64 and ARM64 nodes being used simultaneously.
1513

16-
NOTE: Superset 2.x (deprecated, and to be removed in a future version) is not available as a multi-platform product image.
14+
NOTE: Superset 2.x (deprecated, and to be removed in a future version) is not available as a multi-platform product image.

‎modules/concepts/pages/opa.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
:opa: https://www.openpolicyagent.org
33
:rego: https://www.openpolicyagent.org/docs/latest/policy-language/
44
:opa-docs: https://www.openpolicyagent.org/docs/latest/#overview
5+
:description: Stackable Data Platform uses OpenPolicyAgent (OPA) for policy-based access control with Rego rules, ensuring efficient, local policy evaluation across nodes.
56

67
The Stackable Data Platform offers policy-based access control via the {opa}[OpenPolicyAgent] (OPA) operator.
78
Authorization policies are defined in the {rego}[Rego] language, divided into packages and supplied via ConfigMaps.

‎modules/concepts/pages/operations/cluster_operations.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Cluster operations
22
:page-aliases: ../cluster_operations.adoc
3+
:description: Manage Stackable clusters with operations like pausing reconciliation, stopping Pods, and manual/automatic restarts. Learn how to update and restart services effectively.
34

45
Stackable operators offer different cluster operations to control the reconciliation process.
56
This is useful when updating operators, debugging or testing of new settings:
@@ -97,7 +98,7 @@ To restart the HDFS DataNode Pods, run:
9798

9899
[source,shell]
99100
----
100-
$ kubectl rollout restart statefulset dumbo-datanode-default
101+
$ kubectl rollout restart statefulset dumbo-datanode-default
101102
statefulset.apps/dumbo-datanode-default restarted
102103
----
103104

‎modules/concepts/pages/operations/graceful_shutdown.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Graceful shutdown
2+
:description: Graceful shutdown ensures a controlled, clean shutdown of service instances, allowing time for normal shutdown activities.
23

34
Graceful shutdown refers to the managed, controlled shutdown of service instances in the manner intended by the software authors.
45
Typically, an instance will receive a signal indicating the intent for the server to shut down, and it will initiate a controlled shutdown.

‎modules/concepts/pages/operations/index.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Operations
2+
:description: Guidance for maintaining Stackable Data Platform installations. Covers service availability, maintenance actions, and performance optimization.
23

34
This section of the documentation is intended for the operations teams that maintain a Stackable Data Platform installation.
45
It provides you with the necessary details to operate it in a production environment.

‎modules/concepts/pages/operations/pod_disruptions.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Allowed Pod disruptions
22
:k8s-pdb: https://kubernetes.io/docs/tasks/run-application/configure-pdb/
3+
:description: Configure PodDisruptionBudgets (PDBs) to minimize planned downtime for Stackable products. Default values are based on fault tolerance and can be customized.
34

45
Any downtime of our products is generally considered to be bad.
56
Although downtime can't be prevented 100% of the time - especially if the product does not support High Availability - we can try to do our best to reduce it to an absolute minimum.

‎modules/concepts/pages/operations/pod_placement.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Pod placement
22
:page-aliases: ../pod_placement.adoc
3+
:description: Configure pod affinity, anti-affinity, and node affinity for Stackable Data Platform operators using YAML definitions.
34

45
Several operators of the Stackable Data Platform permit the configuration of pod affinity as described in the Kubernetes https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/[documentation].
56
If no affinity is defined in the product's custom resource, the operators apply reasonable defaults that make use of the `preferred_during_scheduling_ignored_during_execution` property.

‎modules/concepts/pages/overrides.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Overrides
22
:k8s-openapi-deepmerge: https://arnavion.github.io/k8s-openapi/v0.22.x/k8s_openapi/trait.DeepMerge.html
3+
:description: Stackable operators support configuration overrides for Stacklets, including settings for config files, environment variables, and Pod specifications, with precedence rules.
34

45
The Stackable operators configure the xref:stacklet.adoc[Stacklets] they are operating with sensible defaults and required settings to enable connectivity and security.
56
Other important settings are usually exposed in the Stacklet resource definition for you to configure directly.

‎modules/concepts/pages/overview.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Stackable Data Platform explained
2+
:description: The Stackable Data Platform leverages Kubernetes operators to manage products like ZooKeeper and HDFS, using custom resources for deployment and configuration.
23

34
The Stackable Data Platform (SDP) is built on Kubernetes.
45
Its core is a collection of Kubernetes Operators and CustomResourceDefinitions which are designed to work together.
@@ -76,4 +77,4 @@ image::common_objects.drawio.svg[]
7677

7778
These objects can be reused by all operators that support this feature. The S3 bucket only needs to be described once, and then it can be referenced in all products that support reading and/or writing from/to S3. Learn more about S3 configuration: xref:s3.adoc[].
7879

79-
Similarly for the OpenPolicyAgent (OPA). Configuring it looks the same across all products. Learn more: xref:opa.adoc[].
80+
Similarly for the OpenPolicyAgent (OPA). Configuring it looks the same across all products. Learn more: xref:opa.adoc[].

‎modules/concepts/pages/product-image-selection.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
= Product image selection
22
:page-aliases: product_image_selection.adoc
3-
:description: This page describes the different ways of specifying a product image to use in your product deployment.
43
:keywords: Kubernetes, operator, docker, registry, custom image, tags
4+
:description: Learn how to specify product images for Stackable Data Platform deployments, including using default, custom, or mirrored registries.
55

66
To run any product on the Stackable Data Platform, you need to specify which version you want to run in the resource definition (i.e. a SparkApplication or DruidCluster).
77
The simplest way to do this is this:

‎modules/concepts/pages/resources.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= Resource management
2+
:description: Learn how to manage CPU, memory, and storage resources for Stackable Data Platform products, including setting requests, limits, and StorageClasses.
23

34
The Stackable Data Platform and its xref:operators:index.adoc[operators] deploy their products in https://kubernetes.io/docs/concepts/containers/[containers] within https://kubernetes.io/docs/concepts/workloads/pods/[Pods] using https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/[StatefulSets] or https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/[DaemonSets].
45
In order for the Kubernetes scheduler to select a suitable https://kubernetes.io/docs/concepts/architecture/nodes/[Node] for a Pod, https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/[resource] requests and limits for CPU and memory can be specified.

‎modules/concepts/pages/s3.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
= S3 resources
2+
:description: Explore how to configure S3 storage with Stackable using S3Connection and S3Bucket objects, including setup examples with credentials and TLS configuration.
23

34
// -------------- Intro ----------------
45

@@ -48,7 +49,7 @@ image::s3-overview.drawio.svg[A diagram showing four variations (A, B, C, D) of
4849
The diagram above shows four examples of how the objects can be structured.
4950

5051
// Variant A
51-
Variant A shows all S3 objects inlined in a DruidCluster resource. This is a very convenient way to quickly test something since the entire configuration is encapsulated in a single but potentially large manifest.
52+
Variant A shows all S3 objects inlined in a DruidCluster resource. This is a very convenient way to quickly test something since the entire configuration is encapsulated in a single but potentially large manifest.
5253

5354
// Variant B
5455
In variant B the S3 bucket has been split out into its own resource. It can now be referred to by multiple different tools as well.

‎modules/concepts/pages/service-discovery.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Service discovery ConfigMap
22
:page-aliases: service_discovery.adoc
3+
:description: Learn how Stackable's service discovery ConfigMap enables product connections, providing essential instance info for integration and external connections.
34

45
// Abstract
56
Stackable operators provide a _service discovery ConfigMap_ for each product instance that is deployed. **This ConfigMap has the same name as the product instance** and contains information about how to connect to the instance. The ConfigMap is used by other Operators to connect products together and can also be used by you, the user, to connect external software to Stackable-operated software.

‎modules/concepts/pages/service-exposition.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
= Service exposition
22
:k8s-service: https://kubernetes.io/docs/concepts/services-networking/service/
33
:k8s-service-types: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
4+
:description: Explore Stackable's service exposition options: ClusterIP for internal access, NodePort for unstable external access, and LoadBalancer for stable external access.
5+
46

57
Data products expose interfaces to the outside world.
68
These interfaces (whether UIs, or APIs) can be accessed by other products or by end users.

‎modules/concepts/pages/stacklet.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= Stacklet
22
:page-aliases: roles-and-role-groups.adoc
3+
:description: A Stacklet is a managed product in Kubernetes, consisting of roles and role groups. Roles allow general configuration of components, while role groups allow finer-grained control over specific groups of components.
34

45
A _Stacklet_ is a deployed product that is managed by a Stackable operator.
56
The running instance is made up of multiple pieces of software called _roles_ and can be further subdivided into _role groups_.
@@ -13,7 +14,7 @@ The products are usually deployed with StatefulSets from which Pods are created.
1314
Configuration is done with ConfigMaps, and the the software is exposed using Services.
1415
To allow for easier connectivity between Stacklets, some operators also deploy a xref:service-discovery.adoc[] for Stacklets they manage.
1516

16-
CAUTION: Watch out for name collisions when deploying multiple Stacklets in the same namespace!
17+
CAUTION: Watch out for name collisions when deploying multiple Stacklets in the same namespace!
1718
Even though the resource might be different (TrinoCluster, HbaseCluster), there is a name conflict for the discovery ConfigMap if two Stacklets in the same Kubernetes namespace share a name.
1819
It is best to always use unique names for Stacklets.
1920

‎modules/concepts/pages/tls-server-verification.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= TLS server verification
22
:page-aliases: tls_server_verification.adoc
3+
:description: Configure TLS server and mutual authentication with custom or public CA certificates.
34

45
A TLS section is part of Stackable CRDs and describes how to connect to a TLS enabled system like LDAP or S3.
56

0 commit comments

Comments
 (0)