zydronium/google-nomulus
1
0
Fork 0
mirror of https://github.com/google/nomulus.git synced 2025-04-30 12:07:51 +02:00
Code Issues Projects Releases Packages Wiki Activity

Update premium and reserved list management docs (#380)

Browse source 
* Update premium and reserved list management docs

They were a little bit out of date.
This commit is contained in:
Ben McIlwain 2019-11-21 16:44:45 -05:00 • committed by GitHub
parent 9359f40665
commit c34b68331f
2 changed files with 69 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
docs/operational-procedures/premium-list-management.md
View file

@ -31,8 +31,8 @@ reconstruct a premium list .txt file from the premium list that is loaded into
Datastore (though in principle it would be easy to do by writing a tool to do
so), so don't lose those .txt files.
An example premium list can be found at
`java/google/registry/model/registry/config/files/premium/example.txt`.
The nomulus repository contains an
[example premium list file](https://github.com/google/nomulus/blob/master/core/src/main/java/google/registry/config/files/premium/example.txt).
## Creating a premium list
@ -52,6 +52,9 @@ that the convention of naming premium lists after the TLD they are intended to
be used for is enforced unless the override parameter `-o` is passed, which
allows premium lists to be created with any name.
You're not done yet! After creating the premium list you must the apply it to
one or more TLDs (see below) for it to actually be used.
## Updating a premium list
If the premium list already exists and you want to update it with new prices
@ -66,6 +69,10 @@ Perform this command? (y/N): y
Successfully saved premium list exampletld
```
If this premium list is already applied to a TLD, then changes will take up to
60 minutes to take effect (depending on how you've configured the relevant
caching interval; 60 minutes is the default).
## Applying a premium list to a TLD
Separate from the management of the contents of individual premium lists, a
@ -92,9 +99,9 @@ all other information about a TLD). It is used as follows:
```shell
$ nomulus -e {ENVIRONMENT} get_tld exampletld
[ ... snip ... ]
[ ... snip output ... ]
premiumList=Key<?>(EntityGroupRoot("cross-tld")/PremiumList("exampletld"))
[ ... snip ... ]
[ ... snip output ... ]
```
## Listing all available premium lists
@ -107,3 +114,22 @@ $ nomulus -e {ENVIRONMENT} list_premium_lists
exampletld
someotherlist
```
## Verifying premium list updates
To verify that the changes have actually been applied, you can run a domain
check on a modified entry using the `nomulus check_domain` command and verify
that the domain now has the correct price.
```shell
$ nomulus -e production check_domain {domain_name}
[ ... snip output ... ]
```
**Note that the list can be cached for up to 60 minutes, so the old value may
still be returned for a little while**. If it is urgent that the new pricing
changes be applied, and it's OK to potentially interrupt client connections,
then you can use the App Engine web console to kill instances of the `default`
service, as the cache is per-instance. Once you've killed all the existing
instances (don't kill them all at once!), all of the newly spun up instances
will now be using the new values you've configured.

52
docs/operational-procedures/reserved-list-management.md
View file

@ -65,14 +65,19 @@ acmecorp,RESERVED_FOR_ANCHOR_TENANT
internaldomain,NAMESERVER_RESTRICTED,ns1.internal.tld:ns1.internal.tld
```
# Reserved list file name format
There are two types of reserved lists: Those that are intended to apply to a
specifc TLD, and are thus prefixed with the name of the TLD followed by an
specific TLD, and are thus prefixed with the name of the TLD followed by an
underscore, and those that can be applied to any TLD, and are prefixed with
`common_`. For example, a list of reserved labels on the TLD `exampletld` might
be named `exampletld_blocked-names.txt`, whereas a similar list intended to
apply to multiple TLDs might be named `common_blocked-names.txt`. Note that
these naming conventions are enforced by the tooling used to create and apply
reserved lists (see subsequent sections).
reserved lists (see subsequent sections). The two naming patterns are thus:
* `common_list-name.txt`
* `tldname_list-name.txt`
## Creating a reserved list
@ -82,17 +87,20 @@ purposes of this example, we are creating a common reserved list named
"common_bad-words".
```shell
$ nomulus -e {ENVIRONMENT} create_reserved_list -n common_bad-words \
-i common_bad-words.txt
$ nomulus -e {ENVIRONMENT} create_reserved_list -i common_bad-words.txt
[ ... snip long confirmation prompt ... ]
Perform this command? (y/N): y
Updated 1 entities.
```
`-n` is the name of the reserved list to create, and `-i` is the input file
containing the list. Note that if `-n` is omitted, the list name is inferred
from the input of the filename minus its file extension. It is recommended to
store all lists such that the filename and list name are identical.
Note that `-i` is the input file containing the list. You can optionally specify
the name of the reserved list using `-n`, but when it's omitted as above the
list name is inferred from the name of the filename (minus the file extension).
For ease of tracking track of things, it is recommended to store all lists such
that the filename and list name are identical.
You're not done yet! After creating the reserved list you must the apply it to
one or more TLDs (see below) for it to actually be used.
## Updating a reserved list
@ -101,15 +109,14 @@ file containing the reserved list entries, then pass it as input to the
`update_reserved_list` command as follows:
```shell
$ nomulus -e {ENVIRONMENT} update_reserved_list -n common_bad-words \
-i common_bad-words.txt
$ nomulus -e {ENVIRONMENT} update_reserved_list -i common_bad-words.txt
[ ... snip diff of changes to list entries ... ]
Perform this command? (y/N): y
Updated 1 entities.
```
Note that, like the create command, the name of the list is inferred from the
filename if the `-n` parameter is omitted.
filename unless you specify the `-n` parameter (not generally recommended).
## Applying a reserved list to a TLD
@ -149,9 +156,9 @@ purposes here. It is used as follows:
```shell
$ nomulus -e {ENVIRONMENT} get_tld exampletld
[ ... snip ... ]
[ ... snip output ... ]
reservedLists=[Key<?>(EntityGroupRoot("cross-tld")/ReservedList("common_bad-words"))]
[ ... snip ... ]
[ ... snip output ... ]
```
## Listing all available reserved lists
@ -165,3 +172,22 @@ $ nomulus -e {ENVIRONMENT} list_reserved_lists
common_bad-words
exampletld_some-other-list
```
## Verifying reserved list updates
To verify that the changes have actually been applied, you can run a domain
check on a modified entry using the `nomulus check_domain` command and verify
that the domain now has the correct reservation status.
```shell
$ nomulus -e production check_domain {domain_name}
[ ... snip output ... ]
```
**Note that the list can be cached for up to 60 minutes, so changes may not
take place immediately**. If it is urgent that the new changes be applied, and
it's OK to potentially interrupt client connections, then you can use the App
Engine web console to kill instances of the `default` service, as the cache is
per-instance. Once you've killed all the existing instances (don't kill them all
at once!), all of the newly spun up instances will now be using the new values
you've configured.