mirror of
https://github.com/holos-run/holos.git
synced 2026-04-07 01:54:58 +00:00
dab94961ff
In preparation for v1alpha6 where we're designing a generic Command task for use in generators, transformers, and validators, we need to create permalinks for the existing v1alpha5 schemas. This patch copies the current documentation to the v1alpha5 versioned docs links and establishes v1alpha6 as the current version. See: https://github.com/holos-run/holos/pull/413 for context.
256 lines
9.8 KiB
Plaintext
256 lines
9.8 KiB
Plaintext
---
|
|
slug: kustomize
|
|
title: Kustomize
|
|
description: Holos makes it easy to Kustomize configuration.
|
|
sidebar_position: 45
|
|
---
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import CodeBlock from '@theme/CodeBlock';
|
|
|
|
# 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
|
|
|
|
### Holos Version
|
|
|
|
Ensure you have a current version of `holos` installed. This document was
|
|
tested with the following version.
|
|
|
|
import HolosVersionCommand from '!!raw-loader!./_kustomize/script-01-holos-version/command.sh';
|
|
import HolosVersionOutput from '!!raw-loader!./_kustomize/script-01-holos-version/output.txt';
|
|
|
|
<CodeBlock language="bash">{HolosVersionCommand}</CodeBlock>
|
|
<CodeBlock language="txt">{HolosVersionOutput}</CodeBlock>
|
|
|
|
### Generating the structure
|
|
|
|
<Tabs>
|
|
<TabItem value="optional" label="Optional">
|
|
:::note Skip this step if you completed the [Helm Values] tutorial.
|
|
|
|
Otherwise click the **Generate** tab to generate a blank platform now.
|
|
:::
|
|
</TabItem>
|
|
<TabItem value="generate" label="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.
|
|
|
|
import MkdirAndInit from '!!raw-loader!./_kustomize/script-02-kustomize/mkdir-and-init.sh';
|
|
import GitInit from '!!raw-loader!./_kustomize/script-02-kustomize/git-init.sh';
|
|
|
|
<CodeBlock language="bash">{MkdirAndInit}</CodeBlock>
|
|
|
|
Make a commit to track changes.
|
|
|
|
<CodeBlock language="bash">{GitInit}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### Managing the Component
|
|
|
|
Create the `httpbin` component directory, and add the `httpbin.cue` and
|
|
`httpbin.yaml` files to it for configuration and setup.
|
|
|
|
import MkdirComponent from '!!raw-loader!./_kustomize/script-02-kustomize/mkdir-component.sh';
|
|
import HttpbinComponentHeader from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-component-header.sh';
|
|
import HttpbinComponentBody from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-component-body.cue';
|
|
import EofTrailer from '!!raw-loader!./_kustomize/script-02-kustomize/eof-trailer.sh';
|
|
import HttpbinYamlHeader from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-yaml-header.sh';
|
|
import HttpbinYamlBody from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-yaml-body.yaml';
|
|
|
|
<Tabs groupId="800C3AE7-E7F8-4AFC-ABF1-6AFECD945958">
|
|
<TabItem value="setup" label="Setup">
|
|
<CodeBlock language="bash">{MkdirComponent}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="components/httpbin/httpbin.cue" label="httpbin.cue">
|
|
<CodeBlock language="bash">{HttpbinComponentHeader}</CodeBlock>
|
|
<CodeBlock language="cue" showLineNumbers>{HttpbinComponentBody}</CodeBlock>
|
|
<CodeBlock language="bash">{EofTrailer}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="components/httpbin/httpbin.yaml" label="httpbin.yaml">
|
|
<CodeBlock language="bash">{HttpbinYamlHeader}</CodeBlock>
|
|
<CodeBlock language="yaml" showLineNumbers>{HttpbinYamlBody}</CodeBlock>
|
|
<CodeBlock language="bash">{EofTrailer}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
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.
|
|
|
|
import RegisterComponentHeader from '!!raw-loader!./_kustomize/script-02-kustomize/register-component-header.sh';
|
|
import RegisterComponentBody from '!!raw-loader!./_kustomize/script-02-kustomize/register-component-body.cue';
|
|
|
|
<CodeBlock language="bash">{RegisterComponentHeader}</CodeBlock>
|
|
<CodeBlock language="cue">{RegisterComponentBody}</CodeBlock>
|
|
<CodeBlock language="bash">{EofTrailer}</CodeBlock>
|
|
|
|
Render the platform.
|
|
|
|
import RenderCommand from '!!raw-loader!./_kustomize/script-02-kustomize/render.sh';
|
|
import RegisterComponentOutput from '!!raw-loader!./_kustomize/script-02-kustomize/register-component-output.txt';
|
|
|
|
<Tabs groupId="B120D5D1-0EAB-41E0-AD21-15526EBDD53D">
|
|
<TabItem value="command" label="Command">
|
|
<CodeBlock language="bash">{RenderCommand}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="output" label="Output">
|
|
<CodeBlock language="txt">{RegisterComponentOutput}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Commit the results.
|
|
|
|
import GitCommitComponent from '!!raw-loader!./_kustomize/script-02-kustomize/git-commit-component.sh';
|
|
import GitCommitComponentOutput from '!!raw-loader!./_kustomize/script-02-kustomize/git-commit-component-output.txt';
|
|
|
|
<Tabs groupId="446CC550-A634-45C0-BEC7-992E5C56D4FA">
|
|
<TabItem value="command" label="Command">
|
|
<CodeBlock language="bash">{GitCommitComponent}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="output" label="Output">
|
|
<CodeBlock language="txt">{GitCommitComponentOutput}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### 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.
|
|
|
|
import CueExport from '!!raw-loader!./_kustomize/script-02-kustomize/cue-export.sh';
|
|
import BuildplanOutput from '!!raw-loader!./_kustomize/script-02-kustomize/buildplan-output.cue';
|
|
|
|
<Tabs groupId="DD697D65-5BEC-4B92-BB33-59BE4FEC112F">
|
|
<TabItem value="command" label="Command">
|
|
<CodeBlock language="bash">{CueExport}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="output" label="Output">
|
|
<CodeBlock language="yaml">{BuildplanOutput}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### 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.
|
|
|
|
import HttpbinPatchHeader from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-patch-header.sh';
|
|
import HttpbinPatchBody from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-patch-body.cue';
|
|
|
|
<CodeBlock language="bash">{HttpbinPatchHeader}</CodeBlock>
|
|
<CodeBlock language="bash" showLineNumbers>{HttpbinPatchBody}</CodeBlock>
|
|
<CodeBlock language="bash">{EofTrailer}</CodeBlock>
|
|
|
|
:::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.
|
|
|
|
import KustomizePatchRenderOutput from '!!raw-loader!./_kustomize/script-02-kustomize/kustomize-patch-render-output.txt';
|
|
|
|
<Tabs groupId="5D1812DD-8E7B-4F97-B349-275214F38B6E">
|
|
<TabItem value="command" label="Command">
|
|
<CodeBlock language="bash">{RenderCommand}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="output" label="Output">
|
|
<CodeBlock language="txt">{KustomizePatchRenderOutput}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Holos is configuring Kustomize to patch the plain `httpbin.yaml` file with the
|
|
annotation.
|
|
|
|
import GitDiff from '!!raw-loader!./_kustomize/script-02-kustomize/git-diff.sh';
|
|
import GitDiffOutput from '!!raw-loader!./_kustomize/script-02-kustomize/git.diff';
|
|
|
|
<Tabs groupId="3D80279E-8EDE-4B3E-9269-50F5D1C1CA42">
|
|
<TabItem value="command" label="Command">
|
|
<CodeBlock language="bash">{GitDiff}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="output" label="Output">
|
|
<CodeBlock language="diff">{GitDiffOutput}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Add and commit the final changes.
|
|
|
|
import GitCommitFinal from '!!raw-loader!./_kustomize/script-02-kustomize/git-commit-final.sh';
|
|
import GitCommitFinalOutput from '!!raw-loader!./_kustomize/script-02-kustomize/git-commit-final-output.txt';
|
|
|
|
<Tabs groupId="54C335C8-B382-4277-AE87-0D6556921955">
|
|
<TabItem value="command" label="Command">
|
|
<CodeBlock language="bash">{GitCommitFinal}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="output" label="Output">
|
|
<CodeBlock language="txt">{GitCommitFinalOutput}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## 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.
|
|
|
|
[httpbin]: https://github.com/mccutchen/go-httpbin/tree/v2.15.0
|
|
[prometheus]: https://github.com/prometheus-community/helm-charts/tree/prometheus-25.27.0/charts/prometheus
|
|
[blackbox]: https://github.com/prometheus-community/helm-charts/tree/prometheus-blackbox-exporter-9.0.1/charts/prometheus-blackbox-exporter
|
|
[kustomize]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
|
|
|
|
[Helm Values]: ./helm-values.mdx
|
|
[File Generator]: ../api/core.md#File
|
|
[Kustomize Transformer]: ../api/core.md#Kustomize
|
|
[BuildPlan]: ../api/core.md#BuildPlan
|
|
[KustomizeConfig]: ../api/author.md#KustomizeConfig
|
|
[Local Cluster]: ../topics/local-cluster.mdx
|