Англійська для розробників Terraform Modules

Писання і підтримка модулів Terraform, які можна використовувати повторно, є відмінною вмінням від простого застосування інфраструктури як коду, і вона має свій власний словник навколо інтерфейсів, версій і композиції. Коли ви публікуєте модуль для використання іншими командами, переглядаєте запит на витягнення, який змінює вхідні дані модуля, або пояснюєте зміну у журналі змін, точна англійська мова має таке ж значення, як і сам код. Цей посібник зосереджено на термінології, яку використовують під час створення і версування модулів Terraform, а не на інфраструктурі як коді загалом.

Ключовий словник

** Вхідна змінна ** — параметр, який модуль приймає від будь- кого, хто його викликає, що дозволяє налаштовувати один і той же модуль по- різному у різних середовищах.

• “Ми додали змінну вводу для instance_ type, щоб виклики могли вибирати свій власний розмір замість його твердого кодування.” *

** Значення виводу ** — дані, які модуль показує викликаючому після створення ресурсів, зазвичай використовується для передачі інформації, наприклад, ідентифікаторів ресурсів, іншим модулям. “Модул виставляє ідентифікатор VPC як вихідне значення, щоб модулі нижнього рівня могли посилатися на нього.”

** Реєстр модулів ** — центральний каталог, публічний або приватний, де опубліковано версії модулів Terraform і де вони знаходяться для повторного використання. “Ми опублікували модуль мережі в нашому приватному реєстрі, щоб кожна команда отримувала одне і те ж джерело правди.”

** Семантичне версування ** — схема версування (major. minor. patch), яка сигналізує, чи містить випуск модуля зміни, нові можливості або виправлення помилок.

• “Відновлення головної версії було необхідним, оскільки ми перейменували необхідну змінну вводу, що є зміною, що порушує правила.” *

** Модульна композиція ** — практика створення більших конфігурацій інфраструктури за допомогою поєднання менших, фокусованих модулів, а не одного монолітного модуля.

• “За допомогою складання модулів, наша коренева конфігурація просто з’ єднує мережу, базу даних і обчислювальні модулі.” *

** Коріньовий модуль ** — це налаштування Terraform верхнього рівня, яке користувач запускає безпосередньо, зазвичай, викликаючи один або декілька дочірніх модулів.

• “Кореневий модуль сам по собі не визначає жодних ресурсів, він просто складається з трьох дочірніх модулів.” *

** Provider requirement ** — декларація всередині модуля, у якій вказано, від яких постачальників і версій вони залежать. “Ми прикріпили вимогу провайдера, щоб уникнути зміни з майбутнього випуску провайдера AWS.”

** Джерело модуля ** — адреса, з якої Terraform завантажує модуль, це може бути локальний шлях, сховище Git або адреса реєстру. “Оновити джерела модулів, щоб вони вказували на випуск з мітками замість головної гілки, щоб збирання залишалися відтворюваними.”

Звичайні фрази

• «Це різка зміна, тому нам потрібно перевірити основну версію перед публікацією»
• «Давайте прикріпимо джерело модуля до тег замість main, щоб середовища не дрейфували»
• Чи можемо ми виставити це як вихідне значення замість того, щоб твердо кодувати його вниз по течії?»
• «Інтерфейс стає надмірно великим, ми повинні розділити його на два менші модулі»
• Чи ми оновили вимоги постачальника після останнього оновлення?»
• «Ця змінна повинна мати розумне за замовчуванням, тому більшість викликаючих не потрібно встановлювати її.»

Приклади висловлювань

При поясненні модулів Terraform нетехнічним користувачам: “Модулі дозволяють нашій команді з інфраструктури пакувати стандартний, перевірений спосіб налаштування таких речей, як бази даних або мережі, так що кожен проект використовує один і той же надійний шаблон, замість того, щоб кожен збирав його з нуля.”

Під час створення квитка підтримки:

• “Після оновлення мережевого модуля з v2. 3. 0 до v3. 0. 0, наш план зазнав невдачі, оскільки виводу subnet_ ids більше не існує. Чи було це перейменовано, і чи є посібник з міграції для випуску v3? ”*

Під час обговорення архітектури на груповій нараді: “Я пропоную витягнути налаштування бази даних у власний модуль з чітко визначеними вхідними змінними і вихідними, щоб інші команди могли використовувати його через реєстр замість копіювання наших файлів Terraform.”

Професійні поради

• Завжди описуйте зміни модулів з точки зору ** семантичного версування ** - скажіть “це незначне видання, повністю зворотньо сумісне”, а не нечітке “невелике оновлення”, оскільки споживачі покладаються на цей сигнал, щоб вирішити, чи оновити негайно.
• Під час перегляду інтерфейсу модуля, спочатку зосередьтеся на ** вхідних змінних ** і ** вихідних значеннях ** — вони формують публічний контракт модуля, тоді як внутрішні назви ресурсів є деталями реалізації.
• Використовуйте « ** pin the module source ** », коли радите колегам по команді посилатися на точну версію або мітку Git, а не на гілку, оскільки це стандартна фраза для уникнення непереглянутого дрейфу.
• Проясніть, чи йдеться про кореневий модуль або про дочірній модуль на початку розмови — заплутаність двох рівнів складання є поширеним джерелом нерозуміння під час перегляду коду.

Практичні вправи

1. Один з членів команди хоче опублікувати новий модуль Terraform і запитує, як визначити номер першої версії. Напишіть від двох до трьох речень, у яких ви поясните семантику версій у цьому контексті.
2. Поясніть у одному реченні різницю між вхідною змінною і вихідним значенням.
3. Видає короткий чернетковий запис журналу змін, який повідомляє про зміну версії, спричинену перейменуванням обов’ язкової змінної.

Національна мова: мова, що використовується для спілкування населення

Як не рідною мовою англійською, створення чіткого і ефективного спілкування навколо інфраструктури як коду - особливо модулів Terraform - може відчувати себе особливо складно. Це не просто про те, щоб отримати синтаксис правильно; це про передачу намірів, нюансів і очікувань таким чином, що резонує з колегами, які можуть розвинути вкорінені звички вираження. Одна з поширених областей, де виникають нерозуміння, це в циклах зворотнього зв’язку під час перегляду коду або при обговоренні дизайну модуля. Давайте розглянемо, як підходити до цих ситуацій проактивно, зосереджуючись на ясності і точності, а не просто перекладаючи безпосередньо з вашої рідної мови.

Часто ви отримуєте коментар на зразок: « Ця змінна потребує типового значення ». Хоча буквальний переклад може бути простим, * наслідком * часто є те, що змінна не має достатньо самодокументації або її відсутність спричиняє неоднозначність. Краще відповідь – і така, що демонструє професіоналізм – була б: «Я ціную відгук. Чи можете ви розібратися, які конкретні проблеми виникають, коли цю змінну не вказано? Знання контексту потенційного режиму невдачі допоможе мені визначити, чи є типове значення дійсно необхідним, або ж чи достатньо буде більш чіткого підходу до документації/ перевірки. » Зауважте зміну фокусу; мова йде не лише про те, що слід змінити, а про те, чому слід змінити. Це демонструє, що ви активно слухаєте і намагаєтеся зрозуміти їхні проблеми. Аналогічно, під час написання PR- описів для випусків модулів, уникайте надто довгих пояснень. Замість « Цей модуль тепер підтримує … » спробуйте « Це видання вводить [спеціальну можливість] для покращення [вигоди], вирішення [проблеми]. »

Інша тонка відмінність полягає у формулюваннях, пов’язаних з залежностями і відносинами всередині модулів. Використання таких термінів, як «вгору» або «вниз» може бути заплутаним на початку. Часто простіше просто сказати: « Модуль залежить від aws-ec2 провайдера для створення прикладу ». Сфокусування на * тому, на що * покладається, а не на абстрактних концепціях, значно зменшує неоднозначність. Пам’ятайте, перегляд коду не тільки про ідентифікацію помилок; вони про встановлення спільного розуміння архітектури системи і сприяння підтримці.

І, нарешті, не вагайтеся попросити про пояснення, якщо щось не відразу зрозуміло. Запитання на кшталт: «Чи можете ви пояснити ваші міркування за цим вибором?» або «Чи можете ви провести мене потоком даних в цьому модулі?» демонструє інтелектуальну цікавість і прихильність до навчання. Краще визнати, що ви впали в хаос, ніж робити припущення.

terraform plan -var="instance_type=t3.micro"

Ця проста команда, яку використовують під час планування, є прикладом точної мови, яку ми обговорюємо: вказування точного значення для вхідної змінної — instance_type у цьому випадку — і перегляд змін, які Terraform планує зробити. Зрозуміння цих нюансів не лише покращить ваше спілкування, але й зміцнить ваш внесок у спільне середовище розробки.