Skip to content
This repository was archived by the owner on Oct 20, 2023. It is now read-only.

Commit bdb3abf

Browse files
author
Michelle Noorali
committed
ref(*): move spec into a file with version
* also moves api specs into their own directory * creates working draft under each api dir * removes apiVersion field from examples * removes groupVersion field from examples Signed-off-by: Michelle Noorali <[email protected]>
1 parent d7e2056 commit bdb3abf

File tree

14 files changed

+1462
-124
lines changed

14 files changed

+1462
-124
lines changed

‎README.md

+3-58
Original file line numberDiff line numberDiff line change
@@ -9,64 +9,9 @@ The Service Mesh Interface (SMI) is a specification for service meshes that run
99
on Kubernetes. It defines a common standard that can be implemented by a variety
1010
of providers. This allows for both standardization for end-users and innovation
1111
by providers of Service Mesh Technology. SMI enables flexibility and
12-
interoperability, and covers the most common service mesh capabilities
13-
implemented by the following APIs:
14-
15-
* Traffic policy – apply policies like identity and transport encryption
16-
across services
17-
* [Traffic Access Control](traffic-access-control.md) - configure access to
18-
specific pods and routes based on the identity of a client for locking down
19-
applications to only allowed users and services.
20-
* [Traffic Specs](traffic-specs.md) - define how traffic looks on a
21-
per-protocol basis. These resources work in concert with access control and
22-
other types of policy to manage traffic at a protocol level.
23-
* Traffic telemetry – capture key metrics like error rate and latency between
24-
services
25-
* [Traffic Metrics](traffic-metrics.md) - expose common traffic metrics for
26-
use by tools such as dashboards and autoscalers.
27-
* Traffic management – shift traffic between different services
28-
* [Traffic Split](traffic-split.md) - incrementally direct percentages of
29-
traffic between various services to assist in building out canary rollouts.
30-
31-
See the individual documents for the details. Each document outlines:
32-
33-
* Specification
34-
* Possible use cases
35-
* Example implementations
36-
* Tradeoffs
37-
38-
### Goals
39-
40-
The goal of the SMI API is to provide a common, portable set of Service Mesh
41-
APIs which a Kubernetes user can use in a provider agnostic manner. In this way
42-
people can define applications that use Service Mesh technology without tightly
43-
binding to any specific implementation.
44-
45-
### Non-Goals
46-
47-
It is a non-goal for the SMI project to implement a service mesh itself. It
48-
merely attempts to define the common specification. Likewise it is a non-goal to
49-
define the extent of what it means to be a Service Mesh, but rather a generally
50-
useful subset. If SMI providers want to add provider specific extensions and
51-
APIs beyond the SMI spec, they are welcome to do so. We expect that, over time,
52-
as more functionality becomes commonly accepted as part of what it means to be a
53-
Service Mesh, those definitions will migrate into the SMI specification.
54-
55-
### Technical Overview
56-
57-
The SMI is specified as a collection of Kubernetes Custom Resource Definitions
58-
(CRD) and Extension API Servers. These APIs can be installed onto any Kubernetes
59-
cluster and manipulated using standard tools. The APIs require an SMI provider
60-
to do something.
61-
62-
To activate these APIs an SMI provider is run in the Kubernetes cluster. For the
63-
resources that enable configuration, the SMI provider reflects back on their
64-
contents and configures the provider's components within a cluster to implement
65-
the desired behavior. In the case of extension APIs, the SMI provider translates
66-
from internal types to those the API expects to return.
67-
68-
This approach to pluggable interfaces is similar to other core Kubernetes APIs
69-
like +NetworkPolicy+, +Ingress+ and +CustomMetrics+.
12+
interoperability, and covers the most common service mesh capabilities.
13+
14+
Find the full specification [here](SPEC.md).
7015

7116
## Ecosystem
7217

‎SPEC.md

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Service Mesh Interface
2+
3+
## Version
4+
5+
This is SMI **spec** version **v0.4.0-WD**.
6+
WD stands for `working draft`.
7+
Learn more about versioning [below](#versioning).
8+
9+
## Table of Contents
10+
11+
- [Abstract](#abstract)
12+
- [Objective](#objective)
13+
- [Technical Overview](#technical-overview)
14+
- [APIs](#apis)
15+
- [Traffic Access Control](#traffic-access-control)
16+
- [Traffic Split](#traffic-split)
17+
- [Traffic Specs](#traffic-specs)
18+
- [Traffic Metrics](#traffic-metrics)
19+
- [Appendix](#appendix)
20+
- [Terminology](#terminology)
21+
- [API Development Process](#api-development-process)
22+
- [Versioning](#versioning)
23+
24+
## Abstract
25+
26+
The Service Mesh Interface (SMI) is a specification for service meshes that run
27+
on Kubernetes. It defines a common standard that can be implemented by a variety
28+
of providers. This allows for both standardization for end-users and innovation
29+
by providers of Service Mesh Technology. SMI enables flexibility and
30+
interoperability, and covers the most common service mesh capabilities.
31+
32+
## Objective
33+
34+
### Goals
35+
36+
The goal of the SMI API is to provide a common, portable set of Service Mesh
37+
APIs which a Kubernetes user can use in a provider agnostic manner. In this way
38+
people can define applications that use Service Mesh technology without tightly
39+
binding to any specific implementation.
40+
41+
### Non-Goals
42+
43+
It is a non-goal for the SMI project to implement a service mesh itself. It
44+
merely attempts to define the common specification. Likewise it is a non-goal to
45+
define the extent of what it means to be a Service Mesh, but rather a generally
46+
useful subset. If SMI providers want to add provider specific extensions and
47+
APIs beyond the SMI spec, they are welcome to do so. We expect that, over time,
48+
as more functionality becomes commonly accepted as part of what it means to be a
49+
Service Mesh, those definitions will migrate into the SMI specification.
50+
51+
## Technical Overview
52+
53+
The SMI is specified as a collection of Kubernetes APIs via Kubernetes Custom
54+
Resource Definitions (CRD) and Extension API Servers. These APIs can be
55+
installed onto any Kubernetes cluster and manipulated using standard tools.
56+
The APIs require an SMI provider to do something.
57+
58+
To activate these APIs an SMI provider is run in the Kubernetes cluster. For the
59+
resources that enable configuration, the SMI provider reflects back on their
60+
contents and configures the provider's components within a cluster to implement
61+
the desired behavior. In the case of extension APIs, the SMI provider translates
62+
from internal types to those the API expects to return.
63+
64+
This approach to pluggable interfaces is similar to other core Kubernetes APIs
65+
like +NetworkPolicy+, +Ingress+ and +CustomMetrics+.
66+
67+
## APIs
68+
69+
Find each API described at a high level below. Follow the links to see the
70+
individual API specification documents for the details. Each document outlines:
71+
72+
- Specification
73+
- Possible use cases
74+
- Example implementations
75+
- Tradeoffs
76+
77+
_Note: historical versions of the API specification as well as current working
78+
drafts can be found under the [apis/ directory](apis/)_
79+
80+
### Traffic Access Control
81+
82+
Apply policies like identity and transport encryption across services.
83+
84+
The [Traffic Access Control](apis/traffic-access/v1alpha1/traffic-access.md) API
85+
describes a resource to configure access to specific pods and routes based
86+
on the identity of a client for locking down applications to only allowed
87+
users and services.
88+
89+
### Traffic Split
90+
91+
Shift traffic between different services.
92+
93+
The [Traffic Split](apis/traffic-split/v1alpha3/traffic-split.md) API describes
94+
a resource to incrementally direct percentages of traffic between various services
95+
to assist in building out canary rollouts.
96+
97+
### Traffic Specs
98+
99+
Describe traffic on a per-protocol basis.
100+
101+
The [Traffic Specs](apis/traffic-specs/v1alpha2/traffic-specs.md) API describes
102+
a set of resources to define how traffic looks on a per-protocol basis. These
103+
resources work in concert with access control and other types of policy to manage
104+
traffic at a protocol level.
105+
106+
### Traffic Telemetry
107+
108+
Capture key metrics like error rate and latency between services
109+
110+
The [Traffic Metrics](apis/traffic-metrics/v1alpha1/traffic-metrics.md) API
111+
exposes common traffic metrics for use by tools such as dashboards and autoscalers.
112+
113+
## Appendix
114+
115+
### Terminology
116+
117+
- **SMI Provider**: An implementor of SMI. This could be a service mesh.
118+
- **API Group**: A set of resources that are exposed together. Each group may have
119+
one or more versions that evolve independently of other API Groups. Group names are
120+
in domain form.
121+
122+
### API Development Process
123+
124+
Please submit an issue or a pull request to this repository to propose a change.
125+
Changes are discussed on the [SMI community meetings](README.md/#communications).
126+
Changes should be made to working draft documents of each API which can be found
127+
in the corresponding directories under [apis/](apis/). Current working drafts
128+
documents have a suffix **-WD.md**
129+
130+
### Versioning
131+
132+
The spec has its own version listed [above](#version). This version describes the
133+
specification in its entirety. Although it is not related to the API specification
134+
versions, the minor version of the spec will be incremented every time any of the
135+
API Specification versions are incremented.

0 commit comments

Comments
 (0)