Skip to content

Authoring, Migrating, and Importing Configuration

Kubernetes/YAML

ConfigHub expects Kubernetes/YAML configuration units to be comprised of one or more Kubernetes resources each represented as a YAML document.

When not cloning from other Units in ConfigHub, we recommend you use other tools to author or render Kubernetes configuration as plain WET (Write Every Time) YAML, and then import it or upload it to ConfigHub with cub variant upload, cub unit create, or cub function set upsert-resource.

You could also use the ConfigHub package installer.

A number of off-the-shelf components (e.g., cert-manager) include plain YAML as well as Helm charts, kustomize patches, and other DRY (Don't Repeat Yourself) configuration generation formats.

Unlike Infrastructure as Code tools, no laborious templating is required to use generated configuration productively.

Because ConfigHub treats the configuration data as authoritative, configuration values do not need to be specified all at once. They can be decoupled in time. That means you can create a starting configuration and then edit and/or transform it until it meets your requirements.

AI

Use your favorite AI agent or chatbot to generate the Kubernetes YAML, and even to upload it.

The installer's kubernetes-resources package holds starting templates for the common resource kinds, with the recommended defaults below applied, and is a good set of samples to generate from.

Use cub function local vet-schemas to validate the resources prior to uploading them.

ConfigHub stores whatever valid Kubernetes YAML you give it, but some defaults are worth setting on everything you author. Most of them have a function that fills them in, so you can apply them in bulk after uploading, as a Trigger on every change, or as part of an installer package. The defaults functions fill in only what is missing or a placeholder, so running them again leaves values you have set alone. The installer's kubernetes-resources package runs set-namespace, then set-container-resources-defaults, set-container-probe-defaults, set-pod-container-security-context-defaults and set-automount-service-account-token-false on every workload, and set-pod-security-defaults on Namespaces, and validates the result with vet-schemas, vet-merge-keys and vet-format.

  • Labels. Use the Kubernetes recommended labels, at least app.kubernetes.io/name, on the pod template and in the selector, rather than a bare app label. set-workload-labels sets a label on a workload's pod template and on the selectors that select its pods.
  • Resources and probes. set-container-resources-defaults gives every container without resources small requests, and set-container-probe-defaults gives every container without probes liveness, readiness and startup probes. The probes are HTTP GET probes on the first container port, so change them to tcpSocket or exec probes for a database or another workload that does not serve HTTP. set-container-resources sets specific requests and limits.
  • Security context. set-pod-container-security-context-defaults runs pods as a non-root user with the default seccomp profile, and containers with a read-only root filesystem, no privilege escalation and no privileges. With a read-only root filesystem, every path a container writes to needs a volume: set-container-volume-mount-path <container> <volume> <path> --volume-source=emptyDir adds one. set-pod-security-defaults labels Namespaces to enforce the baseline Pod Security Standard and warn on restricted. A DaemonSet that needs access to the host keeps these defaults and overrides only the hostPath, hostPort or hostNetwork fields it needs, and guard them so that the reason is recorded.
  • Service account tokens. set-automount-service-account-token-false sets automountServiceAccountToken: false on pod specs. Set it to true only on the pods that call the Kubernetes API.
  • Ingress. Always set ingressClassName, and terminate TLS for anything reachable in production. The community ingress-nginx controller has been retired, so for new configuration prefer the Gateway API or a maintained controller.
  • NetworkPolicy. Start from a default-deny policy for the namespace and add explicit allows, including egress to DNS on port 53 over both UDP and TCP, which almost every workload needs.
  • RBAC. Grant the verbs a workload uses rather than *, prefer a Role to a ClusterRole, and name Secrets in resourceNames rather than granting access to every Secret in the namespace.
  • Jobs and CronJobs. Set restartPolicy to Never or OnFailure, a backoffLimit, and an activeDeadlineSeconds, and give a CronJob a concurrencyPolicy.
  • Autoscaling and disruption. Give an HPA a scaleDown.stabilizationWindowSeconds so it does not scale down on every dip, and omit spec.replicas from the workload it scales. Give a PodDisruptionBudget either minAvailable or maxUnavailable, not both; maxUnavailable: 1 works for most workloads.
  • StatefulSets. Use volumeClaimTemplates for per-replica storage. Give a standalone PersistentVolumeClaim its own Unit only when its data should outlive the workload.
  • CRDs. Put a CustomResourceDefinition in a Unit of its own, separate from the resources that use it, as with any resource; see Units.

Bringing in existing resources

To bring resources that are already running in a cluster under ConfigHub management, export them with kubectl and create Units from the result. For a whole namespace:

kubectl get all,configmap,secret -n my-namespace -o yaml \
  | cub unit create --space my-space my-namespace-unit -

Strip cluster-assigned fields (status, metadata.uid, metadata.resourceVersion, metadata.creationTimestamp) before or after import — cub function set can do the cleanup once the Unit exists.

Helm

You could use helm template, but the cub helm install command (from the cub-helm plugin) renders a chart and installs it as a component in one step. See the Helm Guide.

Kubectl

We wrote a little kube-gen script to make it a little easier to use kubectl create commands to generate basic Kubernetes resources. It essentially does:

kubectl create "${resource_type}" -o yaml --dry-run=client "${@}" ${namespace}

Pronounced "kube control" ;-).

Kustomize

The base resources could be uploaded into units directly, then cloned in order to create a similar variant hierarchy in ConfigHub. Functions could replace the use of patches a number of cases. Do not include the kustomization.yaml file, which is not relevant to ConfigHub is frequently isn't fully valid KRM.

Or, similar to Helm, kustomize build could be used to render the resources prior to uploading. A kustomization that inflates Helm charts with helmCharts renders the chart's resources along with its own, so bring the chart in one way: either render the whole kustomization and upload it, or install the chart with cub helm install and render the kustomization without it. Doing both gives you two Units for each of the chart's resources.

Kompose

Use kompose convert to render your compose file as Kubernetes YAML.

Cdk8s

Render your cdk8s App and upload the YAML file(s) from the dist directory.

Specialized generation tools

The use of more specialized configuration generation tools is encouraged as well.

For instance, there are a number of RBAC generation tools, such as https://github.com/alcideio/rbac-tool.

https://k8syaml.com/ can generate Kubernetes workload resources.