Add Snapshot Lifecycle Management Package Docs (#43535)

Author: jbaiera

x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/snapshotlifecycle/action/package-info.java

@@ -0,0 +1,11 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+/**
+ * Contains the action definitions for SLM. For the transport and rest action implementations, please see the <tt>ilm</tt> module's
+ * <tt>org.elasticsearch.xpack.snapshotlifecycle</tt> package.
+ */
+package org.elasticsearch.xpack.core.snapshotlifecycle.action;

x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/snapshotlifecycle/history/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+/**
+ * This package contains the utility classes used to persist SLM policy execution results to an internal index.
+ *
+ * <p>The {@link org.elasticsearch.xpack.core.snapshotlifecycle.history.SnapshotLifecycleTemplateRegistry} class is registered as a
+ * cluster state listener when the ILM plugin starts up. It executes only on the elected master node, and ensures that a template is
+ * configured for the SLM history index, as well as an ILM policy (since the two are always enabled in lock step).
+ *
+ * <p>The {@link org.elasticsearch.xpack.core.snapshotlifecycle.history.SnapshotHistoryItem} is used to encapsulate historical
+ * information about a snapshot policy execution. This contains more data than the
+ * {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotInvocationRecord} since it is a more complete history record
+ * stored on disk instead of a low surface area status entry.
+ *
+ * <p>The {@link org.elasticsearch.xpack.core.snapshotlifecycle.history.SnapshotHistoryStore} manages the persistence of the previously
+ * mentioned {@link org.elasticsearch.xpack.core.snapshotlifecycle.history.SnapshotHistoryItem}. It simply does an asynchronous put
+ * operation against the SLM history internal index.
+ */
+package org.elasticsearch.xpack.core.snapshotlifecycle.history;

x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/snapshotlifecycle/package-info.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+/**
+ * This is the Snapshot Lifecycle Management (SLM) core package. This package contains the core classes for SLM, including all of the
+ * custom cluster state metadata objects, execution history storage facilities, and the action definitions. For the main SLM service
+ * implementation classes, please see the <tt>ilm</tt> module's <tt>org.elasticsearch.xpack.snapshotlifecycle</tt> package.
+ *
+ * <p>Contained within this specific package are the custom metadata objects and models used through out the SLM service. The names can
+ * be confusing, so it's important to know the differences between each metadata object.
+ *
+ * <p>The {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotLifecyclePolicy} object is the user provided definition of the
+ * SLM policy. This is what a user provides when creating a snapshot policy, and acts as the blueprint for the create snapshot request
+ * that the service launches. It additionally surfaces the next point in time a policy should be executed.
+ *
+ * <p>Lateral to the policy, the {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotInvocationRecord} represents an execution
+ * of a policy. It includes within it the policy name and details about its execution, success or failure.
+ *
+ * <p>Next is the {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotLifecyclePolicyMetadata} object, which not only contains
+ * the {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotLifecyclePolicy} blueprint, but also any contextual information about
+ * that policy, like the user information of who created it so that it may be used during execution, as well as the version of the policy,
+ * and both the last failed and successful runs as {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotInvocationRecord}s. This
+ * is the living representation of a policy within the cluster state.
+ *
+ * <p>When a "Get Policy" action is executed, the {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotLifecyclePolicyItem} is
+ * returned instead. This is a thin wrapper around the internal
+ * {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotLifecyclePolicyMetadata} object so that we do not expose any sensitive
+ * internal headers or user information in the Get API.
+ *
+ * <p>Finally, the {@link org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotLifecycleMetadata} class contains all living SLM
+ * policies and their metadata, acting as the SLM specific root object within the cluster state.
+ */
+package org.elasticsearch.xpack.core.snapshotlifecycle;

x-pack/plugin/ilm/src/main/java/org/elasticsearch/xpack/snapshotlifecycle/action/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+/**
+ * This package contains all the SLM Rest and Transport actions.
+ *
+ * <p>The {@link org.elasticsearch.xpack.snapshotlifecycle.action.TransportPutSnapshotLifecycleAction} creates or updates a snapshot
+ * lifecycle policy in the cluster state. The {@link org.elasticsearch.xpack.snapshotlifecycle.action.TransportGetSnapshotLifecycleAction}
+ * simply retrieves a policy by id. The {@link org.elasticsearch.xpack.snapshotlifecycle.action.TransportDeleteSnapshotLifecycleAction}
+ * removes a policy from the cluster state. These actions only interact with the cluster state. Most of the logic that take place in
+ * response to these actions happens on the master node in the {@link org.elasticsearch.xpack.snapshotlifecycle.SnapshotLifecycleService}.
+ *
+ * <p>The {@link org.elasticsearch.xpack.snapshotlifecycle.action.TransportExecuteSnapshotLifecycleAction} operates as if the snapshot
+ * policy given was immediately triggered by the scheduler. It does not interfere with any currently scheduled operations, it just runs
+ * the snapshot operation ad hoc.
+ */
+package org.elasticsearch.xpack.snapshotlifecycle.action;

x-pack/plugin/ilm/src/main/java/org/elasticsearch/xpack/snapshotlifecycle/package-info.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+/**
+ * This is the Snapshot Lifecycle Management (SLM) main package. SLM is part of the wider ILM feature, reusing quite a bit of the
+ * functionality for itself in some places, which is why the two features are contained in the same plugin.
+ *
+ * This package contains the {@link org.elasticsearch.xpack.snapshotlifecycle.SnapshotLifecycleService} and
+ * {@link org.elasticsearch.xpack.snapshotlifecycle.SnapshotLifecycleTask}, as well as the Rest and Transport actions for the
+ * feature set.
+ * This package contains the primary execution logic and most of the user facing
+ * surface area for the plugin, but not everything. The model objects for the cluster state as well as several supporting classes are
+ * contained in the {@link org.elasticsearch.xpack.core.snapshotlifecycle} package.
+ *
+ * <p>{@link org.elasticsearch.xpack.snapshotlifecycle.SnapshotLifecycleService} maintains an internal
+ * {@link org.elasticsearch.xpack.core.scheduler.SchedulerEngine SchedulerEngine} that handles scheduling snapshots. The service
+ * executes on the currently elected master node. It listens to the cluster state, detecting new policies to schedule, and unscheduling
+ * policies when they are deleted or if ILM is stopped. The bulk of this scheduling management is handled within
+ * {@link org.elasticsearch.xpack.snapshotlifecycle.SnapshotLifecycleService#maybeScheduleSnapshot(SnapshotLifecyclePolicyMetadata)}
+ * which is executed on all snapshot policies each update.
+ *
+ * <p>The {@link org.elasticsearch.xpack.snapshotlifecycle.SnapshotLifecycleTask} object is what receives an event when a scheduled policy
+ * is triggered for execution. It constructs a snapshot request and runs it as the user who originally set up the policy. The bulk of this
+ * logic is contained in the
+ * {@link org.elasticsearch.xpack.snapshotlifecycle.SnapshotLifecycleTask#maybeTakeSnapshot(String, Client, ClusterService,
+ * SnapshotHistoryStore)} method. After a snapshot request has been submitted, it persists the result (success or failure) in a history
+ * store (an index), caching the latest success and failure information in the cluster state. It is important to note that this task
+ * fires the snapshot request off and forgets it; It does not wait until the entire snapshot completes. Any success or failure that this
+ * task sees will be from the initial submission of the snapshot request only.
+ */
+package org.elasticsearch.xpack.snapshotlifecycle;
+
+import org.elasticsearch.client.Client;
+import org.elasticsearch.cluster.service.ClusterService;
+import org.elasticsearch.xpack.core.snapshotlifecycle.SnapshotLifecyclePolicyMetadata;
+import org.elasticsearch.xpack.core.snapshotlifecycle.history.SnapshotHistoryStore;