From 38c741452c97867fcb6ed581be66b83fcdded76c Mon Sep 17 00:00:00 2001 From: Felix Hennig Date: Wed, 27 Dec 2023 08:56:55 +0100 Subject: [PATCH] reference docs (#398) --- docs/modules/hive/pages/configuration.adoc | 13 ------------- .../commandline-parameters.adoc} | 7 +++++-- docs/modules/hive/pages/reference/crds.adoc | 3 +++ .../hive/pages/{ => reference}/discovery.adoc | 11 ++++++----- .../environment-variables.adoc} | 7 +++++-- docs/modules/hive/pages/reference/index.adoc | 7 +++++++ docs/modules/hive/partials/nav.adoc | 9 ++++++--- 7 files changed, 32 insertions(+), 25 deletions(-) delete mode 100644 docs/modules/hive/pages/configuration.adoc rename docs/modules/hive/pages/{commandline_args.adoc => reference/commandline-parameters.adoc} (81%) create mode 100644 docs/modules/hive/pages/reference/crds.adoc rename docs/modules/hive/pages/{ => reference}/discovery.adoc (78%) rename docs/modules/hive/pages/{env_var_args.adoc => reference/environment-variables.adoc} (90%) create mode 100644 docs/modules/hive/pages/reference/index.adoc diff --git a/docs/modules/hive/pages/configuration.adoc b/docs/modules/hive/pages/configuration.adoc deleted file mode 100644 index 65ff9ab4..00000000 --- a/docs/modules/hive/pages/configuration.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= Configuration - -== Command Line Parameters - -This operator accepts the following command line parameters: - -include::commandline_args.adoc[] - -== Environment variables - -This operator accepts the following environment variables: - -include::env_var_args.adoc[] diff --git a/docs/modules/hive/pages/commandline_args.adoc b/docs/modules/hive/pages/reference/commandline-parameters.adoc similarity index 81% rename from docs/modules/hive/pages/commandline_args.adoc rename to docs/modules/hive/pages/reference/commandline-parameters.adoc index f1064c74..e3e0abec 100644 --- a/docs/modules/hive/pages/commandline_args.adoc +++ b/docs/modules/hive/pages/reference/commandline-parameters.adoc @@ -1,5 +1,8 @@ += Command line parameters -=== product-config +This operator accepts the following command line parameters: + +== product-config *Default value*: `/etc/stackable/hive-operator/config-spec/properties.yaml` @@ -12,7 +15,7 @@ stackable-hive-operator run --product-config /foo/bar/properties.yaml ---- -=== watch-namespace +== watch-namespace *Default value*: All namespaces diff --git a/docs/modules/hive/pages/reference/crds.adoc b/docs/modules/hive/pages/reference/crds.adoc new file mode 100644 index 00000000..9dc04b18 --- /dev/null +++ b/docs/modules/hive/pages/reference/crds.adoc @@ -0,0 +1,3 @@ += CRD Reference + +Find all CRD reference for the Stackable Operator for Apache Hive at: {crd-docs-base-url}/hive-operator/{crd-docs-version}. \ No newline at end of file diff --git a/docs/modules/hive/pages/discovery.adoc b/docs/modules/hive/pages/reference/discovery.adoc similarity index 78% rename from docs/modules/hive/pages/discovery.adoc rename to docs/modules/hive/pages/reference/discovery.adoc index 57117aa9..88441cb3 100644 --- a/docs/modules/hive/pages/discovery.adoc +++ b/docs/modules/hive/pages/reference/discovery.adoc @@ -2,10 +2,11 @@ :namespace: \{namespace\} :metastorePort: 9083 :roleGroup: \{roleGroup\} +:page-aliases: discovery.adoc = Discovery -The Stackable Operator for Apache Hive publishes a discovery https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#configmap-v1-core[`ConfigMap`], which exposes a client configuration bundle that allows access to the Apache Hive cluster. +The Stackable Operator for Apache Hive publishes a discovery https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#configmap-v1-core[ConfigMap], which exposes a client configuration bundle that allows access to the Apache Hive cluster. The bundle includes an Apache Thrift connection string to access the Hive Metastore service. This string may be used by other operators or tools to configure their products with access to Hive. Access is limited to services within the same Kubernetes cluster. @@ -32,17 +33,17 @@ spec: default: # <3> replicas: 2 ---- -<1> The name of the Hive cluster, which is also the name of the created discovery `ConfigMap`. -<2> The namespace of the discovery `ConfigMap`. +<1> The name of the Hive cluster, which is also the name of the created discovery ConfigMap. +<2> The namespace of the discovery ConfigMap. <3> A role group name of the metastore role. -The resulting discovery `ConfigMap` is `{namespace}/{clusterName}`. +The resulting discovery ConfigMap is `{namespace}/{clusterName}`. == Contents === Internal access -The `{namespace}/{clusterName}` discovery `ConfigMap` contains the following fields where `{clusterName}` represents the name, `{namespace}` the namespace of the cluster and `{roleGroup}` a role group of the `metastore` role: +The `{namespace}/{clusterName}` discovery ConfigMap contains the following fields where `{clusterName}` represents the name, `{namespace}` the namespace of the cluster and `{roleGroup}` a role group of the `metastore` role: `HIVE`:: ==== diff --git a/docs/modules/hive/pages/env_var_args.adoc b/docs/modules/hive/pages/reference/environment-variables.adoc similarity index 90% rename from docs/modules/hive/pages/env_var_args.adoc rename to docs/modules/hive/pages/reference/environment-variables.adoc index 659e352b..e87d910b 100644 --- a/docs/modules/hive/pages/env_var_args.adoc +++ b/docs/modules/hive/pages/reference/environment-variables.adoc @@ -1,5 +1,8 @@ += Environment variables -=== PRODUCT_CONFIG +This operator accepts the following environment variables: + +== PRODUCT_CONFIG *Default value*: `/etc/stackable/hive-operator/config-spec/properties.yaml` @@ -25,7 +28,7 @@ docker run \ docker.stackable.tech/stackable/hive-operator:latest ---- -=== WATCH_NAMESPACE +== WATCH_NAMESPACE *Default value*: All namespaces diff --git a/docs/modules/hive/pages/reference/index.adoc b/docs/modules/hive/pages/reference/index.adoc new file mode 100644 index 00000000..eeb572f1 --- /dev/null +++ b/docs/modules/hive/pages/reference/index.adoc @@ -0,0 +1,7 @@ += Reference + +Consult the reference documentation section to find exhaustive information on: + +* Descriptions and default values of all properties in the CRDs used by this operator in the xref:reference/crds.adoc[]. +* The properties in the xref:reference/discovery.adoc[]. +* The xref:reference/commandline-parameters.adoc[] and xref:reference/environment-variables.adoc[] accepted by the operator. diff --git a/docs/modules/hive/partials/nav.adoc b/docs/modules/hive/partials/nav.adoc index a0ec2cb4..165263a0 100644 --- a/docs/modules/hive/partials/nav.adoc +++ b/docs/modules/hive/partials/nav.adoc @@ -1,9 +1,6 @@ * xref:hive:getting_started/index.adoc[] ** xref:hive:getting_started/installation.adoc[] ** xref:hive:getting_started/first_steps.adoc[] -* xref:hive:configuration.adoc[] -* Concepts -** xref:hive:discovery.adoc[] * xref:hive:required-external-components.adoc[] * xref:hive:usage-guide/index.adoc[] ** xref:hive:usage-guide/listenerclass.adoc[] @@ -17,3 +14,9 @@ *** xref:hive:usage-guide/operations/pod-placement.adoc[] *** xref:hive:usage-guide/operations/pod-disruptions.adoc[] *** xref:hive:usage-guide/operations/graceful-shutdown.adoc[] +* xref:hive:reference/index.adoc[] +** xref:hive:reference/crds.adoc[] +*** {crd-docs}/hive.stackable.tech/hivecluster/v1alpha1/[HiveCluster {external-link-icon}^] +** xref:hive:reference/discovery.adoc[] +** xref:hive:reference/commandline-parameters.adoc[] +** xref:hive:reference/environment-variables.adoc[] \ No newline at end of file