README: describe service/namespace onboarding workflow
This change adds the documentation for onboarding services
into the OSM managed service mesh.
@@ -16,4 +16,32 @@ The Open Service Mesh (OSM) project is a light weight, envoy based service mesh
Note: This project is a work in progress. See the [demo instructions](demo/README.md) to get a sense of what we've accomplished and are working on.
## OSM Design
+
Read more about the high level goals, design and architecture [here](DESIGN.md).
+
+## Managing Services Using OSM
+
+#### On-boarding services to the OSM managed service mesh
+
+To on-board a service to the OSM managed service mesh, OSM first needs to be configured to monitor the namespace the service belongs to. This can be done by labeling the namespace with the OSM ID as follows.
+```
+$ kubectl label namespace <namespace> openservicemesh.io/monitor=<osm-id>
+```
+The `osm-id` is a unique ID for an OSM instance generated during OSM install.
+
+After a namespace is labeled for monitoring, new services deployed in a monitored namespace will be a part of the service mesh and OSM will perform automatic sidecar injection for newly created PODs in that namespace.
+
+#### Disabling automatic sidecar injection
+Since the sidecar is automatically injected for PODs belonging to a monitored namespace, PODs that are not a part of the service mesh but belong to a monitored namespace should be configured to not have the sidecar injected. This can be achieved by any of the following ways.
+
+- Deploying PODs that are not a part of the service mesh in namespaces that are not monitored by OSM
+- Explicitly annotating PODs with sidecar injection as disabled: `"openservicemesh.io/sidecar-injection": "disabled"`
+
+#### Adding existing services to be managed by a new OSM instance
+Currently OSM only supports automatic sidecar injection for newly created PODs. Thus, existing services will need to be enabled for monitoring as described above, and then the PODs will need to be redeployed. This workflow will be simplified once OSM supports manual sidecar injection.
+
+#### Un-managing namespaces
+To stop OSM from monitoring a namespace, remove the monitoring label from the namespace.
+```
+$ kubectl label namespace <namespace> openservicemesh.io/monitor-
+```
\ No newline at end of file
