[kea-dev] Initial proposal for Kea Control API

[Shawn Routhier]

> On May 24, 2016, at 4:27 PM, Tomek Mrugalski <tomasz at isc.org> wrote:
> 
> Hi,
> 
> I have just finished an initial proposal for Control API for Kea. The
> proposal is available here:
> 
> http://kea.isc.org/wiki/ControlAPIRequirements
> 
> I'm very eager to hear your opinions on this. If you're an existing or
> prospective user, can you also share your perceived priorities of those
> proposed calls? Sharing your opinion on kea-dev is the best way to
> respond, but sending your comments privately off the list is ok, too.
> 
> The complete API is huge and there is no way ISC could implement all of
> it, at least not in one release. Therefore it's very useful to
> prioritize which calls should be implemented first.
> 
> Note that ISC does not plan to make actual implementation of the API in
> Kea 1.1. We had preliminary discussions whether it would be a good
> leading topic for Kea 1.2, but we did not make any specific decisions yet.
> 
> Tomek
> _______________________________________________
> kea-dev mailing list
> kea-dev at lists.isc.org
> https://lists.isc.org/mailman/listinfo/kea-dev


General:

1) Adding numbers to the questions would make it easier to reference them
in the discussion.

2) I second Thomas’s comments about security.  I don’t think we need encryption
but we will want authentication and data integrity.  If the control channel can only
be accessed from the local host we may be able to defer this for a bit, but it may
be easier to include it at the start.

3) My current understanding of multi-tenancy is that each tenant would see what
looks like their own server with (potentially) different configurations.  Following this
model it would seem best to have the tenant selector be at a fairly high level so that
each command could only affect one tenant at a time (or maybe even an entire
connection would be for a single tenant).  If others have a different understanding
of multi-tenancy, perhaps we need to discuss and define that as well?

4) Thomas’s idea of audit logs is also something that I think is useful.

5) I would find a table at the end to collect all the requirements together useful.  I’m
not sure if it would be useful enough to spend the time organizing it and updating
it as the rest of the document changes.

6) From a practical perspective if we can get an update effect by doing a delete followed
by an add we may decide that all of the updates can be deferred.  This will make
it harder to do certain things via the command channel but it also may allow the
first round of the work to be completed earlier.

7) In Bind’s RNDC there is the concept of freezing the server such that the
configuration can be updated while it is still “running” but not “serving”.  This
is useful if the admin wants to make a number of changes that should be
somewhat atomic as seen from the outside.  Do we think that such a feature
would be useful?  perhaps in the future and for now any such changes would
be done be replacing the entire configuration?

8) Should there be some sort of version or time stamp on the configuration to
allow an admin to see if anything has been changed?  I’m thinking of the case
of an admin trying to synchronize the configuration with an external source
and being able to confirm that the version or time stamp is the same as when
the external source last updated the configuration could avoid having to
retrieve and compare the entire configuration.

Administrative Actions

9) A4 - get-config
While I won’t argue for it strongly I think have a write-config command would be
convenient for the admins.  While I agree over-writing the config file on all changes
would be inappropriate I think having a command to do so would eliminate some
work for a basic set up.  The admin would understand that they would lose any
extra data in the config file but they might find that acceptable in some cases.

10) As Thomas pointed out getting a copy of the config file is going to be useful
for debugging purposes.  Either having the file saved to a diagnostic file or providing
the admin a way to save the file would seem to be useful.

Lease Management

11) Q: Do we want to have a single query?
I think a single query with multiple parameters is a better choice.

12) Q: Do we want to support multi-tenancy?
See item (3) above.

13) L.7 and L.8
See item (6) above, I think these could be moved to SHOULD rather than MUST
as their functionality could be handled by a delete and add.

14) Q: Do we want a way to delete all leases in a subnet?
Probably

15) Q: Do we want to delete all leases that belong to a certain identifier?
This could be useful but if we add it we should also probably add an option to get-leaseX
to get all of the leases. I currently read the text as saying we only support getting the
lease by identifier for a given subnet.  (Or if the subnet-id is optional that should be
made clearer in the text).  If we have a command to get all the leases then I would
make a command to delete all the leases lower priority as the admin could simply
do the get and then walk through the resulting list.

Host reservation
16) H.16 - Kea Should support get-reservation by id
This is inconsistent with H.17 which is a MUST and allows the admin to update the reservation
by selecting it via id.  I think H.16 needs to be a MUST if H.17 is a MUST (but see my
general comment and H.17 as  SHOULD or MAY).

17) Q: For IPv6 there may be multiple addresses …
As with Thomas I think this is a bit more general than just addresses and prefixes for host
reservations.  I think that eventually adding commands to add new addresses and prefixes
is useful, but I think it can be deferred.  The alternative is to have the admins do a
get command followed by editing the response and then an update.  This puts more effort
on the admin (or the tool they use to connect to Kea) but is also likely to produce more
consistent structures.

18) Q: Do we want to specify delete-reservation with ids?
Don’t we have to support this to be complete?  If we have a host reservation that only
has options but doesn’t have an ip address how else could it be deleted?

Subnets Management
19) Should there be support for get-subnetX by prefix/prefix length?
If so and continuing with the general rule that we don’t need to add convenience
commands in the first round this would probably be a MAY.

20) One note describes the expected workflow of get-subnet, edit response, update-subnet.
If we choose this style we should choose it for all of the update commands (perhaps
that is already your thinking?)  If so it should be made as a general statement to cover
all of the document.

21) I think the TBD and Q about subnet modification and subnet removal
need to be handled in the same fashion (whatever we choose).  Adding a parameter
to choose does allow the admin the flexibility to do what they think is correct.  One
of the options should be keep the leases around until they expire as the client does
still think it owns the address and there will be problems if it gets reused.

We may also want to consider the idea of before and after from ISC DHCP.  With
these options one can specify that a given subnet is to only to be used until a certain
date or only after a certain date.  Such a feature would require changes in the allocation
code as well but it would make adding, removing or updating subnet information
more convenient.  An example of how this could work is that an IPv6 subnet is being
renumbered and the old prefix should stop at midnight tonight while the new prefix
can be used after midnight.  The server would hand out shorter and shorter leases
up till midnight such that all the leases would expire at midnight when the old prefix
is no longer used.  Exact details of how to implement this would need to be discussed
and again this is likely to be deferred till later.

Options management
22) Do we want get-optionX-def which would return a single option definition
Eventually yes, but I think it would be a MAY

23) Thomas asks about what to do if one of several options in a request is invalid.
I think we want to fail the entire set.  I don’t like the term rollback as it implies that
we started setting the others and then un-did those sets.  I would prefer the code
to have validated all of the options before trying to “commit” any of them but that
is an implementation detail.

Interfaces Management
24) I agree with changing it from a MUST to a MAY

Other
25) can we update the logging information while running?  It would be useful to
modify the severity and debug level at least.

26) can we usefully display hooks information?  perhaps a MAY?