Hello Holos

Overview

Like a traditional "Hello World" program, we'll start by configuring the podinfo Helm chart to output a greeting from a Kubernetes Service. This introduces the core concept of wrapping Helm charts as Holos Components.

Implementation

Holos Version

Ensure you have a current version of holos installed. This document was tested with the following version.

holos --version

0.104.1

Initialize Platform Structure

Create and initialize a minimal platform:

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

For reference, the directory structure you will attain by the end of this tutorial is listed below (NOTE: we have omitted the cue.mod directory for brevity):

Tree

.
|-- components
|   `-- podinfo
|       |-- podinfo.cue
|       `-- vendor
|-- deploy
|   `-- components
|       `-- podinfo
|-- platform
|   |-- platform.gen.cue
|   `-- podinfo.cue
|-- platform.metadata.json
|-- resources.cue
|-- schema.cue
`-- tags.cue

8 directories, 7 files

Details

.
|-- components
|   `-- podinfo
|       |-- podinfo.cue
|       `-- vendor
|-- deploy
|   `-- components
|       `-- podinfo
|-- platform
|   |-- platform.gen.cue
|   `-- podinfo.cue
|-- platform.metadata.json
|-- resources.cue
|-- schema.cue
`-- tags.cue

8 directories, 7 files

• Line 1 The platform root is the holos-tutorial directory we created.
• Line 2 This tutorial places components in components/. They may reside anywhere.
• Line 3 A component is a collection of *.cue files at a path.
• Line 4 We'll create this file and configure the podinfo helm chart in the next section.
• Line 5 The vendor directory contains a cached copy of the Helm chart that was fetched for the component.
• Line 6 Rendered manifests are placed within the deploy directory following the structure of the components/ directory.
• Line 9 The platform directory is the main entrypoint for the holos render platform command.
• Line 10 platform.gen.cue is initialized by holos init platform and contains the Platform spec.
• Line 11 podinfo.cue integrates podinfo with the platform by adding the component to the platform spec. We'll add ths file after the next section.
• Line 13 resources.cue Defines the Kubernetes resources available to manage in CUE.
• Line 14 schema.cue Defines the configuration common to all component kinds.
• Line 15 tags.cue Defines where component parameter values are injected into the overall platform configuration. We don't need to be concerned with this file until we cover component parameters.
• Lines 9-15 Initialized by holos init platform, user editable after initialization.

Create the Component

Configure the podinfo component:

mkdir -p components/podinfo

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

package holos

// Produce a helm chart build plan.
holos: HelmChart.BuildPlan

HelmChart: #Helm & {
	Name: "podinfo"
	Chart: {
		version: "6.6.2"
		repository: {
			name: "podinfo"
			url:  "https://stefanprodan.github.io/podinfo"
		}
	}
	// Holos marshals Values into values.yaml for Helm.
	Values: {
		// message is a string with a default value.  @tag indicates a value may
		// be injected from the platform spec component parameters.
		ui: {
			message: string | *"Hello World" @tag(greeting, type=string)
		}
	}
}

EOF

important

Like Go packages, CUE loads all *.cue files in the component directory to define the component.

note

CUE recursively loads *.cue files from the component directory up to the platform root. For example, #Helm referenced on line 6 is defined in root-level schema.cue.

Add to Platform

Register the podinfo component in platform/podinfo.cue:

cat <<EOF > platform/podinfo.cue

package holos

Platform: Components: podinfo: {
	name: "podinfo"
	path: "components/podinfo"
	// Inject a value into the component.
	parameters: greeting: "Hello Holos!"
}

EOF

tip

Parameter names are unrestricted, except for the reserved holos_ prefix.

Generate Manifests

Render the podinfo configuration:

Command

holos render platform

Output

rendered podinfo in 312.472625ms
rendered platform in 312.557375ms

Holos executes helm template with locally cached charts to generate:

deploy/components/podinfo/podinfo.gen.yaml

Service

apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: podinfo
    app.kubernetes.io/version: 6.6.2
    helm.sh/chart: podinfo-6.6.2
  name: podinfo
spec:
  ports:
  - name: http
    port: 9898
    protocol: TCP
    targetPort: http
  - name: grpc
    port: 9999
    protocol: TCP
    targetPort: grpc
  selector:
    app.kubernetes.io/name: podinfo
  type: ClusterIP

Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: podinfo
    app.kubernetes.io/version: 6.6.2
    helm.sh/chart: podinfo-6.6.2
  name: podinfo
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: podinfo
  strategy:
    rollingUpdate:
      maxUnavailable: 1
    type: RollingUpdate
  template:
    metadata:
      annotations:
        prometheus.io/port: "9898"
        prometheus.io/scrape: "true"
      labels:
        app.kubernetes.io/name: podinfo
    spec:
      containers:
      - command:
        - ./podinfo
        - --port=9898
        - --cert-path=/data/cert
        - --port-metrics=9797
        - --grpc-port=9999
        - --grpc-service-name=podinfo
        - --level=info
        - --random-delay=false
        - --random-error=false
        env:
        - name: PODINFO_UI_MESSAGE
          value: Hello Holos!
        - name: PODINFO_UI_COLOR
          value: '#34577c'
        image: ghcr.io/stefanprodan/podinfo:6.6.2
        imagePullPolicy: IfNotPresent
        livenessProbe:
          exec:
            command:
            - podcli
            - check
            - http
            - localhost:9898/healthz
          failureThreshold: 3
          initialDelaySeconds: 1
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 5
        name: podinfo
        ports:
        - containerPort: 9898
          name: http
          protocol: TCP
        - containerPort: 9797
          name: http-metrics
          protocol: TCP
        - containerPort: 9999
          name: grpc
          protocol: TCP
        readinessProbe:
          exec:
            command:
            - podcli
            - check
            - http
            - localhost:9898/readyz
          failureThreshold: 3
          initialDelaySeconds: 1
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 5
        resources:
          limits: null
          requests:
            cpu: 1m
            memory: 16Mi
        volumeMounts:
        - mountPath: /data
          name: data
      terminationGracePeriodSeconds: 30
      volumes:
      - emptyDir: {}
        name: data

Holos renders the component with the greeting injected from the platform spec.

grep -B2 Hello deploy/components/podinfo/podinfo.gen.yaml

        env:
        - name: PODINFO_UI_MESSAGE
          value: Hello Holos!

Breaking it down

We run holos render platform because the CUE files in the platform directory export a Platform resource to holos.

important

The platform/ directory is the default entry point to the platform rendering process. Override with --platform <dir>.

Components are the building blocks of a Platform. The platform/podinfo.cue file integrates the podinfo component with the Platform.

Holos requires two fields to integrate a component with the platform:

1. A unique name for the component.
2. The component path to the directory containing the CUE files that export a BuildPlan defining the component.

Component parameters are optional and allow re-use of the same component.

Rendering Overview

Take a look at the other tabs for more detailed sequence diagrams.

Platform Sequence

Component Sequence

Next Steps

We've shown how to integrate one Helm chart into the Platform, but we haven't yet covered multiple Helm charts. Continue with the next tutorial to learn how Holos makes it easy to inject values into multiple components safely and efficiently.