spiffe / spire-api-sdk Goto Github PK

Pursuant to spiffe/spire#2246, we need a new API for privileged platform components to interact with SPIRE Agent for the purpose of delegated SVID management.

There are many possible shapes here, and given the use cases I've seen before I can think of at least a few. That said, there is one immediate need that is clear. I suggest we start with just one or two RPCs, the minimum to meet the use case at hand, knowing that we will likely add more RPCs in the future as additional integration work arises.

see spiffe/spire#4785

This commit introduces:

New Data Types

• Logger : a representation of a logger

  • name : the logger's name, empty for the root logger
  • current_level : the current log level of the logger
  • default_level : the log level of the logger configured
    in the application's config file

• LoggerMask : which Logger fields must be populated on a
  query response

  • current_level : populate the current log level
  • default_level : populate the default log level

Single Logger Operations:

• GetLogger : Fetches the log level of the logger

  • Input: name, the logger name
    (optional, unset is root logger)
  • Input: output_mask, the desired logger output fields
    (optional, unset is all fields)
  • Output: a Logger record

• AdjustLogger : Changes the log level of the logger

  • Input: name, the logger name
    (optional, unset is the root logger)
  • Input: log_level, the logger's new LogLevel
    (required)
  • Output: none

Plural Logger Operations:

• CountLoggers : Returns the number of loggers

  • Input: none
  • Output: the number of loggers

• ListLoggers : Show Logger details for a number of loggers

  • Input: filter, the control over which loggers are returned.
    (optional, unset is the root logger with all sub-loggers)
    • filter.by_name : the name of the logger forming the root
      of the returned loggers
    • filter.with_subloggers : a flag indicating if sub-loggers
      are to be included in the response
  • Input: output_mask, the fields to be returned in the output
    • output_mask.current_level : show the current log level of
      the logger
    • output_mask.default_level : show the log level of the logger
      configured in the process config
      file

SPIRE PR spiffe/spire#3982 added a spire-server CLI command for pruning old agents out of the database. That work does client-side filtering of agents to determine which need pruning. During review, this was flagged and we agreed that the prune logic is best handled server-side.

Introduce and implement a new RPC to support this server-side prune feature

Hopes to add some test cases

The Server and Agent APIs currently provide only a short description of the purpose of each RPC with documentation of each request/response field. It would be helpful to API clients to also be able to see all the expected gRPC status codes for each RPC, with a description of the cases in which each status code is returned. Clients need to understand why a particular status code would be returned so they can determine how to handle it. API dashboards and alerting also need to be built around these status codes.

Documenting the expected RPC status codes in the protobuf presents the following advantages:

• One place for all information you need as a consumer of SPIRE APIs. Right now, to discover the returned status codes requires studying the implementation of the APIs. This is not always easy to do because it requires examining middleware and API handler code.
• Establishes expected status codes explicitly as part of the API contract. This will help catch potential API regressions that may break client consumption/alerting.