Proposal for the Server Role API

Tue Jun 3 11:42:07 UTC 2014

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

On 06/03/2014 03:19 AM, Marius Vollmer wrote:
> Stephen Gallagher <sgallagh at redhat.com> writes:
> 
>> On 06/02/2014 02:51 AM, Marius Vollmer wrote:
>>> 
>>> 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".
> 
> Would it be possible to explain "active" in terms of the operations
> on roles?  For example, a role becomes "active" after a successful 
> "deploy", and "decommission" causes a role to no longer be
> "active".
> 
>>>> 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
> 
> But we don't define those interfaces here, no?  We only define the 
> generic one that every role should support, and we just need one 
> concrete name for it.  org.fedoraproject.ServerRoleManager1.Role?
> 
>>> What is the state before the role is deployed?
>> 
>> Good point, we probably need "unconfigured".
> 
> So "deploy" goes from "unconfigured" to "deployed"?  Did you mean 
> "undeployed"?
> 
> Sorry for being pedantic, but IMO defining the states is not
> trivial, and a major part of the API.  So let's not hand wave them
> away now and treat them as a random string that we can easily
> change later. :-)
> 

No, you are absolutely correct that we need to have these sorted out
or it will cause problems later. I'm going to defer for the moment to
Thomas Woerner for his opinion on the above comments.

>>> 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.
> 
> A common approach would be to export "Job" objects on D-Bus that
> carry progress information and have a Cancel method.  "deploy"
> would return the path of such an object.
> 

Yes, this is absolutely the approach we would want to take, but we
still want the '*ing' states in case some *other* process
communicating with the API shows up (such as Cockpit monitoring things
while an admin is using the CLI)

>>> 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.
> 
> In what states can a "unconfigured" role be?  Maybe "unconfigured"
> can be a state.
> 

Good question; we need to figure out how this fits with
active/inactive. I think perhaps we need to step back and try to
re-think the states from the beginning. I get the impression that
trying to iteratively revise the ones we came up with first is not
proving effective.

>>> 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).
> 
> Hmm, users will always find a way to cancel even without an
> explicit button, so roles need to be prepared for that anyway, I'd
> say.
> 

Well, the reason I make that statement is that cancellation isn't
often supported by the *underlying* mechanisms. For example, if you
abort ipa-server-install, there's no telling what state your system
will be in and not guarantee that you can run 'ipa-server-install -u'
and get your system back to how it was before.

>> 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.
> 
> I think interrupting yum is well defined, no?
> 

Yeah, it's one of the most potentially catastrophic operations you can
do :-(

This is part of why I'm advocating the use of docker images for any
roles that can support them. At least that way, we can simply destroy
the container and know that the host system is untouched. However,
that won't work for all Roles (FreeIPA being the obvious one, right now).

So I'm okay with having a cancellation routine, but clients will have
to be able to expect and handle a "CannotCancel" D-BUS error if the
specific Role cannot be canceled.

>>>> 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.
> 
> Sure, I was actually going in the other direction, but I wasn't
> clear: _Instead_ of reconfigureRole (which can't be used
> generically), the generic role description would just say what
> program to run for a limited number of session types.  FreeIPA
> would say "ipa-server-install" here, and Cockpit would offer to run
> that in a terminal.
> 

I'd prefer not doing that in v1, honestly. The goal here is for the
API to always produce a known-good state following best-practices.
Giving them an official way to bypass those choices defeats the
purpose somewhat.

> The state of the role would tell when it is legal to run that
> program.
> 
> Any configuration APIs should be on the role specific interfaces
> such as org.fedoraproject.ServerRoleManager1.Role.DomainController,
> no?

Yes, was that unclear?