Shriti Chandra

• Blog

GSoD 2020 with CNCF

Final Project Report

This summer, I worked with the CNCF - SMI community and Layer5 to develop a set of documentation and interactive tutorials under the Google Season of Docs (2020) program. The project aimed to provide support and facilitate better understanding of the SMI project and service meshes, for both users and developers.

SMI Project

The SMI project, originally developed by Microsoft and donated to CNCF in April 2020, is an extensible set of API abstractions built with the intent of establishing a standard set of specifications to enable interoperability and cover the most widely used features of service meshes.

With a continuous influx of meshes in the service mesh landscape, each with its own set of APIs, the standards are ever-changing and thus difficult to surmise and check for, both by developers and users. The base problem arising here is a dearth of resources that provides you with accessible methods of inspecting your service mesh. This is where the SMI specification comes in. It defines an industry standard to compare your service mesh against and analyze its shortcomings.

SMI currently supports 4 sets of APIs:

• Traffic Specs - Used to define traffic, currently only supports TCP, HTTP traffic.
• Traffic Access Control - Used to specify whether a particular form of traffic is allowed or not
• Traffic Split - Used to redirect/divide a request for a resource between 2 or more resources. Useful in canary testing
• Traffic Metrics - Used to expose common traffic metrics like p99 in a specific format that can be utilized by a single dashboard for all the service meshes.

Why Meshery?

The SMI specs have already been widely adopted but due to SMI being a relatively new project, it is largely devoid of both, user and dev documentation. My goal was to create comprehensive end-user documentation, including a complete set of User and Dev Guides, User Tutorials, and API documentation.

Meshery, the service mesh management plane (developed by Layer5) was chosen as the tool to showcase the SMI specifications because:

• It supports upto 12 service meshes
• Allows the application of custom configurations
• Supports distributed load generation
• Enables performance testing

Being able to run performance tests with consistent load generation is a basic requirement for running SMI tests so that the tests can be easily integrated with the pipelines of any service mesh.

Project Goals

These goals were decided on after my acceptance to the Google Season of Docs program, with discussions and reviews from my mentors:

• Use Katacoda to create interactive end-user tutorials for SMI and related service meshes using Meshery as a tool.
• Rewrite, update and improve upon the end-user and dev documentation
  • Restructure the documentation
  • Locate and Rewrite outdated sections
  • Add new guides to better explain the SMI specs and Meshery’s performance testing capabilities
  • Add infographics to improve readability
  • Update the documentation site to improve end-user experience
• Make the documentation project community driven, to allow and enable easy upkeep.
• Use Swagger to generate API Endpoint documentation (if time permits)

Community Bonding

I took this time to understand the community and project goals better and established a regular channel of communication with my mentors. I also took this time to redefine my goals to stay in line with the specific aims of the SMI project and to maximize the reach and benefit to the end user. This was followed by setting a priority order for my finalized goals, after exhaustive discussions with my mentors. I followed through with these goals with weekly sync calls with my mentors, where we discussed the progress and extensibility of the project over the next four months.

Development Phase

After discussions with my mentors and in line with the SMI project’s immediate goals, I decided to give first priority to the user and dev documentation, followed by user tutorials and continuing to API documentation for Meshery, only after perfecting the first two.

Documentation

In the first phase, I started out with rewriting the User and Developer Documentation, following a draft structure I had formulated for improving the Meshery documentation in the application phase. As I continued working on the coumentation, the structure was improved upon as needed to better focus on and explain the SMI specifications, and the final implementation followed this structure.

The Meshery documentation site is built on Jekyll, a static site generator and runs in a Ruby environment.

• Rewriting the Documentation:

  I started out by rewriting the installation guides to improve readibility and user experience. I also ensured that the installation and working steps were up to date and efficient, and went along updating the documentation wherever necessary with inputs and reviews from the community. This was followed by the addition of a new quickstart guide with an easy-to-understand approach to setting up the dev environment and running Meshery locally. This was highly needed to make the tool more accessible to new users.

  Post that, I updated the user guides in an effort to explain Meshery’s various Performance testing features and also added Concept and Tutorial guides on a long list of topics, including but not limited to the SMI spec, conformance testing, load generation, lifecycle management, performance management, deploying sample applications, using metrics and more.

• Improving User Experience

  I also worked on adding features to the documentation site to improve the user experience and create a management system for a regular revisal of the documentation. These included adding a search feature and integrating a clipboard plugin. The site has been updated with a locally integrated internationlization feature and currently supports Spanish in addition to English. However, this still needs to be automated and improved upon to support more than one language. I will continue to work on this after my GSoD timeline is concluded to further add more support for internationalization and pagination features to the site.

• Integrating Visual Aids

  One of my central aims while going through the documentation was to ensure that the information provided was up to date and had been written to include precise and efficient steps to accomplish the task at hand. To accomplish this, I have personally executed each of the tasks that I have written about and have added infographics, including screenshots, GIFs, and videos to each of the guides to facilitate better understanding. This was highly needed because of the intensively technical nature of most of the documentation.

Interactive tutorials

The most efficient way of showcasing the SMI specifications was to allow users to run tests on top of a service mesh on their own, allowing them to witness, appreciate and analyze the working behind these specs. Moreover, the SMI specs don’t mean to constrain or control the configurations of a service mesh. Vendors are encouraged to build extensions or capabilities beyond the scope of the SMI API. This also helps the project grow. However, Meshery requires a docker-enabled system and inherently looks for a running Kubernetes cluster on any local system. This can involve a certain level of setup, which in turn requires an up front time investment for incoming users. To allow users to get a first hand experience with the SMI spec and running performance tests on the Meshery platform, I planned to created interactive tutorials with a sandbox environment.

Katacoda was finally chosen as the platform to make and host these tutorials, because of their easily configurable environments. Tutorials have been added on setting up and running Meshery, Deploying sample apps, and running performance tests.

Contributions

1. Issues Opened
2. Pull Requests
3. Commits
4. Issues opened by my mentors

Meshery Documentation

• Quickstart
• Installation Guides
• Service Mesh Adapter Guides
• User Guides
• Concepts

Dev Interactive Tutorials:

Katacoda : The tutorials are currently displayed on Katacoda itself and are publicly available on Katacoda, as well as on the service mesh labs repository.

Learnings

Over the last four months, I regularly engaged in the SMI and Meshery communities and attended weekly project meetings. This helped me learn a lot more about service meshes, their architecture, the SMI spec’s applications and how the APIs can be extended to fit any service mesh data plane and help test and analyze its abilities. Through the GSoD program, I had the opportunity of working in real time on an OpenSource project and was lucky enough to witness my contributions increase the project’s product value during the development phase itself.

My project included making user tutorials which in addition to being a great learning directive, was also a lot of fun because it required taking creative decisions and working through the code to figure out the most efficient ways of working with the product and presenting it to the user. I was also allowed to work with CLI commands and I utilized this opportunity for improving upon my coding skills including Golang, Javascript and bash scripting.

Future Implementations

The SMI specification is still relatively new to the service mesh landscape and needs more user tutorials and guides to familiarize both developers and users with its workings. After the conclusion of my GSoD project, I will continue to remain active in the #smi community and will also be working on creating API documentation for the Meshery project. The next steps for improvement to the SMI project should be:

• Creation of more user tutorials targeting SMI abilities and Conformance testing to make performance testing more accessible to users.
• Improvement and Upkeep of the SMI documentation to include and promote the growing service mesh landscape
• Creating API documentation for the Meshery project