Обзор
Помимо Helm-шаблонов, werf поддерживает генерацию Kubernetes-манифестов с помощью TypeScript. Helm-шаблоны и TypeScript-шаблоны могут сосуществовать в одном чарте — полученные манифесты объединяются в единый мульти-документный YAML.
TypeScript-шаблоны рендерятся с помощью Node.js: для развёртывания чарта с директорией ts/ на хосте должны быть установлены Node.js 26 или новее и менеджер пакетов (npm, pnpm или yarn).
Зачем TypeScript
Язык шаблонов Helm хорошо работает для простых случаев, но с ростом сложности чарта становится сложным в поддержке: примитивный язык с большим количеством подводных камней, ограниченная стандартная библиотека, проблемы с производительностью, сложная отладка, слабая поддержка в IDE и редакторах. TypeScript в werf решает эти проблемы, не усложняя процесс развёртывания.
Возможности
- Поддержка IDE — автокомплит, проверка типов, go-to-definition и рефакторинг в любом редакторе с поддержкой TypeScript (VS Code, JetBrains, Neovim и др.).
- Стандартный синтаксис — обычные функции, циклы и условия вместо неудобных конструкций шаблонизатора.
- Чистый TypeScript — директория
tsявляется обычным TypeScript-проектом для Node.js и может рендериться без werf с помощьюnpm run dev. - Большая экосистема — TypeScript один из самых популярных языков с обширной документацией, ресурсами сообщества и инструментарием.
- Возможность использовать практически любую стороннюю TypeScript/JavaScript-библиотеку, например kubernetes-models, cdk8s или любую другую из экосистемы npm.
- Тестирование — тестируйте код с помощью привычных TypeScript-библиотек и инструментов.
- Изолированные окружения — модули npm по умолчанию включаются в бандл чарта, так что во время развёртывания не будет сетевых обращений, кроме обращений к самому Kubernetes.
- Безопасность — код выполняется в рамках модели разрешений Node.js без доступа к сети, переменным окружения и запуску процессов. Доступ к файловой системе ограничен чтением файлов чарта.
Быстрый старт
Инициализация TypeScript-файлов в существующем чарте:
werf chart ts init
Команда создаст директорию .helm/ts/ с готовым скелетом TypeScript-проекта и несколькими файлами с примерами ресурсов. Попробуйте отредактировать ts/src/deployment.ts — например, изменить количество реплик — и проверьте результат:
werf render --dev
Для развёртывания:
werf converge --dev
Структура чарта
ts/node_modules/
ts/.dev/
ts/.pnp.*
ts/.yarn/cache/
ts/.yarn/unplugged/
ts/.yarn/__virtual__/
ts/.yarn/install-state.gz
ts/.yarn/build-state.yml
# Patterns to ignore when building packages.
# This supports shell glob matching, relative path matching, and
# negation (prefixed with !). Only one pattern per line.
# TypeScript chart files
ts/node_modules/
ts/.dev/
ts/.pnp.*
ts/.yarn/cache/
ts/.yarn/unplugged/
ts/.yarn/__virtual__/
ts/.yarn/install-state.gz
ts/.yarn/build-state.yml
apiVersion: v2
name: ts-chart-example
version: 0.1.0
Capabilities:
APIVersions:
- v1
HelmVersion:
go_version: go1.25.0
version: v3.20
KubeVersion:
Major: "1"
Minor: "35"
Version: v1.35.0
Chart:
APIVersion: v2
Annotations:
anno: value
AppVersion: 1.0.0
Condition: ts-chart-example.enabled
Description: ts-chart-example description
Home: https://example.org/home
Icon: https://example.org/icon
Keywords:
- ts-chart-example
Maintainers:
- Email: john@example.com
Name: john
URL: https://example.com/john
Name: ts-chart-example
Sources:
- https://example.org/ts-chart-example
Tags: ts-chart-example
Type: application
Version: 0.1.0
Files:
myfile: "content"
Release:
IsInstall: false
IsUpgrade: true
Name: ts-chart-example
Namespace: ts-chart-example
Revision: 2
Service: Helm
Values:
global:
werf:
name: myapp
version: v3.6.1
repo: example.org/mycompany/myapp
env: production
images:
app:
registry: example.org
namespace: mycompany
name: myapp
tag: a1b2c3d4-1234567890
digest: "sha256:abcdef1234567890"
tag_digest: "a1b2c3d4-1234567890@sha256:abcdef1234567890"
image: example.org/mycompany/myapp
repository: mycompany/myapp
ref: "example.org/mycompany/myapp:a1b2c3d4-1234567890@sha256:abcdef1234567890"
ref_tag: "example.org/mycompany/myapp:a1b2c3d4-1234567890"
repository_ref: "mycompany/myapp:a1b2c3d4-1234567890@sha256:abcdef1234567890"
repository_tag: "mycompany/myapp:a1b2c3d4-1234567890"
name_ref: "myapp:a1b2c3d4-1234567890@sha256:abcdef1234567890"
name_tag: "myapp:a1b2c3d4-1234567890"
commit:
date:
human: "2025-01-15 12:00:00 +0000"
unix: 1736942400
hash: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
image:
repository: nginx
tag: latest
replicaCount: 1
service:
enabled: true
port: 80
type: ClusterIP
{
"name": "ts-chart-example-ts",
"version": "0.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "ts-chart-example-ts",
"version": "0.0.0",
"dependencies": {
"@nelm/chart-ts-sdk": "^0.2.0"
},
"devDependencies": {
"typescript": "~6.0.3"
}
},
"node_modules/@esbuild/aix-ppc64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
"integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
"cpu": [
"ppc64"
],
"license": "MIT",
"optional": true,
"os": [
"aix"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-arm": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
"integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
"cpu": [
"arm"
],
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
"integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
"cpu": [
"arm64"
],
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
"integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
"cpu": [
"x64"
],
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/darwin-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
"integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
"cpu": [
"arm64"
],
"license": "MIT",
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/darwin-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
"integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
"cpu": [
"x64"
],
"license": "MIT",
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/freebsd-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
"integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
"cpu": [
"arm64"
],
"license": "MIT",
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/freebsd-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
"integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
"cpu": [
"x64"
],
"license": "MIT",
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-arm": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
"integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
"cpu": [
"arm"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
"integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
"cpu": [
"arm64"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-ia32": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
"integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
"cpu": [
"ia32"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-loong64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
"integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
"cpu": [
"loong64"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-mips64el": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
"integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
"cpu": [
"mips64el"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-ppc64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
"integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
"cpu": [
"ppc64"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-riscv64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
"integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
"cpu": [
"riscv64"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-s390x": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
"integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
"cpu": [
"s390x"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
"integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
"cpu": [
"x64"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/netbsd-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
"integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
"cpu": [
"arm64"
],
"license": "MIT",
"optional": true,
"os": [
"netbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/netbsd-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
"integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
"cpu": [
"x64"
],
"license": "MIT",
"optional": true,
"os": [
"netbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openbsd-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
"integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
"cpu": [
"arm64"
],
"license": "MIT",
"optional": true,
"os": [
"openbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openbsd-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
"integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
"cpu": [
"x64"
],
"license": "MIT",
"optional": true,
"os": [
"openbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openharmony-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
"integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
"cpu": [
"arm64"
],
"license": "MIT",
"optional": true,
"os": [
"openharmony"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/sunos-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
"integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
"cpu": [
"x64"
],
"license": "MIT",
"optional": true,
"os": [
"sunos"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
"integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
"cpu": [
"arm64"
],
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-ia32": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
"integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
"cpu": [
"ia32"
],
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
"integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
"cpu": [
"x64"
],
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@nelm/chart-ts-sdk": {
"version": "0.2.0",
"resolved": "https://registry.npmjs.org/@nelm/chart-ts-sdk/-/chart-ts-sdk-0.2.0.tgz",
"integrity": "sha512-BpV2RppfbBjK6gqsAxg4aZcmeNEwSg3cc1p6J7ca320B6y/a0a0gA6Y6R8b8a9/wAZq8zxAGcuKc9n1WSKl/EQ==",
"license": "Apache-2.0",
"dependencies": {
"esbuild": "0.28.2",
"js-yaml": "^5.5.0"
},
"bin": {
"nelm-chart-ts": "dist/cli.js"
},
"engines": {
"node": ">=26"
}
},
"node_modules/argparse": {
"version": "3.0.4",
"resolved": "https://registry.npmjs.org/argparse/-/argparse-3.0.4.tgz",
"integrity": "sha512-fwWK3Zq22l4XJJjx5mcBHGikIk+hJqO+32dPm0Jur7+rtG5x1scOjSfdT9ZKeWHPpsya/l0HHK4tDImBkTrtvA==",
"funding": [
{
"type": "github",
"url": "https://github.com/sponsors/puzrin"
},
{
"type": "github",
"url": "https://github.com/sponsors/nodeca"
}
],
"license": "PSF-2.0"
},
"node_modules/esbuild": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
"integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
"hasInstallScript": true,
"license": "MIT",
"bin": {
"esbuild": "bin/esbuild"
},
"engines": {
"node": ">=18"
},
"optionalDependencies": {
"@esbuild/aix-ppc64": "0.28.2",
"@esbuild/android-arm": "0.28.2",
"@esbuild/android-arm64": "0.28.2",
"@esbuild/android-x64": "0.28.2",
"@esbuild/darwin-arm64": "0.28.2",
"@esbuild/darwin-x64": "0.28.2",
"@esbuild/freebsd-arm64": "0.28.2",
"@esbuild/freebsd-x64": "0.28.2",
"@esbuild/linux-arm": "0.28.2",
"@esbuild/linux-arm64": "0.28.2",
"@esbuild/linux-ia32": "0.28.2",
"@esbuild/linux-loong64": "0.28.2",
"@esbuild/linux-mips64el": "0.28.2",
"@esbuild/linux-ppc64": "0.28.2",
"@esbuild/linux-riscv64": "0.28.2",
"@esbuild/linux-s390x": "0.28.2",
"@esbuild/linux-x64": "0.28.2",
"@esbuild/netbsd-arm64": "0.28.2",
"@esbuild/netbsd-x64": "0.28.2",
"@esbuild/openbsd-arm64": "0.28.2",
"@esbuild/openbsd-x64": "0.28.2",
"@esbuild/openharmony-arm64": "0.28.2",
"@esbuild/sunos-x64": "0.28.2",
"@esbuild/win32-arm64": "0.28.2",
"@esbuild/win32-ia32": "0.28.2",
"@esbuild/win32-x64": "0.28.2"
}
},
"node_modules/js-yaml": {
"version": "5.5.0",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-5.5.0.tgz",
"integrity": "sha512-paNr4LFIFPjeeSmwNYdrb8FafLLG/Cr2Af3GjbsHJ5CxIjH4r0c2emlmRdAtpPAieP1gRVzk6buBbVP5gBMGAg==",
"funding": [
{
"type": "github",
"url": "https://github.com/sponsors/puzrin"
},
{
"type": "github",
"url": "https://github.com/sponsors/nodeca"
}
],
"license": "MIT",
"dependencies": {
"argparse": "^3.0.3"
},
"bin": {
"js-yaml": "bin/js-yaml.mjs"
}
},
"node_modules/typescript": {
"version": "6.0.3",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
"integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
"dev": true,
"license": "Apache-2.0",
"bin": {
"tsc": "bin/tsc",
"tsserver": "bin/tsserver"
},
"engines": {
"node": ">=14.17"
}
}
}
}
{
"name": "ts-chart-example-ts",
"version": "0.0.0",
"type": "module",
"private": true,
"scripts": {
"dev": "nelm-chart-ts dev --input-file input.example.yaml",
"typecheck": "tsc"
},
"dependencies": {
"@nelm/chart-ts-sdk": "^0.2.0"
},
"devDependencies": {
"typescript": "~6.0.3"
}
}
import type { WerfRenderContext } from '@nelm/chart-ts-sdk';
import { getFullname, getLabels, getSelectorLabels } from './helpers.ts';
export function newDeployment($: WerfRenderContext): object {
const name = getFullname($);
return {
apiVersion: 'apps/v1',
kind: 'Deployment',
metadata: {
name,
labels: getLabels($),
},
spec: {
replicas: $.Values.replicaCount ?? 1,
selector: {
matchLabels: getSelectorLabels($),
},
template: {
metadata: {
labels: getSelectorLabels($),
},
spec: {
containers: [
{
name: name,
image: ($.Values.image?.repository ?? 'nginx') + ':' + ($.Values.image?.tag ?? 'latest'),
ports: [
{
name: 'http',
containerPort: $.Values.service?.port ?? 80,
},
],
},
],
},
},
},
};
}
import type { WerfRenderContext } from '@nelm/chart-ts-sdk';
/**
* Truncate string to max length, removing trailing hyphens.
*/
export function trunc(str: string, max: number): string {
if (str.length <= max) return str;
return str.slice(0, max).replace(/-+$/, '');
}
/**
* Get the fully qualified app name.
* Truncated at 63 chars (DNS naming spec limit).
*/
export function getFullname($: WerfRenderContext): string {
if ($.Values.fullnameOverride) {
return trunc($.Values.fullnameOverride, 63);
}
const chartName = $.Values.nameOverride || $.Chart.Name;
if ($.Release.Name.includes(chartName)) {
return trunc($.Release.Name, 63);
}
return trunc(`${$.Release.Name}-${chartName}`, 63);
}
export function getLabels($: WerfRenderContext): Record<string, string> {
return {
'app.kubernetes.io/name': $.Chart.Name,
'app.kubernetes.io/instance': $.Release.Name,
};
}
export function getSelectorLabels($: WerfRenderContext): Record<string, string> {
return {
'app.kubernetes.io/name': $.Chart.Name,
'app.kubernetes.io/instance': $.Release.Name,
};
}
import { type WerfRenderContext, type RenderResult, render } from '@nelm/chart-ts-sdk';
import { newDeployment } from './deployment.ts';
import { newService } from './service.ts';
function generate($: WerfRenderContext): RenderResult {
const manifests: object[] = [];
manifests.push(newDeployment($));
if ($.Values.service?.enabled !== false) {
manifests.push(newService($));
}
return { manifests };
}
await render(generate);
import type { WerfRenderContext } from '@nelm/chart-ts-sdk';
import { getFullname, getLabels, getSelectorLabels } from './helpers.ts';
export function newService($: WerfRenderContext): object {
return {
apiVersion: 'v1',
kind: 'Service',
metadata: {
name: getFullname($),
labels: getLabels($),
},
spec: {
type: $.Values.service?.type ?? 'ClusterIP',
ports: [
{
port: $.Values.service?.port ?? 80,
targetPort: 'http',
},
],
selector: getSelectorLabels($),
},
};
}
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"noEmit": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"strict": true,
"skipLibCheck": true,
"types": []
},
"include": ["src"]
}
replicaCount: 1
image:
repository: nginx
tag: latest
service:
enabled: true
type: ClusterIP
port: 80
Разработка чарта с TypeScript-шаблонами
Установите Node.js 26 или новее и настройте поддержку TypeScript в вашей IDE или редакторе (VS Code, JetBrains, Neovim и др.).
Инициализируйте TypeScript-файлы в чарте, если они ещё не инициализированы:
werf chart ts init
Откройте директорию ts/ в редакторе как обычный TypeScript-проект для Node.js. Работайте с ним так же, как с любой TypeScript-кодовой базой — запускайте скрипты, пишите тесты, используйте отладчик.
Структуру кодовой базы можно организовать по своему усмотрению. Единственное требование — файл ts/src/index.ts должен существовать, и функция render из @nelm/chart-ts-sdk обязательно должна быть вызвана. Иначе рендеринг TypeScript не произойдёт.
Для отладки рендеринга шаблонов в окружении, максимально близком к тому, как werf запускает Node.js, используйте скрипт dev из ts/package.json:
cd .helm/ts
npm run dev
TypeScript-движок вызовет функцию render из ts/src/index.ts с примером контекста из ts/input.example.yaml. Полученный YAML будет выведен в консоль после сообщения Rendered manifests:.
Устанавливайте библиотеки с помощью npm install, например попробуйте установить kubernetes-models — библиотеку для строгой типизации Kubernetes-ресурсов:
npm install kubernetes-models
Зависимость добавится в package.json автоматически. Теперь можно импортировать и использовать её:
// .helm/ts/src/deployment.ts:
import { Deployment } from 'kubernetes-models/apps/v1';
export function newDeployment($: WerfRenderContext): object {
return new Deployment({
metadata: { name: 'myapp' },
spec: {
// other fields
},
}).toJSON();
}
Чтобы убедиться, что всё работает при рендеринге в werf, выполните:
werf lint --dev
werf render --dev
Как развернуть чарт с TypeScript-шаблонами
Просто запустите werf converge: TypeScript-шаблоны будут отрендерены с помощью Node.js и развёрнуты.
Обратите внимание: Согласно политикам гиттерминизма, все изменённые файлы должны быть закоммичены.
Развёртывание в изолированных окружениях
В изолированном окружении достаточно, чтобы на целевой машине был установлен Node.js, а сам чарт был самодостаточным:
- Опубликуйте чарт:
werf bundle publish --repo example.org/mycompany/myappВсе модули npm будут минифицированы и включены в бандл, так что чарт можно установить даже без доступа к интернету.
- На целевой машине в изолированном окружении (без доступа к сети) выполните:
werf bundle apply --repo example.org/mycompany/myappTypeScript-шаблоны будут отрендерены и развёрнуты с использованием предварительно скомпилированных файлов из бандла чарта.
Чтобы изменить такой чарт и упаковать его снова без доступа к сети, передайте nelm chart pack опцию --ts-no-rebuild: она использует предварительно скомпилированные файлы вместо пересборки, см. Изменение опубликованного чарта. Helm, Argo CD и Flux не выполняют TypeScript-шаблоны, поэтому не развёртывают генерируемые ими ресурсы.
Обзор SDK API
TypeScript-движок использует пакет @nelm/chart-ts-sdk.
Функции “render” и “generate”
index.ts обязан вызвать функцию render(). Функция generate(), которая непосредственно генерирует манифесты, должна быть передана в render() в качестве аргумента, например:
// .helm/ts/src/index.ts:
await render(generate);
Объект “WerfRenderContext”
Функция generate получает корневой контекст в переменной $ типа WerfRenderContext — тот же контекст, что и в Helm-шаблонах:
| Поле | Тип | Описание |
|---|---|---|
$.Values |
WerfServiceValues |
Параметры чарта + сервисные значения в $.Values.global.werf |
$.Release |
Release |
Информация о релизе |
$.Chart |
ChartMetadata |
Метаданные из Chart.yaml |
$.Capabilities |
Capabilities |
Возможности кластера (API-версии, версия Kubernetes) |
$.Files |
Record<string, Uint8Array> |
Исходные файлы чарта (кроме templates/ и ts/) |
Пример контекста — в файле ts/input.example.yaml. Подробнее о параметрах и их формировании — в разделе Параметризация шаблонов.
Объект “RenderResult”
Функция generate возвращает RenderResult — объект с массивом manifests. Каждый элемент — обычный JavaScript-объект, представляющий Kubernetes-ресурс. Пример вывода:
{
"manifests": [
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": { "name": "myapp" },
"spec": { "..." }
},
{
"apiVersion": "v1",
"kind": "Service",
"metadata": { "name": "myapp" },
"spec": { "..." }
}
]
}
Каждый объект сериализуется в YAML и включается в итоговый результат рендеринга.