Skip to content

Commit d1f6c73

Browse files
tmctmc
committed
rules_helm: enhance documentation
1 parent e151796 commit d1f6c73

File tree

7 files changed

+291
-22
lines changed

7 files changed

+291
-22
lines changed

‎BUILD

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,31 @@ sh_test(
2424
".dummy_test.sh",
2525
],
2626
)
27+
28+
load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc")
29+
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
30+
31+
# package(default_visibility = ["//visibility:public"])
32+
package(default_visibility = ["//visibility:public"])
33+
34+
load("@bazel_tools//tools/build_defs/pkg:pkg.bzl", "pkg_tar")
35+
36+
bzl_library(
37+
38+
name = "skylib_paths",
39+
srcs = ["@bazel_skylib//lib:paths.bzl"],
40+
)
41+
# bzl_library(
42+
# name = "bazel_tools_pkg",
43+
# srcs = ["@bazel_tools//tools:srcs"],
44+
# )
45+
46+
stardoc(
47+
name = "docs",
48+
out = "docs.md",
49+
input = "helm.bzl",
50+
deps = [
51+
":skylib_paths",
52+
# ":bazel_tools_pkg",
53+
],
54+
)

‎Makefile

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,12 @@ CACHEDIR ?= .cache
66
IMAGE ?= $(shell basename $(shell pwd))
77

88
.PHONY: all
9-
all: ci
9+
all: docs ci
10+
11+
.PHONY: docs
12+
docs: deps
13+
bazel build //:docs && cp bazel-bin/docs.md .
14+
@chmod +w docs.md
1015

1116
.PHONY: deps
1217
ifeq ($(UNAME),Darwin)

‎README.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,65 @@
22

33
This repository contains Bazel rules to install and manipulate Helm charts with Bazel.
44

5+
This allows you to describe Kubernetes applications in a deterministic manner.
6+
7+
## Features
8+
9+
* Tillerless - rules_helm uses [tillerless helm](https://rimusz.net/tillerless-helm/).
10+
11+
## Documentation
12+
13+
* See [Rule and macro defintions](./docs.md) for macro documentation.
14+
15+
## API
16+
17+
* helm_chart - describes a helm chart.
18+
* helm_release - describes a helm release.
19+
20+
21+
## Examples
22+
523
See [rules_helm_examples](https://github.com/tmc/rules_helm_example) for usage examples.
24+
25+
```python
26+
load("@com_github_tmc_rules_helm//:helm.bzl", "helm_release")
27+
28+
package(default_visibility = ["//visibility:public"])
29+
30+
helm_release(
31+
name = "istio_init",
32+
chart = "@com_github_istio_istio//:istio_init",
33+
namespace = "istio-system",
34+
release_name = "istio-init",
35+
values_yaml = ":istio_values.yaml",
36+
)
37+
38+
helm_release(
39+
name = "istio",
40+
chart = "@com_github_istio_istio//:istio",
41+
namespace = "istio-system",
42+
release_name = "istio",
43+
values_yaml = ":istio_values.yaml",
44+
)
45+
```
46+
47+
The releases above create the following targets:
48+
```
49+
:istio_init.test.noclean
50+
:istio_init.test
51+
:istio_init.status
52+
:istio_init.install.wait
53+
:istio_init.install
54+
:istio_init.delete
55+
```
56+
And:
57+
```
58+
:istio.test.noclean
59+
:istio.test
60+
:istio.status
61+
:istio.install.wait
62+
:istio.install
63+
:istio.delete
64+
```
65+
66+
Running `bazel run :istio_init.install` and a subsequent `bazel run :istio.install` (waiting for the CRDs to be created) will install Istio. See [rules_helm_examples](https://github.com/tmc/rules_helm_example) for detailed usage examples.

‎WORKSPACE

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,25 @@
11
workspace(name = "com_github_tmc_rules_helm")
22

3-
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
43
load(":repos.bzl", "helm_repositories")
54

65
helm_repositories()
76

8-
http_file(
9-
name = "buildifier",
10-
executable = True,
11-
sha256 = "25159de982ec8896fc8213499df0a7003dfb4a03dd861f90fa5679d16faf0f99",
12-
urls = ["https://github.com/bazelbuild/buildtools/releases/download/0.22.0/buildifier"],
13-
)
7+
load(":buildifier.bzl", "buildifier_repositories")
8+
buildifier_repositories()
149

15-
http_file(
16-
name = "buildifier_osx",
17-
executable = True,
18-
sha256 = "ceeedbd3ae0479dc2a5161e17adf7eccaba146b650b07063976df58bc37d7c44",
19-
urls = ["https://github.com/bazelbuild/buildtools/releases/download/0.22.0/buildifier.osx"],
10+
# Start stardoc rules
11+
load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
12+
git_repository(
13+
name = "io_bazel_skydoc",
14+
remote = "https://github.com/bazelbuild/skydoc.git",
15+
tag = "0.3.0",
2016
)
17+
load("@io_bazel_skydoc//:setup.bzl", "skydoc_repositories")
18+
skydoc_repositories()
19+
load("@io_bazel_rules_sass//:package.bzl", "rules_sass_dependencies")
20+
rules_sass_dependencies()
21+
load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories")
22+
node_repositories()
23+
load("@io_bazel_rules_sass//:defs.bzl", "sass_repositories")
24+
sass_repositories()
25+
# End stardoc rules

‎buildifier.bzl

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
2+
3+
def buildifier_repositories():
4+
http_file(
5+
name = "buildifier",
6+
executable = True,
7+
sha256 = "25159de982ec8896fc8213499df0a7003dfb4a03dd861f90fa5679d16faf0f99",
8+
urls = ["https://github.com/bazelbuild/buildtools/releases/download/0.22.0/buildifier"],
9+
)
10+
11+
http_file(
12+
name = "buildifier_osx",
13+
executable = True,
14+
sha256 = "ceeedbd3ae0479dc2a5161e17adf7eccaba146b650b07063976df58bc37d7c44",
15+
urls = ["https://github.com/bazelbuild/buildtools/releases/download/0.22.0/buildifier.osx"],
16+
)

‎docs.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
2+
3+
<a name="#helm_chart"></a>
4+
5+
## helm_chart
6+
7+
<pre>
8+
helm_chart(<a href="#helm_chart-name">name</a>, <a href="#helm_chart-srcs">srcs</a>, <a href="#helm_chart-update_deps">update_deps</a>)
9+
</pre>
10+
11+
Defines a helm chart (directory containing a Chart.yaml).
12+
13+
### Parameters
14+
15+
<table class="params-table">
16+
<colgroup>
17+
<col class="col-param" />
18+
<col class="col-description" />
19+
</colgroup>
20+
<tbody>
21+
<tr id="helm_chart-name">
22+
<td><code>name</code></td>
23+
<td>
24+
required.
25+
<p>
26+
A unique name for this rule.
27+
</p>
28+
</td>
29+
</tr>
30+
<tr id="helm_chart-srcs">
31+
<td><code>srcs</code></td>
32+
<td>
33+
required.
34+
<p>
35+
Source files to include as the helm chart. Typically this will just be glob(["**"]).
36+
</p>
37+
</td>
38+
</tr>
39+
<tr id="helm_chart-update_deps">
40+
<td><code>update_deps</code></td>
41+
<td>
42+
optional. default is <code>False</code>
43+
<p>
44+
Whether or not to run a helm dependency update prior to packaging.
45+
</p>
46+
</td>
47+
</tr>
48+
</tbody>
49+
</table>
50+
51+
52+
<a name="#helm_release"></a>
53+
54+
## helm_release
55+
56+
<pre>
57+
helm_release(<a href="#helm_release-name">name</a>, <a href="#helm_release-release_name">release_name</a>, <a href="#helm_release-chart">chart</a>, <a href="#helm_release-values_yaml">values_yaml</a>, <a href="#helm_release-namespace">namespace</a>)
58+
</pre>
59+
60+
Defines a helm release.
61+
62+
A given target has the following executable targets generated:
63+
64+
`(target_name).install`
65+
`(target_name).install.wait`
66+
`(target_name).status`
67+
`(target_name).delete`
68+
`(target_name).test`
69+
`(target_name).test.noclean`
70+
71+
72+
### Parameters
73+
74+
<table class="params-table">
75+
<colgroup>
76+
<col class="col-param" />
77+
<col class="col-description" />
78+
</colgroup>
79+
<tbody>
80+
<tr id="helm_release-name">
81+
<td><code>name</code></td>
82+
<td>
83+
required.
84+
<p>
85+
A unique name for this rule.
86+
</p>
87+
</td>
88+
</tr>
89+
<tr id="helm_release-release_name">
90+
<td><code>release_name</code></td>
91+
<td>
92+
required.
93+
<p>
94+
name of the release.
95+
</p>
96+
</td>
97+
</tr>
98+
<tr id="helm_release-chart">
99+
<td><code>chart</code></td>
100+
<td>
101+
required.
102+
<p>
103+
The chart defined by helm_chart.
104+
</p>
105+
</td>
106+
</tr>
107+
<tr id="helm_release-values_yaml">
108+
<td><code>values_yaml</code></td>
109+
<td>
110+
required.
111+
<p>
112+
The values.yaml file to supply to the release.
113+
</p>
114+
</td>
115+
</tr>
116+
<tr id="helm_release-namespace">
117+
<td><code>namespace</code></td>
118+
<td>
119+
optional. default is <code>""</code>
120+
<p>
121+
The namespace to install the release into. If empty will default the NAMESPACE environment variable and will fall back the the current username (via BUILD_USER).
122+
</p>
123+
</td>
124+
</tr>
125+
</tbody>
126+
</table>
127+
128+

‎helm.bzl

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
load("@bazel_skylib//lib:paths.bzl", "paths")
2-
load("@bazel_tools//tools/build_defs/pkg:pkg.bzl", "pkg_tar")
32

43
HELM_CMD_PREFIX = """
54
echo "#!/bin/bash" > $@
@@ -14,11 +13,20 @@ PATH=\$$(dirname \$$HELM):\$$PATH
1413
"""
1514

1615
def helm_chart(name, srcs, update_deps = False):
16+
"""Defines a helm chart (directory containing a Chart.yaml).
17+
18+
Args:
19+
name: A unique name for this rule.
20+
srcs: Source files to include as the helm chart. Typically this will just be glob(["**"]).
21+
update_deps: Whether or not to run a helm dependency update prior to packaging.
22+
"""
23+
format: The format to write the Rat check report in.
24+
visibility: The visibility of this rule.
1725
filegroup_name = name + "_filegroup"
1826
helm_cmd_name = name + "_package.sh"
1927
package_flags = ""
2028
if update_deps:
21-
package_flags = "-u"
29+
package_flags = "--dependency-update"
2230
native.filegroup(
2331
name = filegroup_name,
2432
srcs = srcs,
@@ -45,7 +53,7 @@ mv *tgz $@
4553
),
4654
)
4755

48-
def helm_cmd(cmd, args, name, helm_cmd_name, values_yaml):
56+
def _helm_cmd(cmd, args, name, helm_cmd_name, values_yaml):
4957
native.sh_binary(
5058
name = name + "." + cmd,
5159
srcs = [helm_cmd_name],
@@ -55,6 +63,24 @@ def helm_cmd(cmd, args, name, helm_cmd_name, values_yaml):
5563
)
5664

5765
def helm_release(name, release_name, chart, values_yaml, namespace = ""):
66+
"""Defines a helm release.
67+
68+
A given target has the following executable targets generated:
69+
70+
`(target_name).install`
71+
`(target_name).install.wait`
72+
`(target_name).status`
73+
`(target_name).delete`
74+
`(target_name).test`
75+
`(target_name).test.noclean`
76+
77+
Args:
78+
name: A unique name for this rule.
79+
release_name: name of the release.
80+
chart: The chart defined by helm_chart.
81+
values_yaml: The values.yaml file to supply to the release.
82+
namespace: The namespace to install the release into. If empty will default the NAMESPACE environment variable and will fall back the the current username (via BUILD_USER).
83+
"""
5884
helm_cmd_name = name + "_run_helm_cmd.sh"
5985
native.genrule(
6086
name = name,
@@ -76,9 +102,9 @@ fi
76102
77103
EOF""",
78104
)
79-
helm_cmd("install", ["upgrade", "--install"], name, helm_cmd_name, values_yaml)
80-
helm_cmd("install.wait", ["upgrade", "--install", "--wait"], name, helm_cmd_name, values_yaml)
81-
helm_cmd("status", ["status"], name, helm_cmd_name, values_yaml)
82-
helm_cmd("delete", ["delete", "--purge"], name, helm_cmd_name, values_yaml)
83-
helm_cmd("test", ["test", "--cleanup"], name, helm_cmd_name, values_yaml)
84-
helm_cmd("test.noclean", ["test"], name, helm_cmd_name, values_yaml)
105+
_helm_cmd("install", ["upgrade", "--install"], name, helm_cmd_name, values_yaml)
106+
_helm_cmd("install.wait", ["upgrade", "--install", "--wait"], name, helm_cmd_name, values_yaml)
107+
_helm_cmd("status", ["status"], name, helm_cmd_name, values_yaml)
108+
_helm_cmd("delete", ["delete", "--purge"], name, helm_cmd_name, values_yaml)
109+
_helm_cmd("test", ["test", "--cleanup"], name, helm_cmd_name, values_yaml)
110+
_helm_cmd("test.noclean", ["test"], name, helm_cmd_name, values_yaml)

0 commit comments

Comments
 (0)