Cloud Native Computing Foundation (CNCF) projesi

Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.

Proje özeti

Açık kaynak kuruluşu:
Cloud Native Computing Foundation (CNCF)
Teknik yazar:
Shriti
Projenin adı:
SMI ve ilgili hizmet ağlarının belgelerini iyileştirme
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

Service Mesh Teknolojisinin temel amacı; güvenlik, yönetim ve izlemeyle ilgili tüm ihtiyaçlarınızı karşılayarak gittikçe artan hizmet sayısına değer katmaktır. Hizmet Ağı Arayüzü (SMI), en yaygın hizmet ağı kullanım durumları (trafik politikası, telemetri ve değiştirme) için bir dizi API tanımlar ve bir mikro hizmet ortamında hizmetten hizmete iletişimi yönetmeye yönelik özel altyapı katmanları olan hizmet ağları arasında uyumluluk sağlar. Bu arayüzlerin standartlaştırılması, gelişmiş bir son kullanıcı deneyimi sağlayacağından, SMI ve ilgili hizmet ağları için gelecekte kullanılabilecek bir hedeftir.

Mevcut Durum:

Kullanıcı Kılavuzları: SMI, Nisan 2020'de CNCF'ye bağışlanan nispeten yeni bir korumalı alan projesidir. Sonuç olarak projede son kullanıcı dokümanları eksik. Meshery, farklı hizmet ağlarının performansının benimsenmesini, yapılandırılması, çalıştırılması ve yönetilmesini kolaylaştıran her tür hizmet için performans karşılaştırma olanağı sunan bir hizmet yönetimi düzlemidir. Ayrıca, herhangi bir hizmet ağının üzerinde çalışan uygulamalardan metriklerin toplanmasını ve gösterilmesini sağlar. Bu nedenle, SMI kullanıcı topluluğunun tamamı için başlangıç noktası olacak bir Meshery kılavuzuyla başlamak istiyorum.

Kullanıcı Eğitimleri: Mevcut SMI platformları arasında: Learn Layer5 adlı örnek uygulama, şu anda SMI için bir öğrenme aracı ve SMI spesifikasyonu doğrulamasının gerçekleştirileceği örnek uygulama olarak hizmet veriyor. Bunun dışında SMI projelerinde son kullanıcı eğitimleri tamamen eksik. Bu durum, projelerin son derece teknik yapısı nedeniyle ciddi bir engel teşkil ediyor. Meshery, SMI ve ilgili hizmet ağlarının avantajlarını ve kullanımını sergilemek için mükemmel bir uygulamadır. Bu nedenle, SMI'nin özelliklerini sergilemek için temel araç olarak kullanacağım.

API Dokümanları: şu anda mevcut değil. SMI ve ilgili çeşitli projelerin API uç noktaları bir platformda tanımlanmıştır. Örneğin, Meshery'nin uç noktaları server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) dosyasında tanımlanmıştır ancak bu uç noktalara dair iyi yorumlar veya harici dokümanlar yoktur. Bu durum, API'lerin anlamlı dokümanları ile çözülebilir ve kullanıcıların uç noktalarını test edip özelliklerini önizleyebilecekleri yöntemler ekleyerek iyileştirilebilir.

Analiz:

Kullanıcı Eğiticileri, kullanıcıların yazılımla etkileşimde bulunmasına ve yazılımı test etmesine olanak tanımak için oluşturulmuştur. Kullanıcının ilgisini kaybetmemesi ve en önemlisi kullanımının kolay olması için bu reklamların etkileşimli ve estetik açıdan çekici olması gerekir.

Ancak kullanıcı kılavuzları genellikle referans kılavuzu veya sorunlara hızlı bir çözüm bulma yeri olarak kullanıldığı için kullanıcı kılavuzlarını yazmak veya barındırmak için daha gelişmiş bir biçim önerilir. Bu sayfaların etkileşimli olması yerine iyi yapılandırılmış olması ve netliği, tutarlılığı ve iyi kullanıcı akışını iyileştirmeye odaklanması gerekir.

Bunun olası bir çözümü, Google Codelabs'i kullanarak ayrı kullanıcı eğitimleri ve Jekyll'in yardımıyla bağımsız bir kullanıcı kılavuzu oluşturmak ve son olarak bunları API dokümanlarıyla entegre ederek hem son kullanıcıya hem de gelecekteki iş ortaklarına kapsamlı bir deneyim sunmaktır.

Hedef Kitle: SMI projeleri, bu projelerin kapsamındaki tüm projeler için dağıtım ve operasyon uygulamaları, öğrenme ortamları ve performans karşılaştırmaları sağlar. Hem bireylere hem de kuruluşlara hitap eder.

Kullanıcı Kılavuzları: Kullanıcı tarafında önceden var olan BT bilgisi varsaymadan, başlangıç seviyesindeki kullanıcıları hedefliyorum. Hedef: Başlangıç seviyesindeki kullanıcılar Nedeni: Genellikle geniş bir referans rehberi olarak kullanılır ve zaman içinde güncellenmesi gerekir. Kullanıcının bir hizmet ağı kurmak ve onunla çalışmak için ihtiyaç duyduğu tüm bilgilere sahip olmasını sağlayacak ayrıntılı açıklamalar ve faydalı ipuçları burada yer alacaktır. Gerektiği yerlerde video, resim, ekran görüntüsü ve GIF ekleyerek kılavuzu daha ilgi çekici ve kullanıcı dostu hale getireceğiz.

Kullanıcı Eğitimleri: Hedef: Başlangıç Seviyesi Kullanıcılar Nedeni: Eğitimlerin ilgi çekici ve estetik açıdan hoş olması, kullanıcının dikkatini çekmesi ve yazılımın sorunsuz bir şekilde test edilmesine olanak tanıması, böylece Service Mesh arayüzünün daha iyi anlaşılmasını sağlamak için odaklanılacak.

API uç noktası dokümanları: Hedef: İleri Düzey Kullanıcılar Nedeni: Bu bölümde, hizmet ağının daha karmaşık özelliklerinin kullanılmasına odaklanılır. Bu özellikler, temel düzeyde BT bilgisine sahip ileri düzey kullanıcılar için daha uygundur. İleri düzey kullanıcılar, gerektiğinde referans kılavuzu olarak da kullanılabilecek kısa eğitim videoları arayacaktır. Uç nokta belgeleri, doğruluğundan veya tutarlılığından ödün vermeden kolayca güncellenebilecek şekilde yazılmalıdır. Bu işlem tercihen otomatik olmalıdır.

Kaynaklar: Kullanıcı Eğitimleri: Google Developers Codelab: Etkileşimli ve kapsamlı son kullanıcı eğitimleri oluşturmak için kullanılır. Avantajlar: - Korumalı alan eğitimlerini oluşturabilirsiniz. - Uygulamalı bir yaklaşıma sahiptir. - Google Dokümanlar kullanılarak yazılmış ve Markdown metnini destekler. - Google Analytics kullanılarak izlenebilir. - Kullanıcı trafiğini gözlemlemek kolaydır. - Kullanımı kolaydır. Kullanıcının herhangi bir yatırım yapmadan doğrudan yazılımla etkileşime geçmesine olanak tanıyan, estetik açıdan hoş eğitici içerikler üretir.

Google Codelabs, CLaaT (Codelabs as a Thing) projesi kullanılarak geliştirilebilir ve kolayca dağıtılabilir. Bu program, Markdown kullanılarak Google Dokümanlar'da yazılan eğitici içerikleri Codelabs (HTML) biçimine dönüştürmek için kullanılan bir komut satırı aracı sunar.

Kullanıcı Kılavuzları: Jekyll - Meshery.io için, burada bulabileceğiniz mevcut dokümanlar Jekyll'de barındırılmaktadır ve Docsy Jekyll temasını kullanmaktadır. Barındırılmaya hazır statik web siteleri oluşturmak için Markdown, liquid, HTML ve CSS'yi kullanır ve Ruby geliştirme ortamında çalışır. Avantajları: - Siteleri doğrudan GitHub depolarından barındırabilir. - Bu, çok etkin bir topluluğu olan ve iyi desteklenen bir projedir. - Kullanıcı kılavuzları ve geliştirmeler, başka bir platforma taşınma zahmetine girmek zorunda kalmadan mevcut SMI ve Meshery dokümanlarına kolayca eklenebilir.

API Dokümanları: SMI ve Meshery için API dokümanları oluşturmak amacıyla Swagger (alternatif olarak Swaggo) kullanılacaktır. API dokümanı yazmak için şık bir çözümdür. Avantajlar: - API Tasarımınızdan Belgeler: API'niz geliştikçe belgelerinizin güncel kalmasını sağlar. - API Tasarımınızdan Belgeler: API tanımlarından otomatik olarak oluşturulabilir. - Birden Çok Doküman Sürümü Oluşturma - Özelleştirilmiş API Tasarımları

Proje Hedefleri: - Meshery'yi araç olarak kullanarak SMI ve ilgili hizmet ağları için etkileşimli son kullanıcı eğitimleri oluşturmak üzere Google Developer Codelabs'i kullanın. - Hizmet ağları için Jekyll'i kullanarak bir son kullanıcı kılavuzu oluşturun. - SMI için API uç noktası dokümanı oluşturmak üzere Swagger'ı kullanın. - Projeyi topluluk odaklı hale getirin. Böylece, gelecekteki ve mevcut kullanıcılar ya da geliştiriciler, SMI topluluğunun rehberliği ve moderasyonunda projeye kolayca içerik eklemeye devam edebilir.

Zaman çizelgesi: Önerilen zaman çizelgesini burada bulabilirsiniz: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl

Yapı: Kullanıcı kılavuzu için önerilen yapıya buradan ulaşabilirsiniz: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing

Neden bu proje? Hizmet örgüsü topluluğu, kısa süre önce CNCF'ye korumalı alan projesi olarak entegre edilmesi sayesinde son derece hızlı bir şekilde büyüyor. Ancak projede hem son kullanıcılar hem de geliştiriciler için ciddi bir doküman eksikliği yaşanıyor. Geçmişte EmojiVoto uygulamasıyla linkerD, bookinfo uygulamasıyla Istio ve Hashicorp'un Consul'u gibi çeşitli hizmet ağlarıyla oynadım. SMI trafik bölmesini de denedim ve hizmet ağı yapılandırmamda çeşitli doğrulama kuralları uyguladım. Öğrenme süreci ilgi çekici olsa da son derece tekniktir ve hizmet ağı topluluğuna ilk adımlarını atmak veya kendi kişisel ya da profesyonel projeleri için hizmet ağlarını kullanmak isteyen yeni kullanıcıların yanı sıra geliştiriciler için de can sıkıcı olabilir. Bu boşluğu doldurmak istiyorum. Bunun için etkili ve iyi belgelenmiş kılavuz ve eğitici içerikler gerekiyor.