From 3d4246089fac8b7e29c0ec9cee9c142862c576ba Mon Sep 17 00:00:00 2001 From: Cassandra Targett Date: Tue, 17 Dec 2019 12:12:34 -0600 Subject: [PATCH] Ref Guide: make section headings in Headline Case --- .../src/package-manager-internals.adoc | 37 +++++++++---------- solr/solr-ref-guide/src/package-manager.adoc | 27 ++++++-------- .../src/solr-control-script-reference.adoc | 4 +- ...rcloud-autoscaling-policy-preferences.adoc | 10 ++--- 4 files changed, 36 insertions(+), 42 deletions(-) diff --git a/solr/solr-ref-guide/src/package-manager-internals.adoc b/solr/solr-ref-guide/src/package-manager-internals.adoc index 90448a8d365..d47903ddb0d 100644 --- a/solr/solr-ref-guide/src/package-manager-internals.adoc +++ b/solr/solr-ref-guide/src/package-manager-internals.adoc @@ -17,7 +17,7 @@ At the heart of the system, we have classloader isolation. To achieve this, the The root classloader which has all the jars from Solr classpath. This requires Solr node restart to change anything. A set of named classloaders that inherit from the root classloader. The life cycles of the named classloaders are tied to the package configuration in ZK. As soon as the configuration is modified, the corresponding classloaders are reloaded and components are asked to reload. -== Package loading security +== Package Loading Security Packages are disabled by default. Start all your nodes with the system property `-Denable.packages=true` to use this feature. *Example* @@ -27,7 +27,7 @@ Packages are disabled by default. Start all your nodes with the system property $ bin/solr -c -Denable.packages=true ---- -=== Upload your keys +=== Upload Your Keys Package binaries must be signed with your private keys and ensure your public keys are published in Zookeeper *Example* @@ -51,7 +51,7 @@ Package store is a distributed file store which can store arbitrary files in the * Users can’t create files starting with period (.) * It is agnostic of content type of files. You may store jars as well as other files. -=== How does the Package Store work? +=== How Does the Package Store Work? When a file is uploaded to the PackageStore , * It’s saved to the local file system @@ -67,7 +67,7 @@ The end points are * `GET /api/node/files/{full/path/to/file}?meta=true` get the metadata of the file * `GET /api/node/files/{full/path/to/}` get the list of files in `/full/path/to` -=== Signing your artifacts +=== Signing Your Artifacts Use the following steps to upload a jar signed with your public key: @@ -116,13 +116,13 @@ A Package have the following attributes: For every package / version in the packages definition, there is a unique `SolrResourceLoader` instance. This is a child of the `CoreContainer` resource loader. -=== `packages.json` +=== packages.json The package configurations live in a file called /packages.json in Zookeeper. At any given moment we can have multiple versions of a given package in the package configuration. The system will always use the latest version . Versions are sorted by their numeric value and the biggest is the latest. *example:* -[source, json] +[source,json] ---- { "packages" : { @@ -134,44 +134,46 @@ The package configurations live in a file called /packages.json in Zookeeper. At }, {"version" : "0.2", "files" : ["/path/to/myplugin/1.0/plugin.jar"] - }]}}, + }]}}} ---- -== API end points +== API Endpoints * `GET /api/cluster/package` Get the list of packages * `POST /api/cluster/package` edit packages ** `add` command: add a version of a package ** `delete` command : delete a version of a package -=== How to upgrade? +=== How to Upgrade? Use the add command to add a version that is bigger than the current version -=== How to downgrade ? +=== How to Downgrade ? Use the delete command to delete a version that is the highest and the next highest version will be chosen -=== Using multiple versions in parallel in each collection +=== Using Multiple Versions in Parallel We use the `params.json` in the collection config to store a version of a package it uses. by default it is the $LATEST. + [source, json] ---- {"params":{ "PKG_VERSIONS": { "mypkg": "0.1", "pkg2" : "$LATEST", - }} + }}} ---- + * for `mypkg` use the version `0.1` irrespective of whether there is a newer version is available or not * for `pkg2` use the latest. This is optional. The default is ‘$LATEST’ -=== The workflow +=== The Workflow * A new version of a package is added * The package loader loads the classes and notifies every plugin holder of the availability of the new version * It checks if it is supposed to use a specific version, Ignore the update * If not, reload the plugin -=== Using them in Plugins +=== Using Them in Plugins Any class name can be prefixed with the packagename e.g : `mypkg:fully.qualified.ClassName` and Solr would use the latest version of the package to load the classes from. The plugins loaded from packages cannot depend on core level classes. *Plugin declaration in `solrconfig.xml`* @@ -182,7 +184,7 @@ Any class name can be prefixed with the packagename e.g : `mypkg:fully.qualified ---- -=== Full working example +=== Full Working Example 1) create a package @@ -339,7 +341,7 @@ $ curl http://localhost:8983/solr/gettingstarted/test?omitHeader=true ---- Note that the `Version` value is `"2"` . So the plugin is updated -=== How to avoid automatic upgrade (while only using internal APIs)? +=== How to Avoid Automatic Upgrade The default version used in any collection is always the latest. However, setting a per-collection property in the `params.json` ensures that the versions are always fixed irrespective of the new versions added @@ -352,6 +354,3 @@ $ curl http://localhost:8983/solr/gettingstarted/config/params -H 'Content-type: } }}' ---- - - - diff --git a/solr/solr-ref-guide/src/package-manager.adoc b/solr/solr-ref-guide/src/package-manager.adoc index edf88a3e719..ae84c9ed76b 100644 --- a/solr/solr-ref-guide/src/package-manager.adoc +++ b/solr/solr-ref-guide/src/package-manager.adoc @@ -18,7 +18,7 @@ // specific language governing permissions and limitations // under the License. -== Glossary of terms +== Glossary of Terms === Package A set of jar files (usually one) containing one or more <>. Each jar file is also accompanied by a signature string (which can be verified against a supplied public key). @@ -36,7 +36,7 @@ The package manager in Solr consists of the following internal components: In this guide, we will focus on the Package Manager CLI, which essentially uses the other APIs and components internally. For details on the other components (and hence details of inner workings of the package manager), please refer to <>. -== Interacting with the package manager +== Interacting with the Package Manager Essentially, these are the phases in using the package manager: @@ -46,33 +46,30 @@ Essentially, these are the phases in using the package manager: * Deploying packages on to collections * Updating packages -=== Starting Solr with package management support +=== Starting Solr with Package Management Support Start all Solr nodes with the `-Denable.packages=true` parameter. There are security consequences in doing so. At a minimum, no unauthorized user should have write access to Zookeeper instances, since it would then be possible to install packages from untrusted sources (e.g. malicious repositories). [source,bash] ---- - $ bin/solr -c -Denable.packages=true ---- -=== Adding trusted repositories +=== Adding Trusted Repositories In order to install packages into Solr, one has to add a repository hosting the packages. A repository is essentially a web service hosting package artifacts (jar files) and a public key (to validate the signatures of the jar files while installing). Note: Please do not add repositories that you don't trust or control. Also, only add repositories that are based on https and avoid repositories based on http to safeguard against MITM attacks. [source,bash] ---- - $ bin/solr package add-repo ---- -=== Listing and installing packages +=== Listing and Installing Packages To list installed packages: [source,bash] ---- - $ bin/solr package list-installed ---- @@ -81,7 +78,6 @@ To list packages available for installation from added repositories: [source,bash] ---- - $ bin/solr package list-available ---- @@ -89,15 +85,14 @@ To install a package: [source,bash] ---- - $ bin/solr package install [:] ---- -=== Deploying a package on to a collection +=== Deploying a Package to a Collection Once a package has been installed, the plugins contained in it can be used in a collection, using either of the two methods: -==== Deploying using `deploy` command +==== Deploying using deploy Command This can be done using the package manager's `deploy` command, provided the package supports it (package author's documentation would usually mention that): [source,bash] @@ -107,7 +102,7 @@ $ bin/solr package deploy :[version] -collections [,< This may prompt you to execute a command to deploy the package. If you pass `-y` to the command, then this prompt can be skipped. -==== Deploying manually +==== Deploying Manually Alternatively, it is also possible manually edit a configset (solrconfig.xml, managedschema / schema.xml etc.) and using it by RELOADing a collection. Example: Add a request handler from the package `mypackage` to a configset's solrconfig.xml: @@ -125,7 +120,7 @@ curl "http://localhost:8983/api/collections/collection1/config/params" \ -H 'Content-type:application/json' -d "{set: {PKG_VERSIONS: {mypackage: '1.0.0'}}}" ---- -==== Verifying the deployment +==== Verifying the Deployment After deploying, verify that the collection is using the package: [source,bash] @@ -134,7 +129,7 @@ After deploying, verify that the collection is using the package: $ bin/solr package list-deployed -c ---- -=== Updating packages +=== Updating Packages In order to update a package, first step is make sure the updated version is available in the added repositories by running `list-available` command. Next, install the new version of the package from the repositories. @@ -156,4 +151,4 @@ You can run the `list-deployed` command to verify that this collection is using == Security Except the `add-repo` step, all other steps can be executed using a HTTP endpoint in Solr (see <>). This step registers the public key of the trusted repository, and hence can only be executed using the package manager (CLI) having direct write access to Zookeeper. Hence, as you can imagine, it is important to protect Zookeeper from unauthorized write access. -Also, keep in mind, that it is possible to install any package from a trusted and an already added repository. Hence, if you want to use some packages in production, then it is better to setup your own repository and add that to Solr, instead of adding a generic third-party repository that is beyond your administrative control. \ No newline at end of file +Also, keep in mind, that it is possible to install any package from a trusted and an already added repository. Hence, if you want to use some packages in production, then it is better to setup your own repository and add that to Solr, instead of adding a generic third-party repository that is beyond your administrative control. diff --git a/solr/solr-ref-guide/src/solr-control-script-reference.adoc b/solr/solr-ref-guide/src/solr-control-script-reference.adoc index 05f94ac06ea..34a6783f7d8 100644 --- a/solr/solr-ref-guide/src/solr-control-script-reference.adoc +++ b/solr/solr-ref-guide/src/solr-control-script-reference.adoc @@ -881,7 +881,7 @@ Examples of this command: `bin/solr zk mkroot /solr/production` -== Exporting data to a file +== Exporting Data to a File *Example* @@ -897,7 +897,7 @@ Export all documents from a collection `gettingstarted` to a file called `gettin * `fields`: a comma separated list of fields to be exported. * `limit` : number of documents, default is 100, send `-1` to import all the documents. -=== Importing the data to a collection +=== Importing the Data to a Collection *Example: importing the `jsonl` files* diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc index d7760928c71..a998b07769a 100644 --- a/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc +++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc @@ -500,7 +500,7 @@ Number of iterations of the simulation loop. Default is 10. Results of the simulation contain the initial suggestions, suggestions at each step of the simulation and the final simulated state of the cluster. -=== Simulation scenario tool +=== Simulation Scenario Tool The autoscaling command-line tool supports also the execution of end-to-end simulation scenarios consisting of several cluster- and collection-level operations and events. @@ -520,7 +520,7 @@ Keys and values additionally use www-urlencoded format to avoid meta-characters The `params` part of the line closely follows a regular Solr params representation on purpose - in many cases the content of this part of the command is passed directly to the respective collection- or cluster-level API. -==== Scenario context +==== Scenario Context Scenario has a context, which is simply a map of key-value pairs. Before executing each command the context is updated to contain the current values for the following properties: @@ -543,7 +543,7 @@ For example, assuming a system property is set 'foo=bar', the following command load_snapshot path=/tmp/${foo} ---- -==== Scenario commands +==== Scenario Commands The following commands are supported (command names are case insensitive, but params aren't): * `create_cluster numNodes=N[&disableMetricsHistory=false&timeSourcee=simTime:50]` - create a simulated cluster with N nodes @@ -569,7 +569,7 @@ The following commands are supported (command names are case insensitive, but pa * `index_docs numDocs=NNN[&start=XXX]` - simulate bulk indexing of a large number of documents. * `assert condition=(equals | not_equals | null | not_null)&(key=objectPath | value=myValue)[&expected=value]` - assert a condition. When `key` is specified then it can be an object path to complex values present in the scenario's context. -==== Example scenarios +==== Example Scenarios Example scenario testing the behavior of `.autoAddReplicas` trigger: [source,text] ---- @@ -638,4 +638,4 @@ loop_start iterations=${justCalc} calculate_suggestions loop_end dump redact=true ----- \ No newline at end of file +----