From b59eb700f57e7dc95f59373d0f83526c9c2a4a2a Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 29 Aug 2023 07:56:10 -0400 Subject: [PATCH] [DOCS] Remove unneeded `ifeval`s from install docs (#98952) Problem: The current install docs contain several `ifeval` statements that hide commands and code snippets based on the branch's release state. These statements make the Asciidoc hard to read and maintain. It also makes doc changes difficult to preview. Solution: Remove `ifeval` statements that hide commands or code snippets. Leave in any `ifeval` statements used to add warnings. (cherry picked from commit 1301995a4616df4f481146c1de4aa4fb12371030) --- docs/plugins/install_remove.asciidoc | 5 +--- docs/reference/setup/install/deb.asciidoc | 12 ++------ docs/reference/setup/install/docker.asciidoc | 28 +++---------------- docs/reference/setup/install/rpm.asciidoc | 12 ++------ docs/reference/setup/install/targz.asciidoc | 12 ++------ .../setup/install/zip-windows.asciidoc | 6 +--- .../setup/run-elasticsearch-locally.asciidoc | 8 ++---- 7 files changed, 14 insertions(+), 69 deletions(-) diff --git a/docs/plugins/install_remove.asciidoc b/docs/plugins/install_remove.asciidoc index 0bb9e68049847..c9d163fb30ef2 100644 --- a/docs/plugins/install_remove.asciidoc +++ b/docs/plugins/install_remove.asciidoc @@ -4,12 +4,10 @@ ifeval::["{release-state}"=="unreleased"] -Version {version} of the Elastic Stack has not yet been released. +WARNING: Version {version} of the Elastic Stack has not yet been released. endif::[] -ifeval::["{release-state}"!="unreleased"] - This plugin can be installed using the plugin manager: ["source","sh",subs="attributes,callouts"] @@ -25,7 +23,6 @@ install>> from {plugin_url}/{plugin_name}/{plugin_name}-{version}.zip. To verify the `.zip` file, use the {plugin_url}/{plugin_name}/{plugin_name}-{version}.zip.sha512[SHA hash] or {plugin_url}/{plugin_name}/{plugin_name}-{version}.zip.asc[ASC key]. -endif::[] [discrete] [id="{plugin_name}-remove"] diff --git a/docs/reference/setup/install/deb.asciidoc b/docs/reference/setup/install/deb.asciidoc index dd58391c37369..edaed7c785489 100644 --- a/docs/reference/setup/install/deb.asciidoc +++ b/docs/reference/setup/install/deb.asciidoc @@ -30,12 +30,10 @@ wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearm ifeval::["{release-state}"=="unreleased"] -Version {version} of Elasticsearch has not yet been released. +WARNING: Version {version} of Elasticsearch has not yet been released. endif::[] -ifeval::["{release-state}"!="unreleased"] - You may need to install the `apt-transport-https` package on Debian before proceeding: [source,sh] @@ -52,8 +50,6 @@ ifeval::["{release-state}"=="released"] echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/{major-version}/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-{major-version}.list -------------------------------------------------- -endif::[] - ifeval::["{release-state}"=="prerelease"] ["source","sh",subs="attributes,callouts"] @@ -110,12 +106,10 @@ include::skip-set-kernel-parameters.asciidoc[] ifeval::["{release-state}"=="unreleased"] -Version {version} of Elasticsearch has not yet been released. +WARNING: Version {version} of Elasticsearch has not yet been released. endif::[] -ifeval::["{release-state}"!="unreleased"] - The Debian package for Elasticsearch v{version} can be downloaded from the website and installed as follows: ["source","sh",subs="attributes"] @@ -128,8 +122,6 @@ sudo dpkg -i elasticsearch-{version}-amd64.deb <1> Compares the SHA of the downloaded Debian package and the published checksum, which should output `elasticsearch-{version}-amd64.deb: OK`. -endif::[] - // Set a `distro` attribute so we can reuse files containing anchors :distro: deb [id="deb-security-configuration"] diff --git a/docs/reference/setup/install/docker.asciidoc b/docs/reference/setup/install/docker.asciidoc index 0abba259d46eb..6baa3655c96b1 100644 --- a/docs/reference/setup/install/docker.asciidoc +++ b/docs/reference/setup/install/docker.asciidoc @@ -33,15 +33,11 @@ Docker image is currently available for this version. endif::[] -ifeval::["{release-state}"!="unreleased"] - [source,sh,subs="attributes"] ---- docker pull {docker-repo}:{version} ---- -endif::[] - [[docker-verify-signature]] ==== Optional: Verify the image signature @@ -57,8 +53,6 @@ Docker image signature is currently available for this version. endif::[] -ifeval::["{release-state}"!="unreleased"] - Install the appropriate https://docs.sigstore.dev/cosign/installation/[Cosign application] for your operating system. @@ -83,8 +77,6 @@ The following checks were performed on each of these signatures: - The signatures were verified against the specified public key -------------------------------------------- -endif::[] - [[docker-cli-run-dev-mode]] ==== Run {es} in Docker @@ -123,7 +115,6 @@ Docker image is currently available for this version. endif::[] -ifeval::["{release-state}"!="unreleased"] [source,sh,subs="attributes"] ---- docker run --name es01 --net elastic -p 9200:9200 -it -m 1GB {docker-image} @@ -132,8 +123,6 @@ docker run --name es01 --net elastic -p 9200:9200 -it -m 1GB {docker-image} TIP: Use the `-m` flag to set a memory limit for the container. The command prints the `elastic` user password and an enrollment token for {kib}. - -endif::[] -- . Copy the generated `elastic` password and enrollment token. These credentials @@ -193,13 +182,10 @@ Docker image is currently available for this version. endif::[] -ifeval::["{release-state}"!="unreleased"] [source,sh,subs="attributes"] ---- docker run -e ENROLLMENT_TOKEN="" --name es02 --net elastic -it {docker-image} ---- - -endif::[] -- . Call the <> to verify the node was added to the cluster. @@ -265,15 +251,13 @@ repository on GitHub. -- ifeval::["{release-state}"=="unreleased"] -NOTE: Version {version} of {es} has not been released, -so the sample Docker Compose and configuration files are not yet available for -this version. See the {stack-gs-current}/get-started-docker.html[current version] -for the latest sample files. +WARNING: Version {version} of {es} has not been released, +so the following Docker Compose and configuration files won't work. +See the {stack-gs-current}/get-started-docker.html[current version] +for the latest working files. endif::[] -- --- -ifeval::["{release-state}"!="unreleased"] [discrete] [[docker-env-file]] @@ -315,8 +299,6 @@ then only be accessible from the host machine itself. include::docker/docker-compose.yml[] ---- -endif::[] --- ===== Start your cluster with security enabled and configured @@ -687,7 +669,6 @@ instead. The command must: * Use the `elasticsearch-keystore` tool with the `create -p` option. You'll be prompted to enter a password for the keystore. -ifeval::["{release-state}"!="unreleased"] For example: [source,sh,subs="attributes"] @@ -711,7 +692,6 @@ bin/elasticsearch-keystore \ add my.secure.setting \ my.other.secure.setting ---- -endif::[] If you've already created the keystore and don't need to update it, you can bind-mount the `elasticsearch.keystore` file directly. You can use the diff --git a/docs/reference/setup/install/rpm.asciidoc b/docs/reference/setup/install/rpm.asciidoc index 4dda986207f6c..8dfbca8c63210 100644 --- a/docs/reference/setup/install/rpm.asciidoc +++ b/docs/reference/setup/install/rpm.asciidoc @@ -34,12 +34,10 @@ rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch ifeval::["{release-state}"=="unreleased"] -Version {version} of Elasticsearch has not yet been released. +WARNING: Version {version} of Elasticsearch has not yet been released. endif::[] -ifeval::["{release-state}"!="unreleased"] - Create a file called `elasticsearch.repo` in the `/etc/yum.repos.d/` directory for RedHat based distributions, or in the `/etc/zypp/repos.d/` directory for OpenSuSE based distributions, containing: @@ -58,8 +56,6 @@ autorefresh=1 type=rpm-md -------------------------------------------------- -endif::[] - ifeval::["{release-state}"=="prerelease"] ["source","sh",subs="attributes,callouts"] @@ -101,12 +97,10 @@ endif::[] ifeval::["{release-state}"=="unreleased"] -Version {version} of Elasticsearch has not yet been released. +WARNING: Version {version} of Elasticsearch has not yet been released. endif::[] -ifeval::["{release-state}"!="unreleased"] - The RPM for Elasticsearch v{version} can be downloaded from the website and installed as follows: ["source","sh",subs="attributes"] @@ -119,8 +113,6 @@ sudo rpm --install elasticsearch-{version}-x86_64.rpm <1> Compares the SHA of the downloaded RPM and the published checksum, which should output `elasticsearch-{version}-x86_64.rpm: OK`. -endif::[] - include::skip-set-kernel-parameters.asciidoc[] // Set a `distro` attribute so we can reuse files containing anchors diff --git a/docs/reference/setup/install/targz.asciidoc b/docs/reference/setup/install/targz.asciidoc index ae5d72a6dd43a..c3dd6ad354d9d 100644 --- a/docs/reference/setup/install/targz.asciidoc +++ b/docs/reference/setup/install/targz.asciidoc @@ -19,12 +19,10 @@ see the <> ifeval::["{release-state}"=="unreleased"] -Version {version} of {es} has not yet been released. +WARNING: Version {version} of {es} has not yet been released. endif::[] -ifeval::["{release-state}"!="unreleased"] - The Linux archive for {es} v{version} can be downloaded and installed as follows: ["source","sh",subs="attributes"] @@ -39,19 +37,15 @@ cd elasticsearch-{version}/ <2> `elasticsearch-{version}-linux-x86_64.tar.gz: OK`. <2> This directory is known as `$ES_HOME`. -endif::[] - [[install-macos]] ==== Download and install archive for MacOS ifeval::["{release-state}"=="unreleased"] -Version {version} of {es} has not yet been released. +WARNING: Version {version} of {es} has not yet been released. endif::[] -ifeval::["{release-state}"!="unreleased"] - The MacOS archive for {es} v{version} can be downloaded and installed as follows: ["source","sh",subs="attributes"] @@ -67,8 +61,6 @@ cd elasticsearch-{version}/ <2> `elasticsearch-{version}-darwin-x86_64.tar.gz: OK`. <2> This directory is known as `$ES_HOME`. -endif::[] - ifdef::include-xpack[] [role="xpack"] [[targz-enable-indices]] diff --git a/docs/reference/setup/install/zip-windows.asciidoc b/docs/reference/setup/install/zip-windows.asciidoc index 95341189c67fa..7c3aab0bb89d8 100644 --- a/docs/reference/setup/install/zip-windows.asciidoc +++ b/docs/reference/setup/install/zip-windows.asciidoc @@ -29,12 +29,10 @@ see the <> ifeval::["{release-state}"=="unreleased"] -Version {version} of {es} has not yet been released. +WARNING: Version {version} of {es} has not yet been released. endif::[] -ifeval::["{release-state}"!="unreleased"] - Download the `.zip` archive for {es} {version} from: https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-windows-x86_64.zip Unzip it with your favorite unzip tool. This will create a folder called @@ -46,8 +44,6 @@ window, `cd` to the `%ES_HOME%` directory, for instance: cd C:\elasticsearch-{version} ---------------------------- -endif::[] - ifdef::include-xpack[] [role="xpack"] [[windows-enable-indices]] diff --git a/docs/reference/setup/run-elasticsearch-locally.asciidoc b/docs/reference/setup/run-elasticsearch-locally.asciidoc index 66152933b0e20..a6e6d5c8963a2 100644 --- a/docs/reference/setup/run-elasticsearch-locally.asciidoc +++ b/docs/reference/setup/run-elasticsearch-locally.asciidoc @@ -34,10 +34,9 @@ Desktop]. Go to **Preferences > Resources > Advanced** and set Memory to at leas . Start an Elasticsearch container: ifeval::["{release-state}"=="unreleased"] + -NOTE: Version {version} of {es} has not yet been released, so no +WARNING: Version {version} of {es} has not yet been released, so no Docker image is currently available for this version. endif::[] -ifeval::["{release-state}"!="unreleased"] + [source,sh,subs="attributes"] ---- @@ -45,7 +44,6 @@ docker network create elastic docker pull docker.elastic.co/elasticsearch/elasticsearch:{version} docker run --name elasticsearch --net elastic -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -t docker.elastic.co/elasticsearch/elasticsearch:{version} ---- -endif::[] + When you start Elasticsearch for the first time, the generated `elastic` user password and Kibana enrollment token are output to the terminal. @@ -65,17 +63,15 @@ Kibana enables you to easily send requests to Elasticsearch and analyze, visuali . In a new terminal session, start Kibana and connect it to your Elasticsearch container: ifeval::["{release-state}"=="unreleased"] + -NOTE: Version {version} of {kib} has not yet been released, so no +WARNING: Version {version} of {kib} has not yet been released, so no Docker image is currently available for this version. endif::[] -ifeval::["{release-state}"!="unreleased"] + [source,sh,subs="attributes"] ---- docker pull docker.elastic.co/kibana/kibana:{version} docker run --name kibana --net elastic -p 5601:5601 docker.elastic.co/kibana/kibana:{version} ---- -endif::[] + When you start Kibana, a unique URL is output to your terminal.