Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update premium and reserved list management docs #380

Merged
merged 1 commit into from Nov 21, 2019
Merged

Update premium and reserved list management docs #380

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
34 changes: 30 additions & 4 deletions docs/operational-procedures/premium-list-management.md
View file
Open in desktop
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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 changes: 39 additions & 13 deletions docs/operational-procedures/reserved-list-management.md
View file
Open in desktop
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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.