peripli / specification Goto Github PK
View Code? Open in Web Editor NEWService Manager Specification
License: Apache License 2.0
Service Manager Specification
License: Apache License 2.0
Here is a list of feedback I collected while re-reading the spec. I am willing to create PRs but I want to make sure people think this feedback is valid.
https://github.com/bkrannich/specification/blob/sm-ops/api.md#overview
https://github.com/bkrannich/specification/blob/sm-ops/api.md#creating-a-resource-entity
https://github.com/bkrannich/specification/blob/sm-ops/api.md#body-3
https://github.com/bkrannich/specification/blob/sm-ops/api.md#resource-types
https://github.com/bkrannich/specification/blob/sm-ops/api.md#osb-management
Service Manager could expose an unsecured endpoint that provides information that can be used when accessing its APIs.
This endpoint would be of use to the CLI. It can obtain the endpoints for issuing and refreshing tokens when calling the Service Manager's APIs.
Example:
GET /v1/info
Reponse:
{
"token_issuer": "https://example.com"
}
Where example.com has .well-known/openid-configuration
endpoint as per https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest
This configuration used in the Service Manager authentication should be similar to https://kubernetes.io/docs/admin/authentication/#openid-connect-tokens whereas this info endpoint could be similar to https://apidocs.cloudfoundry.org/268/info/get_info.html
Once #6 is Done, proceed and create detailed content for section "problem definition"
The document structure can be validated with serve of static checks.
Automate those checks with travis build prior PR merge.
Define domain model and corresponding data structures that shall be used for persisting the model in database.
Is there any reason why "state" isn't just part of each object instead of under a different url (e.g. /resource/state) ? It would be good if each object had "state" (just like each has "labels") to provide some consistency. Then a user can GET a resource and see it all in one response object instead of having to GET /resource and GET /resource/state.
This would then also allow for a more consistent pattern between sync and async - meaning doing a GET on a resource URL will always tell us what's going on with it.
Operation that returns all registered service brokers is missing in SM Control API.
Add this operation to specification with all required details:
We could use offset
and limit
query parameters as suggested in https://pages.apigee.com/eBook-WebAPIDesignTheMissingLink_ConfirmationPage.html
How is this done in the service-catalog or K8S?
As part of phase 1 some limitation on specification and corresponding reference implementation will be applied. Such limitations are:
Once #6 is Done, proceed and create detailed content for section "high level architecture"
architecture diagram + sequence diagram + scenarios
PATCH is used to update a resource and missing fields of the request are treated as "non-changed" fields - we should then provide a mechanism to delete (or null out) a field. I would suggest that passing in "null" to mean null out a field - and I would make a "null" value for a field the same as deleting the field. I'm not sure there's value in an optional field being there with a value of "null".
Rather than supporting OSBAPI for instance and binding management, we should consider using a more "normal" REST HTTP approach - one that continues the pattern defined by the APIs in the spec for managing platforms and brokers.
Pullapprove-like feature is available in Github by using Code Owners[1]. I think it would be nice to have this for the specification. Have a list of "maintainers" from which a subset must approve a specific pull request before it can be merged. Granted, it lacks the "disable merge" functionality of pullapprove but I think that's sufficient.
[1]https://blog.github.com/2017-07-06-introducing-code-owners/
Create repository for the specification.
The repository should include:
The release notes shall be filled manually on each change that modifies the specification.
The changes and the corresponding release notes shall be part of single pull request.
The structure need to be like this:
Keep each section in separate document, linked from index (README.md).
I am registering a service broker via SMCTL tool (smctl curl curl /v1/service_brokers -X POST ...). The name of the service broker is always original_name_<subaccount_id>. Can a broker be registered with a name independent from the subaccount?
All committers have to sign the CLA (SAP_CLA) prior PR to be merged.
Link the repository to cla-assistant.io to ensure this.
I think more is needed w.r.t. describing how async works. I would prefer a model like:
CI for Documentation repository that executes the following tasks on each PR and merge:
Create a document with clear statements about contribution to this project.
Similar document have on other open source projects. Examples are:
https://github.com/openservicebrokerapi/servicebroker/blob/master/CONTRIBUTING.md
https://github.com/cloudfoundry/bosh/blob/master/CONTRIBUTING.md
...
Mandatory sections are:
All resources that support mutation operations (creation, deletion and update) MUST contain a state
object. After performing a mutation request, the response MUST include a Location
header from where information about the resource's state
can be obtained. This MAY or MAY NOT be the Retrieve
(GET
) API for the resource entity that is being mutated.
The state
reflects the real state in which the resource currently is. It includes information regarding whether the resource is currently usable or not (ready
or not) and it contains conditions
that provide further details if the resource is not ready (is not usable).
The state
is of particular interest when the mutation operations are asynchronous. But even synchronously mutatable resources should provide state
for consistency reasons. This state
of synchronously mutated resources would often include no conditions.
Field | Type | Description |
---|---|---|
ready* | boolean | Indicates whether a resource is ready for use or not. This value is calculated by the Service Manager based on the conditions' statuses using a resource specific aggregation policy for the conditions that are defined for this resource |
conditions* | array of conditions | Describe the state of the resource and indicate what actions should be taken in order for the resource to become ready. May be an empty array |
message* | string | Human-readable summary for the reasoning behind the ready being what it is |
The conditions
describe the current condition in which the resource is.
Each resource MAY add resource specific conditions and should also handle those conditions accordingly in case they sum up to an undesired state
(in most cases this would be a ready:false
state).
Each condition
MAY include additional fields apart from those specified below in order to provide meaningful information.
Field | Type | Description |
---|---|---|
type* | string | The type of the condition. Each resource defines a set of condition types that are relevant for it. |
status* | string | The status of the condition. Each condition defines its own status values and gives them semantics. Used to determine whether any actions should be taken in regards of this condition. For example, a condition of type last_operation with status in_progress would imply that the operation is still in running. If the status is success it would imply that the operation has successfully finished and if it is failed it would imply that the last_operation failed |
message | string | Human-readable details that describe the condition |
The state
MUST be maintained up-to-date and reflect the real state of the resource. When a process or a component takes actions due to the state
not matching what is actually desired, the process or component MUST also take care of updating the respective conditions
that it has performed actions upon. When any conditions are updated the ready
field MUST be recalculated and updated by the Service Manager.
Each Service Manager resource MUST define the conditions that are relevant for it. It MUST also define an aggregation policy that sums up the conditions
and decides whether the resource is ready
or not. Based on this policy every time a resource's condition
is changed, the ready
field should be recalculated and updated. The fact that each resource defines it's own conditions
and an aggregation policy based on those conditions
is an implementation detail but it is worth mentioning it here to better describe the idea behind the state
.
Example Resource with a State Object:
{
"id": "0941-12c4b6f2-335a-44a3-b971-424ec78c7353",
...
"state": {
"ready": "False",
"message": "Service Binding is currently being created",
"conditions": [
{
"type": "last_operation",
"status": "in_progress",
"message": "Creating deployment pg-0941-12c4b6f2-335a-44a3-b971-424ec78c7353",
"name": "Create"
}
]
}
}
The example state above represents the state of a resource called service_binding
with an id
equal to 0941-12c4b6f2-335a-44a3-b971-424ec78c7353
. The state
implies that the service binding is not ready (it is not usable) due to the fact that the last operation (namely Create, hence the name
field) performed on this entity is currently still running (the status
of the last_operation
condition
is in_progress
).
To register (or create) a new platform resource we do: POST /v1/platforms
and the ID of the platform is in the HTTP Body.
We can then later get info about that platform (or update it) via /v1/platforms/:ID
.
it seems to me that if we're going to have the client pass in the ID then it should be a PUT to the v1/platforms/:ID
URL not a POST since POST is typically for when the server is going to decide things like the resource's ID and final URL.
should the client pick the ID at all? What is the benefit of forcing the client to pick a globally unique value? Is it just for easy reference later on? If so, what is the benefit of using that ID as part of the URL? When we allow some other system to pick our unique IDs then we run the risk of them needing to change them later on - or (forever) maintain a mapping. E.g. what if they need to update the ID? I'm wondering if ID should just be a field of the resource but not part of the URL of the resource. Then clients can update the ID if they need to w/o the URL of the resource changing. Since we're not bound by the "brokers are stateless" constraints, we don't need to force the client to provide info on behalf of the server.
The word "Landscape", to me, brings up thoughts of something abstract - e.g. "What is the Cloud Landscape with respect to Serverless?" But in this case we're talking about a concrete set of Platform Instances. I think it would require less learning for people to use "Environment" or even "Instance".
Write details about CLI commands. For each command specify:
Create sequence diagrams that visualise the communication and participants on each of the calls in all of the covered scenarios.
Operation that returns all registered platforms is missing in SM Control API.
Add this operation to specification with all required details:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.