17 | index
18 | About
19 | Who is this?
20 | I'm Jeroen Op 't Eynde, a software engineer at Grafana
21 | Labs and a maintainer on Tanka and the
22 | jsonnet-libs/k8s project.
23 | This course is the result countless hours of researching and debating with Malcolm
24 | Holmes, Tom Braack and many
25 | colleagues and community members on how to maintain and write more effective Jsonnet.
26 | What are the lessons we've learned after using Jsonnet for years?
27 | Grafana Labs uses a mixture of Terraform (HCL) and Jsonnet to configure the Cloud
28 | infrastructure and applications on Kubernetes. While new hires are often familiar with
29 | Terraform, they might never have heard of Jsonnet. This made that question the top voted
30 | topic for training sessions by new hires at Grafana Labs.
31 | While a training session can cover the basics or highlights in ~30min, there is much more
32 | to it. We usually point out to the excellent tutorials on
33 | jsonnet.org to get started, these explain
34 | very well how Jsonnet works but not necessarily how to work with Jsonnet. This course
35 | attempts to cover the idioms we've been adopting over years of discovering.
36 | Why did we pick Jsonnet?
37 | With the acquisition of Kausal by Grafana Labs early 2018, we also adopted Ksonnet,
38 | laying down the base for configuration management with Jsonnet. In addition to the
39 | language comparison on jsonnet.org,
40 | there are a few other advantages.
41 | The most common tool to manage Kubernetes manifests today is Helm, so why not use that? By
42 | templating the YAML, Helm only allows for one level of abstraction (values.yaml), anything
43 | beyond that requires a change request upstream or more commonly a fork. This causes an
44 | asymmetry between authoring and using Helm charts.
45 | Jsonnet on the other hand allows for an infinite number of abstractions, the initial
46 | author only needs to worry about their use case, so libraries can be kept quite concise.
47 | If a user wants to do something slightly different, they can simply concatenate the
48 | change to the library.
49 |
50 | Helm support in Tanka
51 | Tanka has built-in support for Helm charts,
52 | giving the Jsonnet community access to the biggest ecosystem of application definitions
53 | for Kubernetes.
54 |
55 | What benefit do we gain from it?
56 | Jsonnet is a language about data. By managing configuration with Jsonnet, it essentially
57 | turns into a massive programmable database. The infinite number of abstractions allows it
58 | to create layers. A Deployment is part of an application, which can be included in a cell
59 | (collection of loosely-coupled applications) that gets deployed to a cluster. By extending
60 | the cluster list, new cells can be created and applications automatically become available
61 | without the need to configure and deploy each application individually.
62 | Each of these concepts has their own configuration attributes that could be managed by
63 | a different team. This means that, with a clean, well defined API between layers of
64 | abstraction, a developer new to Jsonnet needn't learn every layer, they only need to
65 | learn the layer they are interested in, enabling them to become productive much faster
66 | than if they had to code every layer.
67 | index
68 |
69 |
70 |
17 | « previous index next »
18 | Exercise: rewrite a library with k8s-libsonnet
19 | In the first lesson we've written a extensible library and in the second lesson we've
20 | covered package management with jsonnet-bundler. In this lesson we'll combine what
21 | we've learned and rewrite that library.
22 | Objectives
23 |
24 | - Rewrite a library
25 | - Vendor and use
k8s-libsonnet
26 | - Understand the
lib/k.libsonnet convention
27 |
28 | Lesson
29 | In Write an extensible library, we created this library:
30 | local webserver = {
31 | new(name, replicas=1): {
32 | local base = self,
33 |
34 | container:: {
35 | name: 'httpd',
36 | image: 'httpd:2.4',
37 | },
38 |
39 | deployment: {
40 | apiVersion: 'apps/v1',
41 | kind: 'Deployment',
42 | metadata: {
43 | name: name,
44 | },
45 | spec: {
46 | replicas: replicas,
47 | template: {
48 | spec: {
49 | containers: [
50 | base.container,
51 | ],
52 | },
53 | },
54 | },
55 | },
56 | },
57 |
58 | withImage(image): {
59 | container+: { image: image },
60 | },
61 | };
62 |
63 | webserver.new('wonderful-webserver')
64 | + webserver.withImage('httpd:2.5')
65 |
66 | // example1.jsonnet
67 |
68 | This library is quite verbose as the author has to provide the apiVersion, kind and
69 | other attributes.
70 | To simplify this, the community has created a Kubernetes client library for Jsonnet called
71 | k8s-libsonnet. By leveraging this
72 | client library, the author can provide an abstraction that can work across most Kubernetes
73 | versions.
74 | Now go ahead with the k8s-libsonnet library and work out on your own with the resources
75 | in these lessons:
76 |
77 | - Write an extensible library
78 | - Understanding Package management
79 |
80 | Find the steps to a solution below.
81 | Solution
82 |
83 | Examples below expect to have an environment with export JSONNET_PATH="lib/:vendor/"
84 |
85 | Let's install k8s-libsonnet with jsonnet-bundler and import it:
86 | $ jb install https://github.com/jsonnet-libs/k8s-libsonnet/1.23@main
87 | Note the alternative naming pattern ending on 1.23, referencing the Kubernetes version
88 | this was generated for.
89 | (import 'github.com/jsonnet-libs/k8s-libsonnet/1.23/main.libsonnet')
90 |
91 | // example2/lib/k.libsonnet
92 |
93 | The most common convention to work with this is to provide lib/k.libsonnet as
94 | a shortcut.
95 |
96 | local k = import 'k.libsonnet';
97 |
98 | k.core.v1.container.new('container-name', 'container-image')
99 |
100 | // example2/example1.jsonnet
101 |
102 | Many libraries have a line local k = import 'k.libsonnet' to refer to this
103 | library.
104 |
105 | Let's rewrite the container following the
106 | documentation:
107 | local k = import 'k.libsonnet';
108 |
109 | local webserver = {
110 | new(name, replicas=1): {
111 | local base = self,
112 |
113 | container::
114 | k.core.v1.container.new('httpd', 'httpd:2.4'),
115 |
116 | deployment: {
117 | apiVersion: 'apps/v1',
118 | kind: 'Deployment',
119 | metadata: {
120 | name: name,
121 | },
122 | spec: {
123 | replicas: replicas,
124 | template: {
125 | spec: {
126 | containers: [
127 | base.container,
128 | ],
129 | },
130 | },
131 | },
132 | },
133 | },
134 |
135 | withImage(image): {
136 | container+:
137 | k.core.v1.container.withImage(image),
138 | },
139 | };
140 |
141 | webserver.new('wonderful-webserver')
142 | + webserver.withImage('httpd:2.5')
143 |
144 | // example2/example2.jsonnet
145 |
146 | The library has grouped a number of functions under k.core.v1.container, we'll use the
147 | new(name, image) function here, this makes it concise. Additionally the withImage()
148 | function uses the function with the same name in the library.
149 |
150 | And now for the
151 | deployment:
152 | local k = import 'k.libsonnet';
153 |
154 | local webserver = {
155 | new(name, replicas=1): {
156 | container::
157 | k.core.v1.container.new('httpd', 'httpd:2.4'),
158 |
159 | deployment:
160 | k.apps.v1.deployment.new(
161 | name,
162 | replicas,
163 | [self.container]
164 | ),
165 | },
166 |
167 | withImage(image): {
168 | container+:
169 | k.core.v1.container.withImage(image),
170 | },
171 | };
172 |
173 | webserver.new('wonderful-webserver')
174 | + webserver.withImage('httpd:2.5')
175 |
176 | // example2/example3.jsonnet
177 |
178 | The new(name, replicas, images) function makes things even more concise. The new()
179 | function is actually a custom shortcut with the most common parameters for a deployment.
180 | Note that we've removed local base = self,, this was not longer needed as the reference
181 | to self.container can now be made inside the same object.
182 |
183 | Having the library and execution together is not so useful, let's move it into a separate
184 | library and import it again.
185 | local k = import 'k.libsonnet';
186 |
187 | {
188 | new(name, replicas=1): {
189 | container::
190 | k.core.v1.container.new('httpd', 'httpd:2.4'),
191 |
192 | deployment:
193 | k.apps.v1.deployment.new(
194 | name,
195 | replicas,
196 | [self.container]
197 | ),
198 | },
199 |
200 | withImage(image): {
201 | container+:
202 | k.core.v1.container.withImage(image),
203 | },
204 | }
205 |
206 | // example2/lib/webserver/main.libsonnet
207 |
208 | This removes the local webserver and moves the contents to the root of the file.
209 |
210 | local webserver = import 'webserver/main.libsonnet';
211 |
212 | webserver.new('wonderful-webserver')
213 | + webserver.withImage('httpd:2.5')
214 |
215 | // example2/example4.jsonnet
216 |
217 | If we now import the library, we can access its functions just like before.
218 |
219 | local webserver = import 'webserver/main.libsonnet';
220 |
221 | {
222 | webserver1:
223 | webserver.new('wonderful-webserver')
224 | + webserver.withImage('httpd:2.3'),
225 |
226 | webserver2:
227 | webserver.new('marvellous-webserver'),
228 |
229 | webserver3:
230 | webserver.new('incredible-webserver', 2),
231 | }
232 |
233 | // example2/example5.jsonnet
234 |
235 | Or, if we want more instances, we can simply do so.
236 | Conclusion
237 | This exercise showed how to make a library more succinct and readable. By using the
238 | k.libsonnet abstract, the user has the option to use an alternative version of the
239 | k8s-libsonnet library.
240 | « previous index next »
241 |
242 |
243 |