The `hull.objects` section

The top-level object types beneath hull.objects represent the supported Kubernetes object types you might want to create instances from. Each object type is a dictionary where the entries values are the objects properties and each object has it's own key which is unique to the object type it belongs to. Further K8S object types can be added as needed to the library so it can easily be extended.

Keys of object instances

One important aspect is that for all top-level object types, instances of a particular type are always identified by a key which is unique to the instance and object type combination. The same key can however be used for instances of different object types.

By having keys that identify instances you can:

do multi-layered merging of object properties by stacking values.yaml files on top of each other. You might start with defining the default object structure of the application or micro service defined in the given helm chart. Then you might add a values.yaml layer for a particular environment like staging or production. Then you might add a values.yaml layer for credentials. And so on. By uniquely identifying the instances of a particular K8s object type it becomes easy to adjust the objects properties through a multitude of layers.
use the key of an instance for naming the instance. All instance names are constructed by the following ground rule: {{ printf "%s-%s-%s" .Release.Name .Chart.Name key }}. This generates unique, dynamic names per object type and release + instance key combination.

For example, assuming the parent Helm chart is named my_webservice and the release named staging and given this specification in values.yaml:

  hull:
    objects:
      deployment:
        nginx:
          pod:
            containers:
              nginx:
                repository: nginx
                tag: 1.14.2

a Kubernetes deployment object with the following metadata.name is created:

my_webservice-staging-nginx

Note that you can opt to define a static name for instances you create by adding a property staticName: true to your objects definition. If you do so the objects name will exactly match the key name you chose.

each particular instance can have an enabled sub-field set to true or false. This way you can predefine instances of object types in your helm charts values.yaml but not deploy them in a default scenario. Or enable them by default and refrain from deploying them in a particular environment by disabling them in an superimposed system specific values.yaml. Note that unless you explicitly specify enabled: false each instance you define will be created by default, a missing enabled key is equivalent to enabled: true.
cross-referencing objects within a helm chart by the instance key is a useful feature of the HULL library. This is possible in these contexts:
when a reference to a ConfigMap or Secret comes into play you can just use the key of the targeted instance and the dynamic name will be rendered in the output. This is possible for referencing
- a ConfigMap or Secret behind a Volume or
- a Secret behind an Ingress' TLS specification or
- a ConfigMap or Secret behind an environment value added to a container spec.
when referencing Services in the backend of an ingress' host you can specify the key to reference the backend service.

Note that you can in these cases opt to refer to a static name instead too. Adding a property staticName: true to the dictionary with your reference will force the referenced objects name to exactly match the name you entered.

Values of object instances

The values of object instance keys reflects the Kubernetes objects to create for the chart. To specify these objects efficiently, the available properties for configuration can be split into three groups:

Basic HULL object configuration with hull.ObjectBase.v1 whose properties are available for all object types and instances. These are enabled, staticName, annotations and labels.

Given the example of a deployment named nginx you can add the following properties of hull.ObjectBase.v1 to the object instance:

hull:
  objects:
    deployment:
      nginx: # unique key/identifier of the deployment to create
        staticName: true # property of hull.ObjectBase.v1
                        # forces the metadata.name to be just the <KEY> 'nginx' 
                        # and not a dynamic name '<CHART>-<RELEASE>-<KEY>' which 
                        # would be the better default behavior of creating 
                        # unique object names for all objects.
        enabled: true    # property of hull.ObjectBase.v1
                        # this deployment will be rendered to a YAML object if enabled
        labels:
          demo_label: "demo" # property of hull.ObjectBase.v1
                            # add all labels here that shall be added 
                            # to the object instance metadata section
        annotations:
          demo_annotation: "demo" # property of hull.ObjectBase.v1
                                  # add all annotations here that shall be added 
                                  # to the object instance metadata section
        pod: 
          ... # Here would come the hull.PodTemplate.v1 definition
              # see below for details

Specialized HULL object properties for some object types. Below is a reference of which object type supports which special properties in addition to the basic object configuration.

Again given the example of a deployment named nginx you would want to add properties of the HULL hull.PodTemplate.v1 to the instance. With them you set the pod property to define the pod template (initContainers, containers, volumes, ...) and can add templateLabels and templateAnnotations just to the pods created metadata and not the deployment objects metadata section:

hull:
  objects:
    deployment:
      nginx: 
        staticName: true 
        enabled: true 
        labels: 
          demo_label: "demo" 
        annotations: 
          demo_annotation: "demo" 
        templateLabels: # property of hull.PodTemplate.v1 to define 
                        # labels only added to the pod
          demo_pod_label: "demo pod" 
        templateAnnotations: # property of hull.PodTemplate.v1 to define 
                        # annotations only added to the pod
          demo_pod_annotation: "demo pod"
        pod: # property of hull.PodTemplate.v1 to define the pod template
          containers:
            nginx: # all containers of a pod template are also referenced by a 
                  # unique key to make manipulating them easy.
              image:
                repository: nginx # specify repository and tag
                                  # separately with HULL for easier composability
                tag: 1.14.2
              ... # further properties (volumeMounts, affinities, ...)

Kubernetes object properties. For each object type it is basically possible to specify all existing Kubernetes properties. In case a HULL property overwrites a identically named Kubernetes property the HULL property has precedence. Even if a HULL property overrides a Kubernetes property it is intended to provide the same complete configuration options, even if sometimes handled differently by HULL.

Some of the typical top-level Kubernetes object properties and fields don't require setting them with HULL based objects because they can be deducted automatically: - the apiVersion and kind are determined by the HULL object type and Kubernetes API version and don't require to be explicitly set (except for objects of type customresource). - the top-level metadata dictionary on objects is handled by HULL via the annotations and labels fields and the naming rules explained above. So the metadata field does not require configuration and is hence not configurable for any object.

Some lower level structures are also converted from the Kubernetes API array form to a dictionary form or are modified to improve working with them. This also enables more sophisticated merging of layers since arrays don't merge well, they only can be overwritten completely. Overwriting arrays however can make it hard to forget about elements that are contained in the default form of the array (you would need to know that they existed in the first place). In short, for a layered configuration approach without an endless amount of elements the dictionary is preferable for representing data since it offers a much better merging support.

So again using the example of a deployment named nginx you can add the remaining available Kubernetes properties to the object instance which are not handled by HULL as shown below. For a deployment specifically you can add all the remaining properties defined in the deploymentspec API schema from deploymentspec-v1-apps which are minReadySeconds, paused, progressDeadlineSeconds, replicas, revisionHistoryLimit and strategy. If properties are marked as mandatory in the Kubernetes JSON schema you must provide them otherwise the rendering process will fail:
```
hull:
  objects:
    deployment:
      nginx: 
        staticName: true 
        enabled: true 
        labels: 
          demo_label: "demo" 
        annotations: 
          demo_annotation: "demo" 
        pod:
          ... # Here would come the hull.PodTemplate.v1 definition
              # see above for details 
        replicas: 3 # property from the Kubernetes API deploymentspec
        strategy: # property from the Kubernetes API deploymentspec
          type: Recreate
        ... # further Kubernetes API deploymentspec options
```

Composing objects with HULL

Here is an overview of which top level properties are available for which object type in HULL. The HULL properties are grouped by the respective HULL JSON schema group they belong to. A detailed description of these groups and their properties is found in the documentation of this helm chart and the respective linked documents.

Admissionregistration APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`mutatingadmissionpolicy`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` mutatingadmissionpolicyspec-v1-admissionregistration `failurePolicy` `matchConditions` `matchConstraints` `mutations` `paramKind` `reinvocationPolicy` `variables`
`mutatingadmissionpolicybinding`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` mutatingadmissionpolicybindingspec-v1-admissionregistration `matchResources` `paramRef` `policyName`
`mutatingwebhookconfiguration`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.MutatingWebhook.v1 `webhooks`
`validatingadmissionpolicy`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` validatingadmissionpolicyspec-v1-admissionregistration `auditAnnotations` `failurePolicy` `matchConditions` `matchConstraints` `paramKind` `validations` `variables`
`validatingadmissionpolicybinding`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` validatingadmissionpolicybindingspec-v1-admissionregistration `matchResources` `paramRef` `policyName` `validationActions`
`validatingwebhookconfiguration`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.ValidatingWebhook.v1 `webhooks`

Apps APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`daemonset`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.PodTemplate.v1 `templateAnnotations` `templateLabels` `pod`	daemonsetspec-v1-apps `minReadySeconds` `ordinals` `revisionHistoryLimit` `updateStrategy`
`deployment`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.PodTemplate.v1 `templateAnnotations` `templateLabels` `pod`	deploymentspec-v1-apps `minReadySeconds` `paused` `progressDeadlineSeconds` `replicas` `revisionHistoryLimit` `strategy`
`statefulset`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.PodTemplate.v1 `templateAnnotations` `templateLabels` `pod`	statefulsetspec-v1-apps `podManagementPolicy` `replicas` `revisionHistoryLimit` `serviceName` `updateStrategy` `serviceName` `volumeClaimTemplates`

Autoscaling APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`horizontalpodautoscaler`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.HorizontalPodAutoscaler.v1 `scaleTargetRef`	horizontalpodautoscalerspec-v2-autoscaling `behavior` `maxReplicas` `metrics` `minReplicas`

Batch APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`job`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.PodTemplate.v1 `templateAnnotations` `templateLabels` `pod`	jobspec-v1-batch `activeDeadlineSeconds` `backoffLimit` `completionMode` `completions` `manualSelector` `parallelism` `selector` `suspend` `ttlSecondsAfterFinished`
`cronjob`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.Job.v1 `job`	cronjobspec-v1-batch `concurrencyPolicy` `failedJobsHistoryLimit` `schedule` `startingDeadlineSeconds` `successfulJobsHistoryLimit` `suspend`

Core APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`configmap`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.VirtualFolder.v1 `data`	configmap-v1-core `binaryData` `immutable`
`endpoints` (deprecated since K8S 1.33)	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	endpoints-v1-core `subsets`
`limitrange`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	limitrange-v1-core `limits`
`namespace`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	namespace-v1-core `spec` `status`
`persistentvolume`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	persistentvolumespec-v1-core `accessModes` `awsElasticBlockStore` `azureDisk` `azureFile` `capacity` `cephfs` `cinder` `claimRef` `csi` `fc` `flexVolume` `flocker` `gcePersistentDisk` `glusterfs` `hostPath` `iscsi` `local` `mountOptions` `nfs` `nodeAffinity` `persistentVolumeReclaimPolicy` `photonPersistentDisk` `portworxVolume` `quobyte` `rbd` `scaleIO` `storageClassName` `storageos` `volumeMode` `vsphereVolume`
`persistentvolumeclaim`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	persistentvolumeclaimspec-v1-core `accessModes` `dataSource` `resources` `selector` `storageClassName` `volumeMode` `volumeName`
`resourcequota`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	resourcequotaspec-v1-core `hard` `scopeSelector` `scopes`
`secret`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.VirtualFolder.v1 `data`	secret-v1-core `immutable` `stringData` `type`
`service`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.Service.v1 `ports`	servicespec-v1-core `allocateLoadBalancerNodePorts` `clusterIP` `clusterIPs` `externalIPs` `externalName` `externalTrafficPolicy` `healthCheckNodePort` `internalTrafficPolicy` `ipFamilies` `ipFamilyPolicy` `loadBalancerClass` `loadBalancerIP` `loadBalancerSourceRanges` `publishNotReadyAddresses` `selector` `sessionAffinity` `sessionAffinityConfig` `topologyKeys` `type`
`serviceaccount`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	serviceaccount-v1-core `automountServiceAccountToken` `imagePullSecrets` `secrets`

Discovery APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`endpointslice`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	endpointslice-v1-discovery-k8s-io `addressType` `endpoints` `ports`

Networking APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`ingress`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.Ingress.v1 `tls` `rules`	ingressspec-v1-networking-k8s-io `defaultBackend` `ingressClassName`
`ingressclass`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	ingressclassspec-v1-networking-k8s-io `controller` `parameters`
`networkpolicy`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	networkpolicyspec-v1-networking-k8s-io `egress` `ingress` `podSelector` `policyTypes`

Policy APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`poddisruptionbudget`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	poddisruptionbudgetspec-v1-policy `maxUnavailable` `minAvailable` `selector` `unhealthyPodEvictionPolicy`

RBAC APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`clusterrole`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.Rule.v1 `rules`	clusterrole-v1-rbac-authorization-k8s-io `aggregationRule`
`clusterrolebinding`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	clusterrolebinding-v1-rbac-authorization-k8s-io `roleRef` `subjects`
`role`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.Rule.v1 `rules`	role-v1-rbac-authorization-k8s-io
`rolebinding`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	rolebinding-v1-rbac-authorization-k8s-io `roleRef` `subjects`

Scheduling APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`priorityclass`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	priorityclass-v1-scheduling-k8s-io `description` `globalDefault` `preemptionPolicy` `value`

Storage APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`storageclass`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	storageclass-v1-storage-k8s-io `allowVolumeExpansion` `allowedTopologies` `mountOptions` `parameters` `provisioner` `reclaimPolicy` `volumeBindingMode`

HULL Extensions APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`customresource`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.CustomResource.v1 `apiVersion` `kind` `spec`
`generic`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.Generic.v1 `apiVersion` `kind`
`registry`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.Registry.v1 `server` `username` `password`

Gateway APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`backendlbpolicy`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.BackendLBPolicy.v1alpha2 `targetRefs`	backendlbpolicyspec-v1alpha2-gateway-networking-k8s-io `sessionPersistence`
`backendtlspolicy`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.BackendTLSPolicy.v1alpha3 `targetRefs`	backendtlspolicyspec-v1alpha3-gateway-networking-k8s-io `options` `validation`
`gatewayclass`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	gatewayclassspec-v1-gateway-networking-k8s-io `controllerName` `description` `parametersRef`
`gateway`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.Gateway.v1 `addresses` `listeners`	gatewayspec-v1-gateway-networking-k8s-io `backendTLS` `gatewayClassName` `infrastructure`
`grpcroute`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.GRPCRoute.v1 `hostnames` `parentRefs` `rules`
`httproute`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.HTTPRoute.v1 `hostnames` `parentRefs` `rules`
`referencegrant`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.ReferenceGrant.v1beta1 `from` `to`
`tcproute`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.TCPRoute.v1alpha2 `parentRefs` `rules`
`tlsroute`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.TLSRoute.v1alpha2 `hostnames` `parentRefs` `rules`
`udproute`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName` hull.UDPRoute.v1alpha2 `parentRefs` `rules`

Third Party APIs

HULL Object Type	HULL Properties	Kubernetes/External Properties
`servicemonitor`	hull.ObjectBase.v1 `enabled` `annotations` `labels` `staticName`	ServiceMonitor CRD `spec`

Back to README.md

The hull.objects section