Kustomize

Overview

In the previous tutorial, we learned how Holos simplifies the holistic integration of the prometheus and blackbox charts, ensuring they are configured in sync.

In this tutorial, we'll go a step further by integrating the httpbin service with Prometheus and Blackbox to automatically probe for availability.

We'll also explore how Holos manages kustomize bases, similar to the Helm kind covered in the Helm Values tutorial.

The Code

Generating the structure

Optional

Skip this step if you completed the Helm Values tutorial.

Otherwise click the Generate tab to generate a blank platform now.

Generate

Use holos to generate a minimal platform directory structure. First, create and navigate into a blank directory. Then, run the holos init platform command.

mkdir holos-kustomize-tutorial
cd holos-kustomize-tutorial
holos init platform v1alpha5

Make a commit to track changes.

git init . && git add . && git commit -m initial

Managing the Component

Create the httpbin component directory, and add the httpbin.cue and httpbin.yaml files to it for configuration and setup.

Setup

mkdir -p components/httpbin

httpbin.cue

cat <<EOF > components/httpbin/httpbin.cue

package holos

// Produce a Kustomize BuildPlan for Holos
holos: Kustomize.BuildPlan

// https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/README.md
Kustomize: #Kustomize & {
	KustomizeConfig: {
		// Files tells Holos to copy the file from the component path to the
		// temporary directory Holos uses for BuildPlan execution.
		Files: {
			"httpbin.yaml": _
		}
		CommonLabels: {
			"app.kubernetes.io/name": "httpbin"
		}
		// Kustomization represents a kustomization.yaml file in CUE.  Holos
		// marshals this field into a `kustomization.yaml` while processing a
		// BuildPlan.  See
		// https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
		Kustomization: {
			images: [{name: "mccutchen/go-httpbin"}]
			// Use a hidden field to compose patches easily with a struct.  Hidden
			// fields are not included in exported structures.
			_patches: {}
			// Convert the hidden struct to a list.
			patches: [for x in _patches {x}]
		}
	}
}

EOF

httpbin.yaml

cat <<EOF > components/httpbin/httpbin.yaml

# https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/resources.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin
spec:
  template:
    spec:
      containers:
        - name: httpbin
          image: mccutchen/go-httpbin
          ports:
            - name: http
              containerPort: 8080
              protocol: TCP
          livenessProbe:
            httpGet:
              path: /status/200
              port: http
          readinessProbe:
            httpGet:
              path: /status/200
              port: http
          resources: {}
---
apiVersion: v1
kind: Service
metadata:
  name: httpbin
spec:
  ports:
    - port: 80
      targetPort: http
      protocol: TCP
      name: http
      appProtocol: http

EOF

Holos knows the httpbin.yaml file is part of the BuildPlan because of the KustomizeConfig: Files: "httpbin.yaml": _ line in the httpbin.cue.

Register the Components

Register httpbin with the platform by adding the following file to the platform directory.

cat <<EOF > platform/httpbin.cue

package holos

Platform: Components: {
	httpbin: {
		name: "httpbin"
		path: "components/httpbin"
	}
}

EOF

Render the platform.

Command

holos render platform

Output

rendered httpbin in 707.554666ms
rendered platform in 707.9845ms

Commit the results.

Command

git add . && git commit -m 'add httpbin'

Output

[main c05f9ef] add httpbin
 4 files changed, 118 insertions(+)
 create mode 100644 components/httpbin/httpbin.cue
 create mode 100644 components/httpbin/httpbin.yaml
 create mode 100644 deploy/components/httpbin/httpbin.gen.yaml
 create mode 100644 platform/httpbin.cue

Inspecting the Build Plan

We can see the BuildPlan exported to holos by the holos: Kustomize.BuildPlan line in httpbin.cue. Holos processes this build plan to produce the fully rendered manifests.

Command

holos cue export --expression holos --out=yaml ./components/httpbin

Output

kind: BuildPlan
apiVersion: v1alpha5
metadata:
  name: no-name
spec:
  artifacts:
    - artifact: components/no-name/no-name.gen.yaml
      generators:
        - kind: Resources
          output: resources.gen.yaml
          resources: {}
        - kind: File
          output: httpbin.yaml
          file:
            source: httpbin.yaml
      transformers:
        - kind: Kustomize
          inputs:
            - resources.gen.yaml
            - httpbin.yaml
          output: components/no-name/no-name.gen.yaml
          kustomize:
            kustomization:
              labels:
                - includeSelectors: false
                  pairs:
                    app.kubernetes.io/name: httpbin
              patches: []
              images:
                - name: mccutchen/go-httpbin
              resources:
                - resources.gen.yaml
                - httpbin.yaml
              kind: Kustomization
              apiVersion: kustomize.config.k8s.io/v1beta1
source:
  component:
    name: no-name
    path: no-path
    parameters: {}

Transforming Manifests

Review the BuildPlan exported in the previous command:

1. The File Generator copies the plain httpbin.yaml file into the build.
2. The Kustomize Transformer uses httpbin.yaml as an input resource.
3. The final artifact is the output from Kustomize.

This BuildPlan transforms the raw YAML by labeling all of the resources with "app.kubernetes.io/name": "httpbin" using the KustomizeConfig CommonLabels field.

To complete the integration with Prometheus, annotate the Service with prometheus.io/probe: "true". Holos makes this easier with CUE, so there's no need to edit any YAML files manually.

Add a new patches.cue file to the httpbin component with the following content.

cat <<EOF > components/httpbin/patches.cue

package holos

import "encoding/yaml"

// Mix in a Kustomize patch to the configuration.
Kustomize: KustomizeConfig: Kustomization: _patches: {
	probe: {
		target: kind: "Service"
		target: name: "httpbin"
		patch: yaml.Marshal([{
			op:    "add"
			path:  "/metadata/annotations/prometheus.io~1probe"
			value: "true"
		}])
	}
}

EOF

note

We use a hidden _patches field to easily unify data into a struct, then convert the struct into a list for export.

Reviewing Changes

Render the platform to see the result of the kustomization patch.

Command

holos render platform

Output

rendered httpbin in 197.030208ms
rendered platform in 197.416416ms

Holos is configuring Kustomize to patch the plain httpbin.yaml file with the annotation.

Command

git diff

Output

diff --git a/deploy/components/httpbin/httpbin.gen.yaml b/deploy/components/httpbin/httpbin.gen.yaml
index 298b9a8..a16bd1a 100644
--- a/deploy/components/httpbin/httpbin.gen.yaml
+++ b/deploy/components/httpbin/httpbin.gen.yaml
@@ -1,6 +1,8 @@
 apiVersion: v1
 kind: Service
 metadata:
+  annotations:
+    prometheus.io/probe: "true"
   labels:
     app.kubernetes.io/name: httpbin
   name: httpbin

Add and commit the final changes.

Command

git add . && git commit -m 'annotate httpbin for prometheus probes'

Output

[main 6eeeadb] annotate httpbin for prometheus probes
 2 files changed, 3 insertions(+), 1 deletion(-)

Trying Locally

Optionally, apply the manifests rendered by Holos to a Local Cluster for testing and validation.

Next Steps

In this tutorial, we learned how Holos simplifies managing httpbin, which is distributed as a Kustomize base. We used a Kustomize component similar to the Helm component covered previously. Holos provides a straightforward way to customize any component, demonstrated by patching an annotation onto the httpbin Service.

Continue with the tutorial to learn how Holos facilitates certificate management and makes services accessible outside of a cluster.