mirror of
https://github.com/google/nomulus.git
synced 2025-05-15 00:47:11 +02:00
3b4b7a475b
VoidKeyring always threw exceptions whenever any of its methods were called, which caused several parts of the system to fail early (and thus required a proper Keyring to be implemented almost immediately, early on in the "just playing around with the system" phase). I'm swapping this out with an InMemoryKeyring which is supplied by DummyKeyringModule, which, instead of throwing exceptions, returns dummy values, delaying the onset of errors to when connecting to external services is attempted. This pushes off the required implementation of a real Keyring- providing module, allowing the system to be played around with more first. ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=132361157
122 lines
6.8 KiB
Markdown
122 lines
6.8 KiB
Markdown
# Configuration
|
|
|
|
There are multiple different kinds of configuration that go into getting a
|
|
working registry system up and running. Broadly speaking, configuration works
|
|
in two ways -- globally, for the entire sytem, and per-TLD. Global
|
|
configuration is managed by editing code and deploying a new version, whereas
|
|
per-TLD configuration is data that lives in Datastore in `Registry` entities,
|
|
and is updated by running `registry_tool` commands without having to deploy a
|
|
new version.
|
|
|
|
## Environments
|
|
|
|
Before getting into the details of configuration, it's important to note that a
|
|
lot of configuration is environment-dependent. It is common to see `switch`
|
|
statements that operate on the current `RegistryEnvironment`, and return
|
|
different values for different environments. This is especially pronounced in
|
|
the `UNITTEST` and `LOCAL` environments, which don't run on App Engine at all.
|
|
As an example, some timeouts may be long in production and short in unit tests.
|
|
|
|
See the "App Engine architecture" documentation for more details on environments
|
|
as used in the domain registry.
|
|
|
|
## App Engine configuration
|
|
|
|
App Engine configuration isn't covered in depth in this document as it is
|
|
thoroughly documented in the [App Engine configuration docs][app-engine-config].
|
|
The main files of note that come pre-configured along with the domain registry
|
|
are:
|
|
|
|
* `cron.xml` -- Configuration of cronjobs
|
|
* `web.xml` -- Configuration of URL paths on the webserver
|
|
* `appengine-web.xml` -- Overall App Engine settings including number and type
|
|
of instances
|
|
* `datastore-indexes.xml` -- Configuration of entity indexes in Datastore
|
|
* `queue.xml` -- Configuration of App Engine task queues
|
|
* `application.xml` -- Configuration of the application name and its services
|
|
|
|
Cron, web, and queue are covered in more detail in the "App Engine architecture"
|
|
doc, and the rest are covered in the general App Engine documentation.
|
|
|
|
If you are not writing new code to implement custom features, is unlikely that
|
|
you will need to make any modifications beyond simple changes to
|
|
`application.xml` and `appengine-web.xml`. If you are writing new features,
|
|
it's likely you'll need to add cronjobs, URL paths, Datastore indexes, and task
|
|
queues, and thus edit those associated XML files.
|
|
|
|
## Global configuration
|
|
|
|
There are two different mechanisms by which global configuration is managed:
|
|
`RegistryConfig` (the old way) and `ConfigModule` (the new way). Ideally there
|
|
would just be one, but the required code cleanup that hasn't been completed yet.
|
|
If you are adding new options, prefer adding them to `ConfigModule`.
|
|
|
|
**`RegistryConfig`** is an interface, of which you write an implementing class
|
|
containing the configuration values. `RegistryConfigLoader` is the class that
|
|
provides the instance of `RegistryConfig`, and defaults to returning
|
|
`ProductionRegistryConfigExample`. In order to create a configuration specific
|
|
to your registry, we recommend copying the `ProductionRegistryConfigExample`
|
|
class to a new class that will not be shared publicly, setting the
|
|
`com.google.domain.registry.config` system property in `appengine-web.xml` to
|
|
the fully qualified class name of that new class so that `RegistryConfigLoader`
|
|
will load it instead, and then editing said new class to add your specific
|
|
configuration options.
|
|
|
|
The `RegistryConfig` class has documentation on all of the methods that should
|
|
be sufficient to explain what each option is, and
|
|
`ProductionRegistryConfigExample` provides an example value for each one. Some
|
|
example configuration options in this interface include the App Engine project
|
|
ID, the number of days to retain commit logs, the names of various Cloud Storage
|
|
bucket names, and URLs for some required services both external and internal.
|
|
|
|
**`ConfigModule`** is a Dagger module that provides injectable configuration
|
|
options (some of which come from `RegistryConfig` above, but most of which do
|
|
not). This is preferred over `RegistryConfig` for new configuration options
|
|
because being able to inject configuration options is a nicer pattern that makes
|
|
for cleaner code. Some configuration options that can be changed in this class
|
|
include timeout lengths and buffer sizes for various tasks, email addresses and
|
|
URLs to use for various services, more Cloud Storage bucket names, and WHOIS
|
|
disclaimer text.
|
|
|
|
## Sensitive global configuration
|
|
|
|
Some configuration values, such as PGP private keys, are so sensitive that they
|
|
should not be written in code as per the configuration methods above, as that
|
|
would pose too high a risk of them accidentally being leaked, e.g. in a source
|
|
control mishap. We use a secret store to persist these values in a secure
|
|
manner, and abstract access to them using the `Keyring` interface.
|
|
|
|
The `Keyring` interface contains methods for all sensitive configuration values,
|
|
which are primarily credentials used to access various ICANN and ICANN-
|
|
affiliated services (such as RDE). These values are only needed for real
|
|
production registries and PDT environments. If you are just playing around with
|
|
the platform at first, it is OK to put off defining these values until
|
|
necessary. To that end, a `DummyKeyringModule` is included that simply provides
|
|
an `InMemoryKeyring` populated with dummy values for all secret keys. This
|
|
allows the codebase to compile and run, but of course any actions that attempt
|
|
to connect to external services will fail because none of the keys are real.
|
|
|
|
To configure a production registry system, you will need to write a replacement
|
|
module for `DummyKeyringModule` that loads the credentials in a secure way, and
|
|
provides them using either an instance of `InMemoryKeyring` or your own custom
|
|
implementation of `Keyring`. You then need to replace all usages of
|
|
`DummyKeyringModule` with your own module in all of the per-service components
|
|
in which it is referenced. The functions in `PgpHelper` will likely prove
|
|
useful for loading keys stored in PGP format into the PGP key classes that
|
|
you'll need to provide from `Keyring`, and you can see examples of them in
|
|
action in `DummyKeyringModule`.
|
|
|
|
## Per-TLD configuration
|
|
|
|
`Registry` entities, which are persisted to Datastore, are used for per-TLD
|
|
configuration. They contain any kind of configuration that is specific to a
|
|
TLD, such as the create/renew price of a domain name, the pricing engine
|
|
implementation, the DNS writer implementation, whether escrow exports are
|
|
enabled, the default currency, the reserved label lists, and more. The
|
|
`update_tld` command in `registry_tool` is used to set all of these options.
|
|
See the "Registry tool" documentation for more information, as well as the
|
|
command-line help for the `update_tld` command. Unlike global configuration
|
|
above, per-TLD configuration options are stored as data in the running system,
|
|
and thus do not require code pushes to update.
|
|
|
|
[app-engine-config]: https://cloud.google.com/appengine/docs/java/configuration-files
|