Add a docs link to the log message about each failing bootstrap check (…

…#99644) Add a docs link to the log message about each failing bootstrap check to help new users to understand failing bootstrap checks. Closes #99614
elastic · Sep 21, 2023 · c3dece1 · c3dece1
1 parent 50abfd3
commit c3dece1
Show file tree

Hide file tree

Showing 16 changed files with 285 additions and 48 deletions.
diff --git a/docs/changelog/99644.yaml b/docs/changelog/99644.yaml
@@ -0,0 +1,6 @@
+pr: 99644
+summary: Add links to docs from failing bootstrap checks
+area: Infra/Node Lifecycle
+type: enhancement
+issues: [99614]
+
diff --git a/qa/evil-tests/src/test/java/org/elasticsearch/bootstrap/EvilBootstrapChecksTests.java b/qa/evil-tests/src/test/java/org/elasticsearch/bootstrap/EvilBootstrapChecksTests.java
@@ -9,6 +9,7 @@
 package org.elasticsearch.bootstrap;
 
 import org.apache.logging.log4j.Logger;
+import org.elasticsearch.common.ReferenceDocs;
 import org.elasticsearch.core.SuppressForbidden;
 import org.elasticsearch.node.NodeValidationException;
 import org.elasticsearch.test.AbstractBootstrapCheckTestCase;
@@ -49,7 +50,17 @@ public void tearDown() throws Exception {
 
     public void testEnforceBootstrapChecks() throws NodeValidationException {
         setEsEnforceBootstrapChecks("true");
-        final List<BootstrapCheck> checks = Collections.singletonList(context -> BootstrapCheck.BootstrapCheckResult.failure("error"));
+        final List<BootstrapCheck> checks = Collections.singletonList(new BootstrapCheck() {
+            @Override
+            public BootstrapCheckResult check(BootstrapContext context) {
+                return BootstrapCheck.BootstrapCheckResult.failure("error");
+            }
+
+            @Override
+            public ReferenceDocs referenceDocs() {
+                return ReferenceDocs.BOOTSTRAP_CHECKS;
+            }
+        });
 
         final Logger logger = mock(Logger.class);
 

diff --git a/server/src/main/java/org/elasticsearch/bootstrap/BootstrapCheck.java b/server/src/main/java/org/elasticsearch/bootstrap/BootstrapCheck.java
@@ -8,6 +8,8 @@
 
 package org.elasticsearch.bootstrap;
 
+import org.elasticsearch.common.ReferenceDocs;
+
 import java.util.Objects;
 
 /**
@@ -59,4 +61,6 @@ default boolean alwaysEnforce() {
         return false;
     }
 
+    ReferenceDocs referenceDocs();
+
 }
diff --git a/server/src/main/java/org/elasticsearch/bootstrap/BootstrapChecks.java b/server/src/main/java/org/elasticsearch/bootstrap/BootstrapChecks.java
@@ -12,6 +12,7 @@
 import org.apache.logging.log4j.Logger;
 import org.apache.lucene.util.Constants;
 import org.elasticsearch.cluster.coordination.ClusterBootstrapService;
+import org.elasticsearch.common.ReferenceDocs;
 import org.elasticsearch.common.settings.Setting;
 import org.elasticsearch.common.transport.BoundTransportAddress;
 import org.elasticsearch.common.transport.TransportAddress;
@@ -131,10 +132,11 @@ static void check(final BootstrapContext context, final boolean enforceLimits, f
         for (final BootstrapCheck check : checks) {
             final BootstrapCheck.BootstrapCheckResult result = check.check(context);
             if (result.isFailure()) {
+                final String message = result.getMessage() + "; for more information see [" + check.referenceDocs() + "]";
                 if (enforceLimits == false && enforceBootstrapChecks == false && check.alwaysEnforce() == false) {
-                    ignoredErrors.add(result.getMessage());
+                    ignoredErrors.add(message);
                 } else {
-                    errors.add(result.getMessage());
+                    errors.add(message);
                 }
             }
         }
@@ -150,7 +152,9 @@ static void check(final BootstrapContext context, final boolean enforceLimits, f
                     + errors.size()
                     + "] bootstrap checks failed. You must address the points described in the following ["
                     + errors.size()
-                    + "] lines before starting Elasticsearch."
+                    + "] lines before starting Elasticsearch. For more information see ["
+                    + ReferenceDocs.BOOTSTRAP_CHECKS
+                    + "]"
             );
             for (int i = 0; i < errors.size(); i++) {
                 messages.add("bootstrap check failure [" + (i + 1) + "] of [" + errors.size() + "]: " + errors.get(i));
@@ -240,6 +244,11 @@ public BootstrapCheckResult check(BootstrapContext context) {
             }
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_HEAP_SIZE;
+        }
+
         // visible for testing
         long getInitialHeapSize() {
             return JvmInfo.jvmInfo().getConfiguredInitialHeapSize();
@@ -298,6 +307,11 @@ public final BootstrapCheckResult check(BootstrapContext context) {
             }
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_FILE_DESCRIPTOR;
+        }
+
         // visible for testing
         long getMaxFileDescriptorCount() {
             return ProcessProbe.getMaxFileDescriptorCount();
@@ -321,6 +335,11 @@ boolean isMemoryLocked() {
             return Natives.isMemoryLocked();
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_MEMORY_LOCK;
+        }
+
     }
 
     static class MaxNumberOfThreadsCheck implements BootstrapCheck {
@@ -349,6 +368,10 @@ long getMaxNumberOfThreads() {
             return JNANatives.MAX_NUMBER_OF_THREADS;
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_MAX_NUMBER_THREADS;
+        }
     }
 
     static class MaxSizeVirtualMemoryCheck implements BootstrapCheck {
@@ -378,6 +401,10 @@ long getMaxSizeVirtualMemory() {
             return JNANatives.MAX_SIZE_VIRTUAL_MEMORY;
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_MAX_SIZE_VIRTUAL_MEMORY;
+        }
     }
 
     /**
@@ -409,6 +436,10 @@ long getMaxFileSize() {
             return JNANatives.MAX_FILE_SIZE;
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_MAX_FILE_SIZE;
+        }
     }
 
     static class MaxMapCountCheck implements BootstrapCheck {
@@ -478,6 +509,10 @@ static long parseProcSysVmMaxMapCount(final String procSysVmMaxMapCount) throws
             return Long.parseLong(procSysVmMaxMapCount);
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_MAXIMUM_MAP_COUNT;
+        }
     }
 
     static class ClientJvmCheck implements BootstrapCheck {
@@ -501,6 +536,10 @@ String getVmName() {
             return JvmInfo.jvmInfo().getVmName();
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_CLIENT_JVM;
+        }
     }
 
     /**
@@ -529,6 +568,10 @@ String getUseSerialGC() {
             return JvmInfo.jvmInfo().useSerialGC();
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_USE_SERIAL_COLLECTOR;
+        }
     }
 
     /**
@@ -551,6 +594,10 @@ boolean isSystemCallFilterInstalled() {
             return Natives.isSystemCallFilterInstalled();
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_SYSTEM_CALL_FILTER;
+        }
     }
 
     abstract static class MightForkCheck implements BootstrapCheck {
@@ -579,6 +626,11 @@ public final boolean alwaysEnforce() {
             return true;
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_ONERROR_AND_ONOUTOFMEMORYERROR;
+        }
+
     }
 
     static class OnErrorCheck extends MightForkCheck {
@@ -658,6 +710,11 @@ String javaVersion() {
             return Constants.JAVA_VERSION;
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_EARLY_ACCESS;
+        }
+
     }
 
     static class AllPermissionCheck implements BootstrapCheck {
@@ -681,6 +738,10 @@ boolean isAllPermissionGranted() {
             return true;
         }
 
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_ALL_PERMISSION;
+        }
     }
 
     static class DiscoveryConfiguredCheck implements BootstrapCheck {
@@ -703,6 +764,11 @@ public BootstrapCheckResult check(BootstrapContext context) {
                 )
             );
         }
+
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECK_DISCOVERY_CONFIGURATION;
+        }
     }
 
     static class ByteOrderCheck implements BootstrapCheck {
@@ -718,5 +784,10 @@ public BootstrapCheckResult check(BootstrapContext context) {
         ByteOrder nativeByteOrder() {
             return ByteOrder.nativeOrder();
         }
+
+        @Override
+        public ReferenceDocs referenceDocs() {
+            return ReferenceDocs.BOOTSTRAP_CHECKS;
+        }
     }
 }
diff --git a/server/src/main/java/org/elasticsearch/common/ReferenceDocs.java b/server/src/main/java/org/elasticsearch/common/ReferenceDocs.java
@@ -46,6 +46,28 @@ public enum ReferenceDocs {
     CONCURRENT_REPOSITORY_WRITERS,
     ARCHIVE_INDICES,
     HTTP_TRACER,
+    BOOTSTRAP_CHECK_HEAP_SIZE,
+    BOOTSTRAP_CHECK_FILE_DESCRIPTOR,
+    BOOTSTRAP_CHECK_MEMORY_LOCK,
+    BOOTSTRAP_CHECK_MAX_NUMBER_THREADS,
+    BOOTSTRAP_CHECK_MAX_FILE_SIZE,
+    BOOTSTRAP_CHECK_MAX_SIZE_VIRTUAL_MEMORY,
+    BOOTSTRAP_CHECK_MAXIMUM_MAP_COUNT,
+    BOOTSTRAP_CHECK_CLIENT_JVM,
+    BOOTSTRAP_CHECK_USE_SERIAL_COLLECTOR,
+    BOOTSTRAP_CHECK_SYSTEM_CALL_FILTER,
+    BOOTSTRAP_CHECK_ONERROR_AND_ONOUTOFMEMORYERROR,
+    BOOTSTRAP_CHECK_EARLY_ACCESS,
+    BOOTSTRAP_CHECK_G1GC,
+    BOOTSTRAP_CHECK_ALL_PERMISSION,
+    BOOTSTRAP_CHECK_DISCOVERY_CONFIGURATION,
+    BOOTSTRAP_CHECKS,
+    BOOTSTRAP_CHECK_ENCRYPT_SENSITIVE_DATA,
+    BOOTSTRAP_CHECK_PKI_REALM,
+    BOOTSTRAP_CHECK_ROLE_MAPPINGS,
+    BOOTSTRAP_CHECK_TLS,
+    BOOTSTRAP_CHECK_TOKEN_SSL,
+    BOOTSTRAP_CHECK_SECURITY_MINIMAL_SETUP,
     // this comment keeps the ';' on the next line so every entry above has a trailing ',' which makes the diff for adding new links cleaner
     ;
 

diff --git a/server/src/main/resources/org/elasticsearch/common/reference-docs-links.json b/server/src/main/resources/org/elasticsearch/common/reference-docs-links.json
@@ -6,5 +6,27 @@
   "SHARD_LOCK_TROUBLESHOOTING": "troubleshooting-unstable-cluster.html#_diagnosing_shardlockobtainfailedexception_failures_2",
   "CONCURRENT_REPOSITORY_WRITERS": "add-repository.html",
   "ARCHIVE_INDICES": "archive-indices.html",
-  "HTTP_TRACER": "modules-network.html#http-rest-request-tracer"
+  "HTTP_TRACER": "modules-network.html#http-rest-request-tracer",
+  "BOOTSTRAP_CHECK_HEAP_SIZE": "_heap_size_check.html",
+  "BOOTSTRAP_CHECK_FILE_DESCRIPTOR": "_file_descriptor_check.html",
+  "BOOTSTRAP_CHECK_MEMORY_LOCK": "_memory_lock_check.html",
+  "BOOTSTRAP_CHECK_MAX_NUMBER_THREADS": "max-number-threads-check.html",
+  "BOOTSTRAP_CHECK_MAX_FILE_SIZE": "_max_file_size_check.html",
+  "BOOTSTRAP_CHECK_MAX_SIZE_VIRTUAL_MEMORY": "max-size-virtual-memory-check.html",
+  "BOOTSTRAP_CHECK_MAXIMUM_MAP_COUNT": "_maximum_map_count_check.html",
+  "BOOTSTRAP_CHECK_CLIENT_JVM": "_client_jvm_check.html",
+  "BOOTSTRAP_CHECK_USE_SERIAL_COLLECTOR": "_use_serial_collector_check.html",
+  "BOOTSTRAP_CHECK_SYSTEM_CALL_FILTER": "_system_call_filter_check.html",
+  "BOOTSTRAP_CHECK_ONERROR_AND_ONOUTOFMEMORYERROR": "_onerror_and_onoutofmemoryerror_checks.html",
+  "BOOTSTRAP_CHECK_EARLY_ACCESS": "_early_access_check.html",
+  "BOOTSTRAP_CHECK_G1GC": "_g1gc_check.html",
+  "BOOTSTRAP_CHECK_ALL_PERMISSION": "_all_permission_check.html",
+  "BOOTSTRAP_CHECK_DISCOVERY_CONFIGURATION": "_discovery_configuration_check.html",
+  "BOOTSTRAP_CHECKS": "bootstrap-checks.html",
+  "BOOTSTRAP_CHECK_ENCRYPT_SENSITIVE_DATA": "bootstrap-checks-xpack.html#_encrypt_sensitive_data_check",
+  "BOOTSTRAP_CHECK_PKI_REALM": "bootstrap-checks-xpack.html#_pki_realm_check",
+  "BOOTSTRAP_CHECK_ROLE_MAPPINGS": "bootstrap-checks-xpack.html#_role_mappings_check",
+  "BOOTSTRAP_CHECK_TLS": "bootstrap-checks-xpack.html#bootstrap-checks-tls",
+  "BOOTSTRAP_CHECK_TOKEN_SSL": "bootstrap-checks-xpack.html#_token_ssl_check",
+  "BOOTSTRAP_CHECK_SECURITY_MINIMAL_SETUP": "security-minimal-setup.html"
 }