[PKG-Openstack-devel] OpenStack switching to a unified template system

[Justin B Rye]

Thomas Goirand wrote:
[...]
> Therefore, I've moved the shared debconf templates from each individual
> services to openstack-pkg-tools. When building, packages are copying the
> templates from /usr/share/openstack-pkg-tools/debconf, and merge the
> translations into debian/po from
> /usr/share/openstack-pkg-tools/debconf/po using msgmerge.
> 
> There's 4 templates, each for a different topic of configuration within
> OpenStack service.
> 
> 1/ configure_db: a small template to activate dbconfig-common
> 2/ api-endpoing: registration of the OpenStack APIs within Keystone catalog
> 3/ rabbitmq: configuration of access to the message queue server
> 4/ ksat: configuration of the keystone_authtoken, ie: credentials to the
> Keystone auth server.
> 
> One or more (usually all) templates are copied at build time from
> openstack-pkg-tools to the debian/ folder of each package, then a sed
> replaces "ospt" by individual package names (nova, cinder, glance, etc.)
> so that templates are owned by each package.
> 
> Doing this work, I had to remove all traces of package names within the
> templates, so that they can be generic enough. Therefore, it is
> reasonable to send these templates to this list, before asking
> translation updates for each languages.
> 
> The openstack-pkg-tools version 70, which includes these generic
> templates, hasn't been released yet, though we will upload soon.
> 
> I've attached the templates. Please review them for English exactitude.

It's getting late, so don't be surprised if I follow this up tomorrow
morning with a whole pile of corrections...

> # ### database configuration ###
> Template: ospt/configure_db
> Type: boolean
> Default: false
> _Description: Set up a database for this package?
>  No database has been set up for this package. Before continuing, you should
>  make sure you have the following information:
>  .
>   * the type of database that you want to use, generally MySQL is a good
>     choice, other implementation like Postgress or SQLite are often
>     problematic with OpenStack (this depends on each service);

Run-on sentence with some number agreement glitches.  I'm assuming
when you say "depends on" that you just mean in the sense of "varies
with" rather than "Depends:", but then you can't really use "each".

    * the type of database that you want to use - generally MySQL is a good
      choice, and other implementation like Postgress or SQLite are often
      problematic with OpenStack (this depends on the service);

>   * the database server hostname (that server must allow TCP connections from
>     this machine);
>   * a username and password to access the database.
>  .
>  Note that if you plan on using a remote database server, you must first
>  configure dbconfig-common to do so (using dpkg-reconfigure dbconfig-common),
>  and the remote database server needs to be configured with adequate
>  credentials.
>  .
>  If some of these requirements are missing, do not choose this option and run with
>  regular SQLite support.
                                                                       ^
(An added comma here would reduce the attractiveness of the "don't
drink and drive" misparsing.)

>  .
>  You can change this setting later on by running "dpkg-reconfigure -plow".
> 

> # ### service and endpoint registration ###
> Template: ospt/configure_api-endpoint
> Type: boolean
> Default: false
> _Description: Register this service in the Keystone endpoint catalog?
>  Each OpenStack service (each API) must be registered in the Keystone catalog
>  in order to be accessible. This is done using "openstack service create" and
>  "openstack endpoint create". This can be done automatically now.
>  .
>  Note that you will need to have an up and running Keystone server on which to
>  connect using a known admin project name, admin username and password. The
>  admin auth token is not used anymore.
>  .
>  Also, if a service of the matching name for this service is already present
>  in the Keystone catalog, endpoint registration will be aborted.

"A service of the matching name for this service" should probably be
just "a service with a matching name".
 
> Template: ospt/api-keystone-address
> Type: string
> _Description: Keystone server address:
>  Please enter the address (IP or resolvable address) of the Keystone server,
>  for creating the new service and endpoints.
>  .
>  Any non-valid ipv4, ipv6 or host address string will abort the endpoint
>  registration.
> 
> Template: ospt/api-keystone-admin-username
> Type: string
> Default: admin
> _Description: Keystone admin name:
>  To create the service endpoint, this package needs to know the Admin login,
>  name, project name, and password, so it can issue commands through the the
>  Keystone API.
                                                                      ^^^^^^^
Oops, double article, here and twice more below.

(And since I'm editing that line perhaps it should start with
"username" rather than just "name".)
 
> Template: ospt/api-keystone-admin-project-name
> Type: string
> Default: admin
> _Description: Keystone admin project name:
>  To create the service endpoint, this package needs to know the Admin login,
>  name, project name, and password, so it can issue commands through the the
>  Keystone API.
> 
> Template: ospt/api-keystone-admin-password
> Type: password
> _Description: Keystone admin password:
>  To create the service endpoint, this package needs to know the Admin login,
>  name, project name, and password, so it can issue commands through the the
>  Keystone API.
> 
> Template: ospt/api-endpoint-address
> Type: string
> _Description: This service endpoint IP address:
                ^^^^
The "this" is awkward here - "Service endpoint IP address:" works well
enough (and it's clarified below).

>  Please enter the endpoint address that will be used to contact this service.
>  .
>  This address should be accessible from the clients that will use this
>  service, so if you are installing a public cloud, this should be a public
>  address. You can specify either a Fully Qualified Domain Name (FQDN) or an IP
>  address. If you specify an FQDN, it must be resolvable for every host in this
>  cloud, preferably through the /etc/hosts file rather than a DNS query.
> 
> Template: ospt/api-endpoint-region-name
> Type: string
> Default: regionOne
> _Description: Name of the region to register:
>  OpenStack supports using regions, with each region representing a different
>  location (usually a different data center). Please enter the region name that
>  you wish to use when registering the endpoint.
>  .
>  The region name is usually a string containing only valid latin alphabet
>  chars, dots and dashes. A non-valid string will abort the API endpoint
>  registration.

"Chars" is a colloquial abbreviation, and talking about the Latin
alphabet makes me wonder whether I'm allowed to use things like <w> or
<é>, or indeed <1>, so probably this should be

   The region name is usually a string containing only ASCII alphanumerics,
   dots, and dashes.

(I'm hoping that also makes it obvious that we don't mean "dots and
dashes" in the sense of "· · · — — — · · ·".)

> # ### keystone_authtoken configuration ###
> # ksat stands for keystone authtoken
> Template: ospt/configure_ksat
> Type: boolean
> Default: false
> _Description: Manage keystone_authtoken with debconf?
>  Every OpenStack service must contact Keystone, and this is configured through
>  the [keystone_authtoken] section of the configuration. Specify if you wish to
>  handle this configuration through debconf.
> 
> Template: ospt/ksat-public-url
> Type: string
> Default: http://localhost:5000
> _Description: Auth server public endpoint url:

For consistency, "URL" (here and below).

>  Specify the URL of your Keystone authentication server public endpoint. This
>  value will be set in the www_authenticate_uri directive.
> 
> Template: ospt/ksat-admin-url
> Type: string
> Default: http://localhost:35357
> _Description: Auth server admin endpoint url:
>  Specify the URL of your Keystone authentication server admin endpoint. This
>  value will be set in auth_url.
> 
> Template: ospt/ksat-region
> Type: string
> Default: regionOne
> _Description: Keystone region:
>  Specify the Keystone region to use.

(Should this perhaps append "The region name is usually..."?)

> 
> Template: ospt/ksat-create-service-user
> Type: boolean
> Default: true
> _Description: Create service user?
>  This package can reuse an already existing username, or create one right now.
>  If you wish to create one, then you will be prompt for the admin credentials.
                                                    ^^
That's "prompted".

> Template: ospt/ksat-admin-username
> Type: string
> Default: admin
> _Description: Auth server admin username:
> 
> Template: ospt/ksat-admin-project-name
> Type: string
> Default: admin
> _Description: Auth server admin project name:
> 
> Template: ospt/ksat-admin-password
> Type: password
> _Description: Auth server admin password:
> 
> Template: ospt/ksat-service-username
> Type: string
> _Description: Auth server service username:
> 
> Template: ospt/ksat-service-project-name
> Type: string
> Default: service
> _Description: Auth server service project name:
> 
> Template: ospt/ksat-service-password
> Type: password
> _Description: Auth server service password:
> 

> # ### rabbitmq access configuration ###
> Template: ospt/configure_rabbit
> Type: boolean
> Default: false
> _Description: Configure rabbitmq with debconf?

When should this (and others) be rabbitmq and when should it be
RabbitMQ?  I'll leave it for now.

>  OpenStack services needs access to a message queue server. This is
                          ^
Plural agreement: "services need access".

>  configured through the transport_url directive. Specify if you
>  wish this package configuration to be handled through debconf.

You mean "wish the relevant piece of configuration (for this package)
to be handled through debconf", right?  "Package configuration" is
already being handled through debconf!

It's also d-l-e policy to discourage "wishing" prompts (if only
because the person answering "yes" might be reluctantly following
corporate policy); I'm not being strict about this elsewhere, but I'm
already rephrasing this paragraph and I'd also like to eliminate
the repeated "configure X through Y".  So how about:

   OpenStack services need access to a message queue server, defined by
   the transport_url directive. Please specify whether configuring this
   should be handled through debconf.

>  .
>  Note that only access to rabbitmq is handled, and that rabbitmq-server user
>  creation isn't performed (you must create usernames and set passwords
>  before installing this package). Also, the standard rabbitmq-server guest
>  account cannot be used for remote connection.
> 
> Template: ospt/rabbit-host
> Type: string
> Default: localhost
> _Description: IP address of your RabbitMQ host:
>  In order to interoperate with other components of OpenStack, this package
>  needs to connect to a central RabbitMQ server.
>  .
>  Please specify the IP address of that server.
> 
> Template: ospt/rabbit-userid
> Type: string
> Default: guest
> _Description: Username for connection to the RabbitMQ server:
>  In order to interoperate with other components of OpenStack, this package
>  needs to connect to a central RabbitMQ server.
>  .
>  Please specify the username used to connect to the RabbitMQ server.
> 
> Template: ospt/rabbit-password
> Type: password
> _Description: Password for connection to the RabbitMQ server:
>  In order to interoperate with other components of OpenStack, this package
>  needs to connect to a central RabbitMQ server.
>  .
>  Please specify the password used to connect to the RabbitMQ server.
> 

These are fine, or maybe I need some sleep.
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
-------------- next part --------------
A non-text attachment was scrubbed...
Name: openstack-pkg-tools.diff
Type: text/x-diff
Size: 6132 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/openstack-devel/attachments/20180306/326a4b20/attachment-0001.diff>
-------------- next part --------------
# ### database configuration ###
Template: ospt/configure_db
Type: boolean
Default: false
_Description: Set up a database for this package?
 No database has been set up for this package. Before continuing, you should
 make sure you have the following information:
 .
  * the type of database that you want to use - generally MySQL is a good
    choice, and other implementation like Postgress or SQLite are often
    problematic with OpenStack (this depends on the service);
  * the database server hostname (that server must allow TCP connections from
    this machine);
  * a username and password to access the database.
 .
 Note that if you plan on using a remote database server, you must first
 configure dbconfig-common to do so (using dpkg-reconfigure dbconfig-common),
 and the remote database server needs to be configured with adequate
 credentials.
 .
 If some of these requirements are missing, do not choose this option, and run with
 regular SQLite support.
 .
 You can change this setting later on by running "dpkg-reconfigure -plow".

-------------- next part --------------
# ### service and endpoint registration ###
Template: ospt/configure_api-endpoint
Type: boolean
Default: false
_Description: Register this service in the Keystone endpoint catalog?
 Each OpenStack service (each API) must be registered in the Keystone catalog
 in order to be accessible. This is done using "openstack service create" and
 "openstack endpoint create". This can be done automatically now.
 .
 Note that you will need to have an up and running Keystone server on which to
 connect using a known admin project name, admin username and password. The
 admin auth token is not used anymore.
 .
 Also, if a service with a matching name is already present in the Keystone
 catalog, endpoint registration will be aborted.

Template: ospt/api-keystone-address
Type: string
_Description: Keystone server address:
 Please enter the address (IP or resolvable address) of the Keystone server,
 for creating the new service and endpoints.
 .
 Any non-valid ipv4, ipv6 or host address string will abort the endpoint
 registration.

Template: ospt/api-keystone-admin-username
Type: string
Default: admin
_Description: Keystone admin name:
 To create the service endpoint, this package needs to know the Admin login,
 username, project name, and password, so it can issue commands through the
 Keystone API.

Template: ospt/api-keystone-admin-project-name
Type: string
Default: admin
_Description: Keystone admin project name:
 To create the service endpoint, this package needs to know the Admin login,
 username, project name, and password, so it can issue commands through the
 Keystone API.

Template: ospt/api-keystone-admin-password
Type: password
_Description: Keystone admin password:
 To create the service endpoint, this package needs to know the Admin login,
 username, project name, and password, so it can issue commands through the
 Keystone API.

Template: ospt/api-endpoint-address
Type: string
_Description: Service endpoint IP address:
 Please enter the endpoint address that will be used to contact this service.
 .
 This address should be accessible from the clients that will use this
 service, so if you are installing a public cloud, this should be a public
 address. You can specify either a Fully Qualified Domain Name (FQDN) or an IP
 address. If you specify an FQDN, it must be resolvable for every host in this
 cloud, preferably through the /etc/hosts file rather than a DNS query.

Template: ospt/api-endpoint-region-name
Type: string
Default: regionOne
_Description: Name of the region to register:
 OpenStack supports using regions, with each region representing a different
 location (usually a different data center). Please enter the region name that
 you wish to use when registering the endpoint.
 .
 The region name is usually a string containing only ASCII alphanumerics,
 dots, and dashes. A non-valid string will abort the API endpoint
 registration.

-------------- next part --------------
# ### keystone_authtoken configuration ###
# ksat stands for keystone authtoken
Template: ospt/configure_ksat
Type: boolean
Default: false
_Description: Manage keystone_authtoken with debconf?
 Every OpenStack service must contact Keystone, and this is configured through
 the [keystone_authtoken] section of the configuration. Specify if you wish to
 handle this configuration through debconf.

Template: ospt/ksat-public-url
Type: string
Default: http://localhost:5000
_Description: Auth server public endpoint URL:
 Specify the URL of your Keystone authentication server public endpoint. This
 value will be set in the www_authenticate_uri directive.

Template: ospt/ksat-admin-url
Type: string
Default: http://localhost:35357
_Description: Auth server admin endpoint URL:
 Specify the URL of your Keystone authentication server admin endpoint. This
 value will be set in auth_url.

Template: ospt/ksat-region
Type: string
Default: regionOne
_Description: Keystone region:
 Specify the Keystone region to use.

Template: ospt/ksat-create-service-user
Type: boolean
Default: true
_Description: Create service user?
 This package can reuse an already existing username, or create one right now.
 If you wish to create one, then you will be prompted for the admin credentials.

Template: ospt/ksat-admin-username
Type: string
Default: admin
_Description: Auth server admin username:

Template: ospt/ksat-admin-project-name
Type: string
Default: admin
_Description: Auth server admin project name:

Template: ospt/ksat-admin-password
Type: password
_Description: Auth server admin password:

Template: ospt/ksat-service-username
Type: string
_Description: Auth server service username:

Template: ospt/ksat-service-project-name
Type: string
Default: service
_Description: Auth server service project name:

Template: ospt/ksat-service-password
Type: password
_Description: Auth server service password:

-------------- next part --------------
# ### rabbitmq access configuration ###
Template: ospt/configure_rabbit
Type: boolean
Default: false
_Description: Configure rabbitmq with debconf?
 OpenStack services need access to a message queue server, defined by
 the transport_url directive. Please specify whether configuring this
 should be handled through debconf.
 .
 Note that only access to rabbitmq is handled, and that rabbitmq-server user
 creation isn't performed (you must create usernames and set passwords
 before installing this package). Also, the standard rabbitmq-server guest
 account cannot be used for remote connection.

Template: ospt/rabbit-host
Type: string
Default: localhost
_Description: IP address of your RabbitMQ host:
 In order to interoperate with other components of OpenStack, this package
 needs to connect to a central RabbitMQ server.
 .
 Please specify the IP address of that server.

Template: ospt/rabbit-userid
Type: string
Default: guest
_Description: Username for connection to the RabbitMQ server:
 In order to interoperate with other components of OpenStack, this package
 needs to connect to a central RabbitMQ server.
 .
 Please specify the username used to connect to the RabbitMQ server.

Template: ospt/rabbit-password
Type: password
_Description: Password for connection to the RabbitMQ server:
 In order to interoperate with other components of OpenStack, this package
 needs to connect to a central RabbitMQ server.
 .
 Please specify the password used to connect to the RabbitMQ server.