zydronium/google-nomulus
1
0
Fork 0
mirror of https://github.com/google/nomulus.git synced 2025-08-05 09:21:49 +02:00
Code Issues Projects Releases Packages Wiki Activity

Add registry_tool documentation

Browse source 
-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=129215218
This commit is contained in:
mcilwain 2016-08-03 08:08:53 -07:00 • committed by Ben McIlwain
parent ea24f6ca31
commit 4cf5a7d67b
2 changed files with 94 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/app-engine-architecture.md
View file

@ -184,31 +184,32 @@ then the sandbox app would be named 'registry-platform-sandbox'.
The full list of environments supported out-of-the-box, in descending order from
real to not, is:
* PRODUCTION -- The real production environment that is actually running live
* `PRODUCTION` -- The real production environment that is actually running live
TLDs. Since the Domain Registry is a shared registry platform, there need
only ever be one of these.
* SANDBOX -- A playground environment for external users to test commands in
* `SANDBOX` -- A playground environment for external users to test commands in
without the possibility of affecting production data. This is the environment
new registrars go through
[OT&E](https://www.icann.org/resources/unthemed-pages/registry-agmt-appc-e-2001-04-26-en)
in. Sandbox is also useful as a final sanity check to push a new prospective
build to and allow it to "bake" before pushing it to production.
* QA -- An internal environment used by business users to play with and sign off
on new features to be released. This environment can be pushed to frequently
and is where manual testers should be spending the majority of their time.
* CRASH -- Another environment similar to QA, except with no expectations of
* `QA` -- An internal environment used by business users to play with and sign
off on new features to be released. This environment can be pushed to
frequently and is where manual testers should be spending the majority of
their time.
* `CRASH` -- Another environment similar to QA, except with no expectations of
data preservation. Crash is used for testing of backup/restore (which brings
the entire system down until it is completed) without affecting the QA
environment.
* ALPHA -- The developers' playground. Experimental builds are routinely pushed
here in order to test them on a real app running on App Engine. You may end
up wanting multiple environments like Alpha if you regularly experience
contention (i.e. developers being blocked from testing their code on Alpha
because others are already using it).
* LOCAL -- A fake environment that is used when running the app locally on a
* `ALPHA` -- The developers' playground. Experimental builds are routinely
pushed here in order to test them on a real app running on App Engine. You
may end up wanting multiple environments like Alpha if you regularly
experience contention (i.e. developers being blocked from testing their code
on Alpha because others are already using it).
* `LOCAL` -- A fake environment that is used when running the app locally on a
simulated App Engine instance.
* UNITTEST -- A fake environment that is used in unit tests, where everything in
the App Engine stack is simulated or mocked.
* `UNITTEST` -- A fake environment that is used in unit tests, where everything
in the App Engine stack is simulated or mocked.
## Release process

80
docs/registry-tool.md
View file

@ -1,3 +1,81 @@
# Registry tool
Information on registry_tool commands.
The registry tool is a command-line registry administration tool that is invoked
using the `registry_tool` command. It has the ability to view and change a
large number of things in a running domain registry environment, including
creating registrars, updating premium and reserved lists, running an EPP command
from a given XML file, and performing various backend tasks like re-running RDE
if the most recent export failed. Its code lives inside the tools package
(`java/google/registry/tools`), and is compiled by building the `registry_tool`
target in the Bazel BUILD file in that package.
The registry tool is always called with a specific environment to run in using
the -e parameter. This looks like:
$ registry_tool -e production {command name} {command parameters}
To see a list of all available commands along with usage information, run
registry_tool without specifying a command name, e.g.:
$ registry_tool -e alpha
Note that the documentation for the commands comes from JCommander, which parses
metadata contained within the code to yield documentation.
## Tech support commands
There are actually two separate tools, `gtech_tool`, which is a collection of
lower impact commands intended to be used by tech support personnel, and
`registry_tool`, which is a superset of `gtech_tool` that contains additional
commands that are potentially more destructive and can change more aspects of
the system. A full list of `gtech_tool` commands can be found in
`GtechTool.java`, and the additional commands that only `registry_tool` has
access to are in `RegistryTool.java`.
## Local and server-side commands
There are two broad ways that commands are implemented: some that send requests
to `ToolsServlet` to execute the action on the server (these commands implement
`ServerSideCommand`), and others that execute the command locally using the
[Remote API](https://cloud.google.com/appengine/docs/java/tools/remoteapi)
(these commands implement `RemoteApiCommand`). Server-side commands take more
work to implement because they require both a client and a server-side
component, e.g. `CreatePremiumListCommand.java` and
`CreatePremiumListAction.java` respectively for creating a premium list.
However, they are fully capable of doing anything that is possible with App
Engine, including running a large MapReduce, because they execute on the tools
service in the App Engine cloud.
Local commands, by contrast, are easier to implement, because there is only a
local component to write, but they aren't as powerful. A general rule of thumb
for making this determination is to use a local command if possible, or a
server-side command otherwise.
## Common tool patterns
All tools ultimately implement the `Command` interface located in the `tools`
package. If you use an IDE such as Eclipse to view the type hierarchy of that
interface, you'll see all of the commands that exist, as well as how a lot of
them are grouped using sub-interfaces or abstract classes that provide
additional functionality. The most common patterns that are used by a large
number of other tools are:
* **`BigqueryCommand`** -- Provides a connection to BigQuery for tools that need
it.
* **`ConfirmingCommand`** -- Provides the methods `prompt()` and `execute()` to
override. `prompt()` outputs a message (usually what the command is going to
do) and prompts the user to confirm execution of the command, and then
`execute()` actually does it.
* **`EppToolCommand`** -- Commands that work by executing EPP commands against
the server, usually by filling in a template with parameters that were passed
on the command-line.
* **`MutatingEppToolCommand`** -- A sub-class of `EppToolCommand` that provides
a `--dry_run` flag, that, if passed, will display the output from the server
of what the command would've done without actually committing those changes.
* **`GetEppResourceCommand`** -- Gets individual EPP resources from the server
and outputs them.
* **`ListObjectsCommand`** -- Lists all objects of a specific type from the
server and outputs them.
* **`MutatingCommand`** -- Provides a facility to create or update entities in
Datastore, and uses a diff algorithm to display the changes that will be made
before committing them.