मान (Values)

यह सर्वोत्तम प्रक्रियाओं मार्गदर्शिका (Best Practices Guide) का वह भाग है जो मानों (values) के उपयोग को कवर करता है।
इस अनुभाग में, हम यह अनुशंसा प्रदान करते हैं कि आपको अपने मानों की संरचना और उपयोग कैसे करना चाहिए,
जिसमें विशेष रूप से किसी चार्ट की values.yaml फ़ाइल को डिज़ाइन करने पर ध्यान केंद्रित किया गया है।

नामकरण संधियाँ (Naming Conventions)

वेरिएबल (variable) के नाम छोटे अक्षर (lowercase letter) से शुरू होने चाहिए, और शब्दों को camelCase में अलग किया जाना चाहिए:

सही:

chicken: true
chickenNoodleSoup: true

गलत:

Chicken: true # प्रारंभिक बड़े अक्षर (initial caps) अंतर्निहित (built-in) नामों से टकरा सकते हैं
chicken-noodle-soup: true # नाम में हाइफ़न (hyphen) का उपयोग न करें

ध्यान दें कि Helm के सभी अंतर्निहित (built-in) वेरिएबल्स बड़े अक्षर (uppercase letter) से शुरू होते हैं,
ताकि उन्हें उपयोगकर्ता-परिभाषित (user-defined) मानों से आसानी से अलग किया जा सके:

उदाहरण: .Release.Name, .Capabilities.KubeVersion।

समतल (Flat) या नेस्टेड (Nested) मान

YAML एक लचीला प्रारूप (flexible format) है, और मानों (values) को गहराई से नेस्ट किया जा सकता है या समतल रखा जा सकता है।

नेस्टेड (Nested):

server:
  name: nginx
  port: 80

इस संरचना में, server शीर्ष-स्तरीय कुंजी है, और इसके अंतर्गत name और port नेस्टेड (अंदर मौजूद) हैं।

समतल (Flat):

serverName: nginx
serverPort: 80

इस संरचना में, सभी कुंजियाँ शीर्ष स्तर (top-level) पर हैं और नेस्टेड नहीं हैं।

अधिकांश मामलों में, समतल (Flat) संरचना को नेस्टेड (Nested) संरचना की तुलना में प्राथमिकता देनी चाहिए।
इसका कारण यह है कि यह टेम्प्लेट डेवलपर्स और उपयोगकर्ताओं के लिए अधिक सरल होती है।

सुरक्षा के लिए, नेस्टेड मानों की प्रत्येक स्तर पर जाँच आवश्यक होती है:

{{ if .Values.server }}
  {{ default "none" .Values.server.name }}
{{ end }}

हर नेस्टिंग स्तर (layer) के लिए, अस्तित्व (existence) की जाँच करनी आवश्यक होती है।
लेकिन समतल (Flat) संरचना में, ऐसी जाँचों को छोड़ा जा सकता है, जिससे टेम्प्लेट पढ़ना और उपयोग करना आसान हो जाता है।

{{ default "none" .Values.serverName }}

जब कई संबंधित वेरिएबल्स (variables) हों और उनमें से कम से कम एक अनिवार्य (non-optional) हो,
तो पठनीयता (readability) में सुधार करने के लिए नेस्टेड (Nested) मानों का उपयोग किया जा सकता है।

प्रकार (Types) को स्पष्ट करें

YAML के प्रकार अनुकूलन (type coercion) नियम कभी-कभी अप्रत्याशित होते हैं।
उदाहरण के लिए, foo: false और foo: "false" समान नहीं होते हैं।
कुछ मामलों में, बड़े पूर्णांक (integers) जैसे foo: 12345678 वैज्ञानिक संकेतन (scientific notation) में परिवर्तित हो सकते हैं।

प्रकार रूपांतरण (type conversion) त्रुटियों से बचने का सबसे आसान तरीका यह है कि:

स्ट्रिंग्स (strings) को स्पष्ट रूप से उद्धरण (quotes) में लिखें।
अन्य सभी प्रकारों को सामान्य रूप में छोड़ दें।

संक्षेप में कहा जाए तो, "सभी स्ट्रिंग्स को उद्धरणों में रखें।"

अक्सर, पूर्णांक (integers) से संबंधित समस्याओं से बचने के लिए, उन्हें स्ट्रिंग के रूप में संग्रहीत करना फायदेमंद होता है।
बाद में, टेम्प्लेट में {{ int $value }} का उपयोग करके उन्हें फिर से पूर्णांक में बदला जा सकता है।

अधिकांश मामलों में, स्पष्ट प्रकार टैग (explicit type tags) का सम्मान किया जाता है,
इसलिए foo: !!string 1234 को 1234 एक स्ट्रिंग के रूप में माना जाएगा।

हालांकि, YAML पार्सर (parser) टैग को खपत (consume) कर लेता है,
जिसके कारण एक बार पार्स (parse) करने के बाद प्रकार संबंधी डेटा खो सकता है।

इस बात पर विचार करें कि उपयोगकर्ता आपके मानों (Values) का उपयोग कैसे करेंगे

मानों के तीन संभावित स्रोत होते हैं:

किसी चार्ट की values.yaml फ़ाइल
helm install -f या helm upgrade -f द्वारा प्रदान की गई मान फ़ाइल
helm install या helm upgrade पर --set या --set-string फ्लैग द्वारा दिए गए मान

जब आप अपने मानों की संरचना डिज़ाइन कर रहे हों, तो ध्यान रखें कि
आपके चार्ट के उपयोगकर्ता या तो -f फ्लैग का उपयोग करके या --set विकल्प के माध्यम से उन्हें ओवरराइड करना चाह सकते हैं।

चूंकि --set अभिव्यक्ति (expressiveness) में अधिक सीमित है,
इसलिए values.yaml फ़ाइल लिखने का पहला नियम यह है कि इसे --set से आसानी से ओवरराइड किया जा सके।

इसी कारण, अपने मान फ़ाइल की संरचना को मैप्स (maps) के रूप में रखना अक्सर बेहतर होता है।

--set के साथ उपयोग करने में कठिन:

servers:
  - name: foo
    port: 80
  - name: bar
    port: 81

उपरोक्त संरचना को Helm <=2.4 में --set के साथ व्यक्त नहीं किया जा सकता।
Helm 2.5 में, foo पर पोर्ट तक पहुँचने के लिए --set servers[0].port=80 का उपयोग किया जाता है।

यह न केवल उपयोगकर्ताओं के लिए समझना कठिन है, बल्कि यदि बाद में servers की क्रमबद्धता (order) बदल जाती है,
तो यह त्रुटियों (errors) की संभावना भी बढ़ा देता है।

उपयोग में आसान:

servers:
  foo:
    port: 80
  bar:
    port: 81

foo के पोर्ट तक पहुँचना कहीं अधिक स्पष्ट है।: --set servers.foo.port=80

`values.yaml` का दस्तावेज़ीकरण करें

values.yaml में परिभाषित प्रत्येक प्रॉपर्टी का दस्तावेज़ीकरण किया जाना चाहिए।
डॉक्यूमेंटेशन स्ट्रिंग को उस प्रॉपर्टी के नाम से शुरू होना चाहिए जिसे यह वर्णित कर रही है,
और फिर कम से कम एक वाक्य में उसका विवरण देना चाहिए।