Proposal for the Server Role API

Mon Jun 2 16:46:31 UTC 2014

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 06/02/2014 02:51 AM, Marius Vollmer wrote:
> Thomas Woerner <twoerner at redhat.com> writes:
> 
> Some question that I had on first reading.  Hopefully they can help
> to improve the API, although most of them are obvious and you
> probably have thought of them already.
> 
>> org.fedoraproject.ServerRoleManager1 
>> ------------------------------------
>> 
>> Properties
>> 
>> version:s                # server role manager version state:s
>> # active/inactive/dead? roles:ao                 # role objects
>> list
>> 
>> Methods
>> 
>> getRole(role:o)→o        # get role by object
> 
> What is the input object?  On first glance, this looks like the
> identity function, no? :)
> 

I missed this one, but I'm puzzled too. Thomas?

>> getNamedRole(name:s)→o   # get role by name getActiveRoles()→ao
>> # get active role object list
> 
> What is "active", exactly?  Is it the same as state == "started"?
> 

IIRC, we're defining "active" as "we've deployed the role on this
system". That could mean "deployed but not currently started". It
might also mean "We've installed the role but have not yet configured it".

>> org.fedoraproject.ServerRoleManager1.roles.$n
> 
> What is the $n here?  Is it the version of the interface?  (If we 
> specify a concrete API, we just need one name.  Role specific APIs 
> should be separate interfaces on the same object.)
> 

I think it's supposed to be the role name, but Thomas can correct me.

So: org.fedoraproject.ServerRoleManager1.roles.DomainController or
org.fedoraproject.ServerRoleManager1.roles.DatabaseServer

>> ---------------------------------------------
>> 
>> Properties (general)       # role settings
>> 
>> name:s (ro)              # role name version:s (ro)           #
>> role version state:s (ro)             #
>> deployed/started/inactive/dead?
> 
> What is the state before the role is deployed?
> 

Good point, we probably need "unconfigured".

> Changing state is not instantanous.  Can I see when a role is
> currently being deployed (and how long that is still estimated to
> take)?
> 

Estimating the deployment time is out of scope (we probably won't
realistically know the answer).

Having "deploying" and "starting" states would be a good idea, though.

> I guess a role can also be in a "failed" state, where it is
> supposed to be active/started but something has gone wrong.
> 

I think that's what "dead" means, but maybe that should be more clear.

I'm not really sure what "inactive" means. I suspect we should
converge deployed and inactive in some way.

>> activate_time:i (ro)     # time of activation deploy_time:i (ro)
>> # time of deployment is_configured:b (ro)     # is this role
>> configured?
> 
> What does "configured" mean?  It's not the same as "active" or 
> "started", right?  Can I start a unconfigured role?  Could this be
> a state?
> 

A "configured" Role can be in any of "deployed", "starting", "started"
or "dead" states.

>> packages:as (ro)         # packages and @groups services:a{sas}
>> (ro)     # services to be enabled and/or started: "enable": [s]
>> and "start": [s] firewall:a{sas} (ro)     # firewall dict ports:
>> [s] and service: [s] #backup_paths:as         # backup files and
>> directories (directory trailing slash it means "everything below
>> here") # ...                    # custom settings, passwords as
>> key value pairs
> 
> It might not a good idea to put sensitive data like passwords into 
> properties.  The common practise seems to be to have a separate
> method to return the secrets.  This is probably done to make
> implementing access control easier, but I am not sure.
> 

Worth considering, but as this API is essentially "root-only", I'm not
sure it's urgent.

>> Methods
>> 
>> deploy()                 # deploy role (i.e. running initial
>> setup post-package-install, ipa-server-install)
> 
> How can I cancel?
> 

Cancellation isn't currently supported (in part because we don't
presently have a guarantee that installing Roles can reasonably be
rolled back).

I don't want to have a cancellation routine without a guaranteed
clean-up. This is something we may be able to address with managing
Roles in containers, though.

Thomas, maybe we can add a cancelDeployment() routine, but ensure that
clients are aware that DeploymentUncancellable or something is an
expected possibility.

>> decommission()           # decommision (example: moved to
>> another machine, ipa-server-install -u ), stop if started
>> 
>> start()                  # start the role (startServices, 
>> installFirewall), fails if not deployed stop()
>> # stop the role (stopServices, uninstallFirewall), fails if not
>> started
>> 
>> updateRole()             # update role: yum update;
>> restartServices; updateFirewall
> 
> How can I see whether an update for the role is available?
> 

Good question. Add a checkForUpdates() method?

>> reconfigureRole(a{sv})   # reconfgure role with new config
>> settings as key value pairs
> 
> A role could specific which program to run to do a interactive 
> configuration.  For terminal, for a graphical session, and for
> Cockpit (by specifying a module that Cockpit will load).
> 

Out of scope. We don't want the API to be interactive to that level.
It introduces too much complexity.

The API will be pretty much static, so the UIs should be able to just
do whatever interaction they want and then push down the final results.

>> installPackages()        # install packages and groups 
>> #uninstallPackages()     # uninstall packages and groups, fails
>> if deployed - not initially
>> 
>> startServices()          # start the services restartServices()
>> # restart the services stopServices()           # stop the
>> services
>> 
>> installFirewall()        # install firewall ports/services 
>> updateFirewall()         # update firewall ports/services 
>> uninstallFirewall()      # uninstall firewall ports/services
> 
> Is there anything more to these than convenience?  E.g., can I just
> take the 'packages' properties and use it with the package
> management API of my choice?  If we already have a good UI for the
> package management API, with highly polished progress reporting and
> error handling, say, it is probably better to just use it instead
> of trying to polish this API to the same level.

Right, these are convenience. In the case of Cockpit, I'd expect you
to use your own package-installation tool.

We should probably add 'getPackageList()' as a method that Cockpit can
use, so it doesn't have to maintain a duplicate list, though.