RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://google.aip.dev/128 below:

AIP-128: Declarative-friendly interfaces

AIP-128 Declarative-friendly interfaces

Many services need to interact with common DevOps tools, particularly those that create and manage network-addressable resources (such as virtual machines, load balancers, database instances, and so on). These tools revolve around the principle of "configuration as code": the user specifies the complete intended landscape, and tooling is responsible for making whatever changes are necessary to achieve the user's specification.

These tools are declarative: rather than specifying specific actions to take, they specify the desired outcome, with the actions being derived based on the differences between the current landscape and the intended one.

Furthermore, there are numerous popular DevOps tools, with more being introduced each year. Integrating hundreds of resource types with multiple tools requires uniformity, so that integration can be automated.

Guidance Resources

Resources that are declarative-friendly must use only strongly-consistent standard methods for managing resource lifecycle, which allows tools to support these resources generically, as well as conforming to other declarative-friendly guidance (see further reading).

Declarative-friendly resources should designate that they follow the declarative-friendly style:

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
    style: DECLARATIVE_FRIENDLY
  };

  // Name and other fields...
}

Reconciliation

If a resource takes time (more than a few seconds) for updates to be realized, the resource should include a bool reconciling field to disclose that changes are in flight. This field must be output only.

A resource must set the reconciling field to true if the current state of the resource does not match the user's intended state, and the system is working to reconcile them. This is regardless of whether the root cause of going into reconciliation was user or system action.

Note: Services responding to a GET request must return the resource's current state (not the intended state).