From 16cbe8fc0817eed153fc953ad6e963caf0bc0e68 Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Tue, 10 Sep 2024 15:40:12 +0200 Subject: [PATCH 01/21] first batch of descriptions --- modules/concepts/pages/authentication.adoc | 1 + modules/concepts/pages/container-images.adoc | 1 + modules/concepts/pages/index.adoc | 1 + modules/concepts/pages/labels.adoc | 1 + modules/concepts/pages/logging.adoc | 1 + modules/concepts/pages/operations/cluster_operations.adoc | 1 + modules/concepts/pages/operations/graceful_shutdown.adoc | 1 + modules/concepts/pages/operations/index.adoc | 1 + modules/concepts/pages/operations/pod_disruptions.adoc | 1 + modules/concepts/pages/operations/pod_placement.adoc | 1 + 10 files changed, 10 insertions(+) diff --git a/modules/concepts/pages/authentication.adoc b/modules/concepts/pages/authentication.adoc index e2bd3a4d9..1f85af71c 100644 --- a/modules/concepts/pages/authentication.adoc +++ b/modules/concepts/pages/authentication.adoc @@ -1,5 +1,6 @@ = Authentication :keycloak: https://www.keycloak.org/ +:description: Overview of Stackable’s user authentication methods and configuration for LDAP, OIDC, TLS, and Static providers. The Stackable Platform uses the AuthenticationClass as a central mechanism to handle user authentication across supported products. The authentication mechanism needs to be configured only in the AuthenticationClass which is then referenced in the xref:stacklet.adoc[Stacklet] definition. diff --git a/modules/concepts/pages/container-images.adoc b/modules/concepts/pages/container-images.adoc index f83158a2d..243ccfa4b 100644 --- a/modules/concepts/pages/container-images.adoc +++ b/modules/concepts/pages/container-images.adoc @@ -2,6 +2,7 @@ :ubi: https://catalog.redhat.com/software/base-images :stackable-image-registry: https://repo.stackable.tech/#browse/browse :stackable-sboms: https://sboms.stackable.tech/ +:description: Overview of Stackable’s container images, including structure, multi-platform support, and why upstream images are not used. The core artifacts of the Stackable Data Platform are container images of Kubernetes operators and the products that these operators deploy. diff --git a/modules/concepts/pages/index.adoc b/modules/concepts/pages/index.adoc index aec67a86f..c74743eef 100644 --- a/modules/concepts/pages/index.adoc +++ b/modules/concepts/pages/index.adoc @@ -1,4 +1,5 @@ = Concepts +:description: Explore Stackable Data Platform concepts like Stacklets, configuration mechanisms, resources, connectivity, security, and observability. == Overview diff --git a/modules/concepts/pages/labels.adoc b/modules/concepts/pages/labels.adoc index 0b8391382..e3c8aac88 100644 --- a/modules/concepts/pages/labels.adoc +++ b/modules/concepts/pages/labels.adoc @@ -1,5 +1,6 @@ = Labels :common-labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/ +:description: Understand resource labeling by Stackable operators and tools like stackablectl and Helm for better management and organization. Labels are key/value pairs in the metadata of Kubernetes objects that add identifying information to the object. They do not have direct semantic implications but can be used to organize and manage resources. diff --git a/modules/concepts/pages/logging.adoc b/modules/concepts/pages/logging.adoc index 376cfbb41..188271032 100644 --- a/modules/concepts/pages/logging.adoc +++ b/modules/concepts/pages/logging.adoc @@ -8,6 +8,7 @@ :vector-agg-install: https://vector.dev/docs/setup/installation/package-managers/helm/#aggregator :vector-source-vector: https://vector.dev/docs/reference/configuration/sources/vector/ :vector-topology-centralized: https://vector.dev/docs/setup/deployment/topologies/#centralized +:description: Learn Stackable's logging setup: human-readable and aggregated logs with Vector, consistent configuration across Stacklets, and custom overrides. Logging is important for observability of the platform. Stackable provides human-readable plaintext logs for each running container, as well as aggregated and persisted logs with identical structure across the whole platform. diff --git a/modules/concepts/pages/operations/cluster_operations.adoc b/modules/concepts/pages/operations/cluster_operations.adoc index 1d408132d..4acc4db35 100644 --- a/modules/concepts/pages/operations/cluster_operations.adoc +++ b/modules/concepts/pages/operations/cluster_operations.adoc @@ -1,5 +1,6 @@ = Cluster operations :page-aliases: ../cluster_operations.adoc +:description: Manage Stackable clusters with operations like pausing reconciliation, stopping Pods, and manual/automatic restarts. Learn how to update and restart services effectively. Stackable operators offer different cluster operations to control the reconciliation process. This is useful when updating operators, debugging or testing of new settings: diff --git a/modules/concepts/pages/operations/graceful_shutdown.adoc b/modules/concepts/pages/operations/graceful_shutdown.adoc index e2241bc72..b09a60b1e 100644 --- a/modules/concepts/pages/operations/graceful_shutdown.adoc +++ b/modules/concepts/pages/operations/graceful_shutdown.adoc @@ -1,4 +1,5 @@ = Graceful shutdown +:description: Graceful shutdown ensures a controlled, clean shutdown of service instances, allowing time for normal shutdown activities. Graceful shutdown refers to the managed, controlled shutdown of service instances in the manner intended by the software authors. Typically, an instance will receive a signal indicating the intent for the server to shut down, and it will initiate a controlled shutdown. diff --git a/modules/concepts/pages/operations/index.adoc b/modules/concepts/pages/operations/index.adoc index 1203113cb..9f16192ab 100644 --- a/modules/concepts/pages/operations/index.adoc +++ b/modules/concepts/pages/operations/index.adoc @@ -1,4 +1,5 @@ = Operations +:description: Guidance for maintaining Stackable Data Platform installations. Covers service availability, maintenance actions, and performance optimization. This section of the documentation is intended for the operations teams that maintain a Stackable Data Platform installation. It provides you with the necessary details to operate it in a production environment. diff --git a/modules/concepts/pages/operations/pod_disruptions.adoc b/modules/concepts/pages/operations/pod_disruptions.adoc index b56f5fc1e..c9bbf561a 100644 --- a/modules/concepts/pages/operations/pod_disruptions.adoc +++ b/modules/concepts/pages/operations/pod_disruptions.adoc @@ -1,5 +1,6 @@ = Allowed Pod disruptions :k8s-pdb: https://kubernetes.io/docs/tasks/run-application/configure-pdb/ +:description: Configure PodDisruptionBudgets (PDBs) to minimize planned downtime for Stackable products. Default values are based on fault tolerance and can be customized. Any downtime of our products is generally considered to be bad. 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. diff --git a/modules/concepts/pages/operations/pod_placement.adoc b/modules/concepts/pages/operations/pod_placement.adoc index ea5e90b01..ca8c17abd 100644 --- a/modules/concepts/pages/operations/pod_placement.adoc +++ b/modules/concepts/pages/operations/pod_placement.adoc @@ -1,5 +1,6 @@ = Pod placement :page-aliases: ../pod_placement.adoc +:description: Configure pod affinity, anti-affinity, and node affinity for Stackable Data Platform operators using YAML definitions. 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]. 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. From d53aa009cf185e61b7baba3566fb8f4188219637 Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Tue, 10 Sep 2024 15:57:39 +0200 Subject: [PATCH 02/21] more descriptions --- modules/concepts/pages/multi-platform-support.adoc | 6 ++---- modules/concepts/pages/opa.adoc | 1 + modules/concepts/pages/overrides.adoc | 1 + modules/concepts/pages/overview.adoc | 1 + modules/concepts/pages/product-image-selection.adoc | 2 +- modules/concepts/pages/resources.adoc | 1 + modules/concepts/pages/s3.adoc | 1 + modules/concepts/pages/service-discovery.adoc | 1 + modules/concepts/pages/service-exposition.adoc | 2 ++ modules/concepts/pages/stacklet.adoc | 1 + modules/concepts/pages/tls-server-verification.adoc | 1 + 11 files changed, 13 insertions(+), 5 deletions(-) diff --git a/modules/concepts/pages/multi-platform-support.adoc b/modules/concepts/pages/multi-platform-support.adoc index 015ae5f75..55bda5a09 100644 --- a/modules/concepts/pages/multi-platform-support.adoc +++ b/modules/concepts/pages/multi-platform-support.adoc @@ -1,13 +1,11 @@ = Multi-platform for SDP -:description: This page describes multi-platform support for AMD64 and ARM64 :keywords: Multi-Architecture, infrastructure, docker, image, tags :multi-platform-images: https://docs.docker.com/build/building/multi-platform/ +:description: Starting with Stackable 24.7, all images support AMD64 and ARM64 architectures, enabling mixed clusters with architecture-specific tags and automated selection. WARNING: This status is still experimental, as we work to fine-tune the necessary workflows. -== Description - -Starting with Stackable release 24.7, all images are {multi-platform-images}[multi-platform images], supporting the AMD64 and ARM64 architectures. +Starting with the Stackable Data Platform release 24.7, all images are {multi-platform-images}[multi-platform images], supporting the AMD64 and ARM64 architectures. Each product image is built for each platform with an architecture-specific tag. 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. The appropriate image will then be transparently selected for the active platform/architecture. diff --git a/modules/concepts/pages/opa.adoc b/modules/concepts/pages/opa.adoc index a8e363b4b..a67968109 100644 --- a/modules/concepts/pages/opa.adoc +++ b/modules/concepts/pages/opa.adoc @@ -2,6 +2,7 @@ :opa: https://www.openpolicyagent.org :rego: https://www.openpolicyagent.org/docs/latest/policy-language/ :opa-docs: https://www.openpolicyagent.org/docs/latest/#overview +:description: Stackable Data Platform uses OpenPolicyAgent (OPA) for policy-based access control with Rego rules, ensuring efficient, local policy evaluation across nodes. The Stackable Data Platform offers policy-based access control via the {opa}[OpenPolicyAgent] (OPA) operator. Authorization policies are defined in the {rego}[Rego] language, divided into packages and supplied via ConfigMaps. diff --git a/modules/concepts/pages/overrides.adoc b/modules/concepts/pages/overrides.adoc index 5e12cdeda..300264a21 100644 --- a/modules/concepts/pages/overrides.adoc +++ b/modules/concepts/pages/overrides.adoc @@ -1,5 +1,6 @@ = Overrides :k8s-openapi-deepmerge: https://arnavion.github.io/k8s-openapi/v0.22.x/k8s_openapi/trait.DeepMerge.html +:description: Stackable operators support configuration overrides for Stacklets, including settings for config files, environment variables, and Pod specifications, with precedence rules. The Stackable operators configure the xref:stacklet.adoc[Stacklets] they are operating with sensible defaults and required settings to enable connectivity and security. Other important settings are usually exposed in the Stacklet resource definition for you to configure directly. diff --git a/modules/concepts/pages/overview.adoc b/modules/concepts/pages/overview.adoc index 8452b5f23..00b6c52a2 100644 --- a/modules/concepts/pages/overview.adoc +++ b/modules/concepts/pages/overview.adoc @@ -1,4 +1,5 @@ = Stackable Data Platform explained +:description: The Stackable Data Platform leverages Kubernetes operators to manage products like ZooKeeper and HDFS, using custom resources for deployment and configuration. The Stackable Data Platform (SDP) is built on Kubernetes. Its core is a collection of Kubernetes Operators and CustomResourceDefinitions which are designed to work together. diff --git a/modules/concepts/pages/product-image-selection.adoc b/modules/concepts/pages/product-image-selection.adoc index 6e895abb3..efcc62e40 100644 --- a/modules/concepts/pages/product-image-selection.adoc +++ b/modules/concepts/pages/product-image-selection.adoc @@ -1,7 +1,7 @@ = Product image selection :page-aliases: product_image_selection.adoc -:description: This page describes the different ways of specifying a product image to use in your product deployment. :keywords: Kubernetes, operator, docker, registry, custom image, tags +:description: Learn how to specify product images for Stackable Data Platform deployments, including using default, custom, or mirrored registries. 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). The simplest way to do this is this: diff --git a/modules/concepts/pages/resources.adoc b/modules/concepts/pages/resources.adoc index 0a41e7be4..a1b00fe78 100644 --- a/modules/concepts/pages/resources.adoc +++ b/modules/concepts/pages/resources.adoc @@ -1,4 +1,5 @@ = Resource management +:description: Learn how to manage CPU, memory, and storage resources for Stackable Data Platform products, including setting requests, limits, and StorageClasses. 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]. 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. diff --git a/modules/concepts/pages/s3.adoc b/modules/concepts/pages/s3.adoc index 20a8ce22e..ba27c41cd 100644 --- a/modules/concepts/pages/s3.adoc +++ b/modules/concepts/pages/s3.adoc @@ -1,4 +1,5 @@ = S3 resources +:description: Explore how to configure S3 storage with Stackable using S3Connection and S3Bucket objects, including setup examples, credentials, and TLS configuration. // -------------- Intro ---------------- diff --git a/modules/concepts/pages/service-discovery.adoc b/modules/concepts/pages/service-discovery.adoc index 71841ba7f..a65cac4a0 100644 --- a/modules/concepts/pages/service-discovery.adoc +++ b/modules/concepts/pages/service-discovery.adoc @@ -1,5 +1,6 @@ = Service discovery ConfigMap :page-aliases: service_discovery.adoc +:description: Learn how Stackable's service discovery ConfigMap enables product connections, providing essential instance info for integration and external connections. // Abstract 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. diff --git a/modules/concepts/pages/service-exposition.adoc b/modules/concepts/pages/service-exposition.adoc index 0471de9a2..5520bc8e8 100644 --- a/modules/concepts/pages/service-exposition.adoc +++ b/modules/concepts/pages/service-exposition.adoc @@ -1,6 +1,8 @@ = Service exposition :k8s-service: https://kubernetes.io/docs/concepts/services-networking/service/ :k8s-service-types: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types +:description: Explore Stackable's service exposition options: ClusterIP for internal access, NodePort for unstable external access, and LoadBalancer for stable external access. + Data products expose interfaces to the outside world. These interfaces (whether UIs, or APIs) can be accessed by other products or by end users. diff --git a/modules/concepts/pages/stacklet.adoc b/modules/concepts/pages/stacklet.adoc index dc2b77ddb..cf3401fa8 100644 --- a/modules/concepts/pages/stacklet.adoc +++ b/modules/concepts/pages/stacklet.adoc @@ -1,5 +1,6 @@ = Stacklet :page-aliases: roles-and-role-groups.adoc +:description: A Stacklet is a managed product in Kubernetes, consisting of roles and role groups. Roles define components, while role groups allow fine-grained control over configurations. A _Stacklet_ is a deployed product that is managed by a Stackable operator. The running instance is made up of multiple pieces of software called _roles_ and can be further subdivided into _role groups_. diff --git a/modules/concepts/pages/tls-server-verification.adoc b/modules/concepts/pages/tls-server-verification.adoc index bae116895..1be638236 100644 --- a/modules/concepts/pages/tls-server-verification.adoc +++ b/modules/concepts/pages/tls-server-verification.adoc @@ -1,5 +1,6 @@ = TLS server verification :page-aliases: tls_server_verification.adoc +:description: TLS server verification in Stackable CRDs supports no, server, and mutual verification methods for secure connections. Configure TLS with custom or public CA certificates. A TLS section is part of Stackable CRDs and describes how to connect to a TLS enabled system like LDAP or S3. From 70f203be8f267ef8febc388f847256aa9fb18339 Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Tue, 10 Sep 2024 16:08:16 +0200 Subject: [PATCH 03/21] pre-commit fixes --- modules/concepts/pages/container-images.adoc | 2 +- modules/concepts/pages/index.adoc | 2 +- modules/concepts/pages/logging.adoc | 2 +- modules/concepts/pages/multi-platform-support.adoc | 2 +- modules/concepts/pages/operations/cluster_operations.adoc | 2 +- modules/concepts/pages/overview.adoc | 2 +- modules/concepts/pages/s3.adoc | 2 +- modules/concepts/pages/stacklet.adoc | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/modules/concepts/pages/container-images.adoc b/modules/concepts/pages/container-images.adoc index 243ccfa4b..21eff4fcd 100644 --- a/modules/concepts/pages/container-images.adoc +++ b/modules/concepts/pages/container-images.adoc @@ -38,7 +38,7 @@ See our documentation xref:concepts:multi-platform-support.adoc[on multi-platfor [#signatures] == Image signatures -All Stackable images are signed. +All Stackable images are signed. Image signatures help to ensure the authenticity and integrity of container images. 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. diff --git a/modules/concepts/pages/index.adoc b/modules/concepts/pages/index.adoc index c74743eef..44eccd3a1 100644 --- a/modules/concepts/pages/index.adoc +++ b/modules/concepts/pages/index.adoc @@ -18,7 +18,7 @@ Learn about how to access xref:experimental-arm64-support[ARM64-support]. == Connectivity -Many Platform components depend on other components or expose functionality that you can connect to. +Many Platform components depend on other components or expose functionality that you can connect to. This connectivity is achived with xref:service-discovery.adoc[service discovery ConfigMaps]. To access your Stackable operated products from outside the Kuberenetes cluster learn more about xref:service-exposition.adoc[]. diff --git a/modules/concepts/pages/logging.adoc b/modules/concepts/pages/logging.adoc index 188271032..2b8bc1b61 100644 --- a/modules/concepts/pages/logging.adoc +++ b/modules/concepts/pages/logging.adoc @@ -94,7 +94,7 @@ spec: level: NONE sidecar-container: console: - level: ERROR + level: ERROR ---- <1> The discovery ConfigMap of the Vector aggregator to publish the logs to. This is set at cluster level. <2> The role or role group config containing the logging configuration. diff --git a/modules/concepts/pages/multi-platform-support.adoc b/modules/concepts/pages/multi-platform-support.adoc index 55bda5a09..146fac564 100644 --- a/modules/concepts/pages/multi-platform-support.adoc +++ b/modules/concepts/pages/multi-platform-support.adoc @@ -11,4 +11,4 @@ For example, the Airflow images with tags `airflow:2.9.2-stackable24.7.0-amd64` The appropriate image will then be transparently selected for the active platform/architecture. This also enables mixed Kubernetes clusters, with AMD64 and ARM64 nodes being used simultaneously. -NOTE: Superset 2.x (deprecated, and to be removed in a future version) is not available as a multi-platform product image. \ No newline at end of file +NOTE: Superset 2.x (deprecated, and to be removed in a future version) is not available as a multi-platform product image. diff --git a/modules/concepts/pages/operations/cluster_operations.adoc b/modules/concepts/pages/operations/cluster_operations.adoc index 4acc4db35..95ceb3ac5 100644 --- a/modules/concepts/pages/operations/cluster_operations.adoc +++ b/modules/concepts/pages/operations/cluster_operations.adoc @@ -98,7 +98,7 @@ To restart the HDFS DataNode Pods, run: [source,shell] ---- -$ kubectl rollout restart statefulset dumbo-datanode-default +$ kubectl rollout restart statefulset dumbo-datanode-default statefulset.apps/dumbo-datanode-default restarted ---- diff --git a/modules/concepts/pages/overview.adoc b/modules/concepts/pages/overview.adoc index 00b6c52a2..ecbbf022c 100644 --- a/modules/concepts/pages/overview.adoc +++ b/modules/concepts/pages/overview.adoc @@ -77,4 +77,4 @@ image::common_objects.drawio.svg[] 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[]. -Similarly for the OpenPolicyAgent (OPA). Configuring it looks the same across all products. Learn more: xref:opa.adoc[]. \ No newline at end of file +Similarly for the OpenPolicyAgent (OPA). Configuring it looks the same across all products. Learn more: xref:opa.adoc[]. diff --git a/modules/concepts/pages/s3.adoc b/modules/concepts/pages/s3.adoc index ba27c41cd..2165e9a22 100644 --- a/modules/concepts/pages/s3.adoc +++ b/modules/concepts/pages/s3.adoc @@ -49,7 +49,7 @@ image::s3-overview.drawio.svg[A diagram showing four variations (A, B, C, D) of The diagram above shows four examples of how the objects can be structured. // Variant A -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. +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. // Variant B 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. diff --git a/modules/concepts/pages/stacklet.adoc b/modules/concepts/pages/stacklet.adoc index cf3401fa8..764830ec3 100644 --- a/modules/concepts/pages/stacklet.adoc +++ b/modules/concepts/pages/stacklet.adoc @@ -14,7 +14,7 @@ The products are usually deployed with StatefulSets from which Pods are created. Configuration is done with ConfigMaps, and the the software is exposed using Services. To allow for easier connectivity between Stacklets, some operators also deploy a xref:service-discovery.adoc[] for Stacklets they manage. -CAUTION: Watch out for name collisions when deploying multiple Stacklets in the same namespace! +CAUTION: Watch out for name collisions when deploying multiple Stacklets in the same namespace! 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. It is best to always use unique names for Stacklets. From 7ad480a35095f6a39fd37c8420a7240ddb717895 Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Tue, 10 Sep 2024 16:12:10 +0200 Subject: [PATCH 04/21] more descriptions --- modules/guides/pages/custom-images.adoc | 2 +- .../guides/pages/enabling-verification-of-image-signatures.adoc | 1 + modules/guides/pages/providing-resources-with-pvcs.adoc | 1 + .../pages/running-stackable-in-an-airgapped-environment.adoc | 1 + modules/guides/pages/viewing-and-verifying-sboms.adoc | 1 + 5 files changed, 5 insertions(+), 1 deletion(-) diff --git a/modules/guides/pages/custom-images.adoc b/modules/guides/pages/custom-images.adoc index 94e65cb00..616666dd0 100644 --- a/modules/guides/pages/custom-images.adoc +++ b/modules/guides/pages/custom-images.adoc @@ -1,8 +1,8 @@ = Using customized product images - :stackable-docker-registry: https://repo.stackable.tech/#browse/browse:docker:v2%2Fstackable :kind: https://kind.sigs.k8s.io/ :kind-load-image: https://kind.sigs.k8s.io/docs/user/quick-start/#loading-an-image-into-your-cluster +:description: Customize Stackable product images by modifying base images, deploying to a registry or Kubernetes cluster, and configuring your Stacklet to use them. The Stackable operator require a certain structure inside the product images, but modifications can be made. This is useful to for example load additional extensions or database drivers into an image. diff --git a/modules/guides/pages/enabling-verification-of-image-signatures.adoc b/modules/guides/pages/enabling-verification-of-image-signatures.adoc index 69152f2d4..e2e4b2cf1 100644 --- a/modules/guides/pages/enabling-verification-of-image-signatures.adoc +++ b/modules/guides/pages/enabling-verification-of-image-signatures.adoc @@ -1,5 +1,6 @@ = Enabling verification of image signatures :page-aliases: tutorials:enabling-verification-of-image-signatures.adoc +:description: Learn to enable and verify image signatures in Kubernetes using Sigstore’s Policy Controller, ensuring image authenticity and security in your cluster. Image signing is a security measure that helps ensure the authenticity and integrity of container images. Starting with SDP 23.11, all our images are signed https://docs.sigstore.dev/cosign/openid_signing/["keyless"]. By verifying these signatures, cluster administrators can ensure that the images pulled from Stackable's container registry are authentic and have not been tampered with. Since Kubernetes does not have native support for verifying image signatures yet, we will use Sigstore's https://docs.sigstore.dev/policy-controller/overview/[Policy Controller] in this tutorial. diff --git a/modules/guides/pages/providing-resources-with-pvcs.adoc b/modules/guides/pages/providing-resources-with-pvcs.adoc index eb0280d03..7c6cd82d8 100644 --- a/modules/guides/pages/providing-resources-with-pvcs.adoc +++ b/modules/guides/pages/providing-resources-with-pvcs.adoc @@ -3,6 +3,7 @@ :pvcs: https://kubernetes.io/docs/concepts/storage/persistent-volumes/ :pvc-capacity: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#capacity :pvc-access-modes: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes +:description: Learn how to use PersistentVolumeClaims to provide external resources to Stacklets in Kubernetes, including access modes, node selection, and practical examples. Several of the tools on the Stackable platform can use external resources that the cluster administrator makes available via a PersistentVolume. Airflow users can access DAG jobs this way, and Spark users can do the same for data or other job dependencies, to name just two examples. diff --git a/modules/guides/pages/running-stackable-in-an-airgapped-environment.adoc b/modules/guides/pages/running-stackable-in-an-airgapped-environment.adoc index 06a005bbe..843fad6bc 100644 --- a/modules/guides/pages/running-stackable-in-an-airgapped-environment.adoc +++ b/modules/guides/pages/running-stackable-in-an-airgapped-environment.adoc @@ -1,5 +1,6 @@ = Running Stackable in an air-gapped environment :page-aliases: tutorials:running-stackable-in-an-airgapped-environment.adoc +:description: Learn how to run Stackable in an air-gapped environment by mirroring images, setting up a reverse proxy, and configuring container runtimes. The main challenge with running Stackable in an air-gapped environment is how to get the artifacts (container images and Helm charts) into the environment. There are a few ways to do this: diff --git a/modules/guides/pages/viewing-and-verifying-sboms.adoc b/modules/guides/pages/viewing-and-verifying-sboms.adoc index 128f9e0b8..4558e4876 100644 --- a/modules/guides/pages/viewing-and-verifying-sboms.adoc +++ b/modules/guides/pages/viewing-and-verifying-sboms.adoc @@ -1,5 +1,6 @@ = Viewing and verifying SBOMs of the Stackable Data Platform :page-aliases: tutorials:viewing-and-verifying-sboms.adoc +:description: Learn to view and verify SBOMs for Stackable Data Platform using CycloneDX standards and cosign. Ensure SBOM authenticity with Policy Controller. With release 24.3 of SDP, we started providing SBOMs (Software Bill of Materials) for our container images. Please note that they currently are in a draft stage and we are continually working on improving them. As a first step, we aim to provide a list of all primary (top level) components and their versions included in each container image. Our SBOMs follow the https://cyclonedx.org/[CycloneDX] standard and are available in JSON format. From 5547b3b9389419ee40bb3927f5183142922ed656 Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Tue, 10 Sep 2024 16:24:11 +0200 Subject: [PATCH 05/21] linter fixes --- .../guides/pages/enabling-verification-of-image-signatures.adoc | 2 +- modules/guides/pages/viewing-and-verifying-sboms.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/guides/pages/enabling-verification-of-image-signatures.adoc b/modules/guides/pages/enabling-verification-of-image-signatures.adoc index e2e4b2cf1..df0171028 100644 --- a/modules/guides/pages/enabling-verification-of-image-signatures.adoc +++ b/modules/guides/pages/enabling-verification-of-image-signatures.adoc @@ -94,4 +94,4 @@ There's a lot more to learn about how keyless signing and verification works. We * https://docs.sigstore.dev/signing/overview/ * https://docs.sigstore.dev/policy-controller/overview/ * https://www.chainguard.dev/unchained/life-of-a-sigstore-signature -* https://blog.sigstore.dev/why-you-cant-use-sigstore-without-sigstore-de1ed745f6fc/ \ No newline at end of file +* https://blog.sigstore.dev/why-you-cant-use-sigstore-without-sigstore-de1ed745f6fc/ diff --git a/modules/guides/pages/viewing-and-verifying-sboms.adoc b/modules/guides/pages/viewing-and-verifying-sboms.adoc index 4558e4876..df4dd5fa1 100644 --- a/modules/guides/pages/viewing-and-verifying-sboms.adoc +++ b/modules/guides/pages/viewing-and-verifying-sboms.adoc @@ -77,4 +77,4 @@ kubectl label namespace stackable policy.sigstore.dev/include=true ---- The Policy Controller checks all newly created Pods in this namespace that run any image matching `+++**+++.stackable.tech/+++**+++` (this matches images provided by Stackable) and ensures that these images have an attested SBOM that's been signed by a Stackable Github Action. If no SBOM is present or its signature is invalid or missing, the policy will deny the pod creation. -For a more detailed explanation of the policy options, please refer to the https://docs.sigstore.dev/policy-controller/overview/#configuring-image-patterns[Sigstore documentation]. \ No newline at end of file +For a more detailed explanation of the policy options, please refer to the https://docs.sigstore.dev/policy-controller/overview/#configuring-image-patterns[Sigstore documentation]. From effadccf7f19b5929613942de23f792ca757f402 Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Tue, 10 Sep 2024 16:28:47 +0200 Subject: [PATCH 06/21] linter fixes --- .../pages/running-stackable-in-an-airgapped-environment.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/guides/pages/running-stackable-in-an-airgapped-environment.adoc b/modules/guides/pages/running-stackable-in-an-airgapped-environment.adoc index 843fad6bc..49305d539 100644 --- a/modules/guides/pages/running-stackable-in-an-airgapped-environment.adoc +++ b/modules/guides/pages/running-stackable-in-an-airgapped-environment.adoc @@ -34,4 +34,4 @@ Then restart the `containerd` service. Now `containerd` will fetch all images th * Add an alias for `docker.stackable.tech` to the `/etc/hosts` file on every node (like `10.7.228.12 docker.stackable.tech`), issue a self-signed certificate for `docker.stackable.tech` to your registry and add the certificate to the trusted certificates on every node. Note that if you also want to enforce signature checks for Stackable's images via a policy controller, you will need to add this host alias to the Pod of the policy controller as well (and make it trust the certificate). -If you want to know how to verify image signatures in an air-gapped environment, check out our documentation about xref:enabling-verification-of-image-signatures.adoc[image signature verification]. \ No newline at end of file +If you want to know how to verify image signatures in an air-gapped environment, check out our documentation about xref:enabling-verification-of-image-signatures.adoc[image signature verification]. From fde1c91ca45ecd33deb36b2fb1dc1e5c171777df Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Tue, 10 Sep 2024 16:32:50 +0200 Subject: [PATCH 07/21] more descriptions --- modules/reference/pages/duration.adoc | 2 +- modules/reference/pages/glossary.adoc | 3 ++- modules/tutorials/pages/authentication_with_openldap.adoc | 7 +++++-- modules/tutorials/pages/index.adoc | 1 + 4 files changed, 9 insertions(+), 4 deletions(-) diff --git a/modules/reference/pages/duration.adoc b/modules/reference/pages/duration.adoc index 62620fc8b..bf2baad47 100644 --- a/modules/reference/pages/duration.adoc +++ b/modules/reference/pages/duration.adoc @@ -1,10 +1,10 @@ = Duration format :page-aliases: concepts:duration.adoc - :rust-duration-max: https://doc.rust-lang.org/std/time/struct.Duration.html#associatedconstant.MAX :go-std-time: https://cs.opensource.google/go/go/+/refs/tags/go1.21.2:src/time/format.go;l=1589 :k8s-cr: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ :go: https://go.dev/ +:description: nderstand the human-readable duration format used by Stackable operators, based on Go's time.ParseDuration, with units like days, hours, minutes, and seconds. All Stackable operators use a human-readable duration format. It very closely resembles the format used by the {go}[Go] programming language - which Kubernetes uses internally. Every duration field of a {k8s-cr}[CustomResource], for example, the xref:trino:usage-guide/operations/graceful-shutdown.adoc[`spec.workers.roleConfig.gracefulShutdownTimeout`] field, supports this format. diff --git a/modules/reference/pages/glossary.adoc b/modules/reference/pages/glossary.adoc index 101d0d9de..12e5440b9 100644 --- a/modules/reference/pages/glossary.adoc +++ b/modules/reference/pages/glossary.adoc @@ -1,5 +1,6 @@ = Glossary :li: pass:[] +:description: Glossary of Stackable terms, including "Role," "Role Group," and "Stacklet," with definitions and links to detailed explanations. // refined styling for the glossary ++++ @@ -54,4 +55,4 @@ Learn more about xref:concepts:stacklet.adoc#role-groups[role groups]. A Stacklet is defined by a custom resource like AirflowCluster or DruidCluster. The term refers to the defining resource and all the resources that belong to it, which are created by the operator, such as StatefulSets, Services, Secrets and ConfigMaps. All objects together are the Stacklet. -==== \ No newline at end of file +==== diff --git a/modules/tutorials/pages/authentication_with_openldap.adoc b/modules/tutorials/pages/authentication_with_openldap.adoc index 9e679f67f..0dcd548b0 100644 --- a/modules/tutorials/pages/authentication_with_openldap.adoc +++ b/modules/tutorials/pages/authentication_with_openldap.adoc @@ -1,4 +1,7 @@ = Authentication with OpenLDAP +:kind: https://kind.sigs.k8s.io/ +:k9s: https://k9scli.io/ +:description: Learn how to set up LDAP authentication for Stackable's Superset and Trino products, including installing OpenLDAP and configuring authentication classes. The Stackable platform supports user authentication with LDAP in multiple products. This page guides you through setting up the configuration necessary to use an existing LDAP installation with Stackable supported products. You can learn @@ -6,10 +9,10 @@ more about authentication in the Stackable Platform on the xref:concepts:authent Prerequisites: -* a k8s cluster available, or https://kind.sigs.k8s.io/[kind] installed +* a k8s cluster available, or {kind}[kind] installed * xref:management:stackablectl:index.adoc[] installed * basic knowledge of how to create resources in Kubernetes (i.e. `kubectl apply -f .yaml`) and inspect them - (`kubectl get` or a tool like https://k9scli.io/[k9s]) + (`kubectl get` or a tool like {k9s}[k9s]) == Setup diff --git a/modules/tutorials/pages/index.adoc b/modules/tutorials/pages/index.adoc index 734e3b673..d8781e2a5 100644 --- a/modules/tutorials/pages/index.adoc +++ b/modules/tutorials/pages/index.adoc @@ -1,4 +1,5 @@ = Tutorials +:description: Explore Stackable Data Platform tutorials for feature setup, product operators, and getting started guides for Airflow, Druid, HBase, and more. Tutorials help you learn about a specific aspect of the Stackable Data Platform in a hands-on way. From 8e64744078feacd1c6ffcfaa8889770dce4896e0 Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Tue, 10 Sep 2024 16:37:47 +0200 Subject: [PATCH 08/21] more descriptions --- modules/ROOT/pages/export.adoc | 1 + modules/ROOT/pages/getting-started.adoc | 1 + modules/ROOT/pages/index.adoc | 2 +- modules/ROOT/pages/licenses.adoc | 1 + modules/ROOT/pages/policies.adoc | 1 + modules/ROOT/pages/product-information.adoc | 2 ++ modules/ROOT/pages/quickstart.adoc | 2 +- modules/ROOT/pages/release-notes.adoc | 1 + 8 files changed, 9 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/export.adoc b/modules/ROOT/pages/export.adoc index c55a2d6d5..c99e19d92 100644 --- a/modules/ROOT/pages/export.adoc +++ b/modules/ROOT/pages/export.adoc @@ -1,4 +1,5 @@ = Export Control +: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. == USA diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc index e3989329e..360354f6c 100644 --- a/modules/ROOT/pages/getting-started.adoc +++ b/modules/ROOT/pages/getting-started.adoc @@ -1,5 +1,6 @@ = Getting Started :page-aliases: getting_started.adoc +:description: Learn how to set up and test a Stackable Data Platform with Apache ZooKeeper, Kafka, and NiFi using Kubernetes. Ideal for lab environments. 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. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index f47a42bf2..3557b3abd 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -1,10 +1,10 @@ = Stackable Documentation :page-layout: landing - :k8s-operators: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ :docs-discussion: https://github.com/stackabletech/community/discussions :docs-issues: https://github.com/stackabletech/documentation/issues :docs-repo: https://github.com/stackabletech/documentation +:description: User Documentation for the Stackable Data Platform. ++++