Basic Kubchi concepts

You do not need to know every Kubernetes detail to work with ready-to-install Packs. The concepts on this page are enough to read Pack status, find configuration, and investigate common problems.

Kubernetes manages containerized applications across a group of machines. Those machines and the components that control them form a cluster.

A Kubernetes cluster has a control plane and one or more nodes. The control plane checks resource state, while nodes run the application's pods and containers.

A Kubit project must be connected to a cluster before Kubchi can show its Packs and resources.

A node is a physical or virtual machine in the cluster. Kubernetes places pods on suitable nodes according to their requested resources and scheduling constraints.

A workload is a resource that manages running pods. Common workload types include Deployment, StatefulSet, DaemonSet, Job, and CronJob.

The Workloads page shows ready replicas, related pods, and the current state of each Pack workload.

A pod is the smallest deployable unit in Kubernetes. It contains one or more containers that share a network and some storage resources.

Pods are usually temporary. If a pod is removed or becomes unhealthy, its workload controller can create a replacement. Changes made directly inside a container therefore usually disappear when the pod is replaced.

A container runs an application process with the files and dependencies it needs. A pod can have more than one container, so the Logs and Terminal pages require you to select a container after choosing a workload or pod.

A pod address may change when Kubernetes replaces it. A Service provides a stable address for a group of pods. A NetworkPolicy can limit allowed traffic between pods or namespaces.

Each Kubernetes resource, such as a Deployment or Service, defines a desired part of the system. Controllers compare the actual state with that definition and correct differences.

This explains why deleting a pod or workload directly may not have a lasting effect. As long as its definition remains in the Pack or chart, a controller can create it again.

A namespace groups resources within a cluster. Names for resources such as Service and Deployment must be unique inside their namespace, but the same name can exist in another namespace. Cluster-scoped resources such as Node and StorageClass do not belong to a namespace.

Each Pack is installed in one namespace. Kubchi can manage it after that namespace is connected to the project. See Manage namespaces for the setup steps.

Infrastructure as code stores resource definitions and settings in files. Git can version, review, and restore those files.

Kubchi supports this workflow through GitOps. GitOps is optional; installing a ready-to-use Pack from the panel does not require a Git repository.

A manifest is the text definition of a Kubernetes resource and is usually written in YAML. Most manifests have apiVersion, kind, metadata, and spec. The spec describes the desired state, and a controller usually writes the result to status.

During a normal ready-to-use Pack installation, Kubchi builds the Pack manifest from the form. Direct YAML editing is useful when the chart has no form or the form does not expose the setting you need. See Pack configuration for that workflow.

A ConfigMap stores non-sensitive settings. The chart must define which values become a ConfigMap and how containers receive them as files or environment variables.

Do not store passwords, tokens, or private keys in a ConfigMap. Encrypt sensitive data with Vault, or use a Secret input defined by the chart.

A Secret is a Kubernetes resource for data that should not be stored with ordinary configuration, such as registry credentials or sensitive application variables. The chart defines how the Secret is consumed as a value, file, or environment variable.

Storing a value in a Secret does not by itself provide end-to-end encryption or hide it from every authorized user. To keep sensitive text out of the Pack manifest, encrypt it with Vault first.

Helm is a package manager for Kubernetes. A Helm chart packages resource templates, default values, and the information needed to install an application in a versioned form.

When a chart provides a form, Kubchi displays it during installation and passes the submitted values to the chart. Helm renders the templates, and Kubernetes resources are then created. You can inspect the rendered output under Configuration > Helm Template.

See Helm and Helm charts for the full explanation of repositories, charts, values, and Helm releases.

A custom resource is a resource type added to the Kubernetes API through a CustomResourceDefinition, or CRD. After the CRD is registered, its resources can be created and read like built-in Kubernetes resources.

An operator is a controller for custom resources. It reads the desired state from the resource, creates or changes the required resources, and records the result in the custom resource status.

A Pack is a custom resource that defines an installation of a Helm chart. It contains the repository and chart names, version, variables, and installation values. Most users manage Packs through the Kubchi panel. The YAML manifest, GitOps, and kubit-cli are available for more technical workflows.

See the Pack reference for its manifest structure and lifecycle.

Pack Operator validates a Pack manifest and keeps the Helm release in sync with it. Installation, upgrade, and error state are recorded on the Pack resource. The Pack Operator guide explains reconciliation and automatic upgrades.

An Ingress routes HTTP and HTTPS traffic from outside the cluster to a Service. It may contain several hostnames and paths and can reference a certificate Secret for TLS.

An Ingress alone is not enough. The cluster needs an active Ingress Controller, and the domain's DNS must point to the cluster entry path. See Add domains and manage TLS certificates for domain and certificate setup.

An Event is a short message about resource state or an operation, such as pod scheduling, image pulling, or disk attachment. Kubernetes events have two types:

Events differ from application logs. Kubernetes components write events, while the application or container writes logs. Use Pack events and container logs to inspect both.

A metric is a numeric value recorded at a point in time, such as CPU, memory, or disk usage. The Monitoring page reads project and Pack resource usage from the cluster metrics system. This resource usage does not depend on the application chart defining a ServiceMonitor.

An application can publish its own metrics from an endpoint such as /metrics. In Prometheus-based systems, a ServiceMonitor defines how those metrics are collected, and a PrometheusRule defines alert conditions.

The Alerts page shows active alerts that the alerting system associates with the project or Pack. You cannot create or edit alert rules from that page.

An environment variable is a named value that a program reads while running. In a container manifest, env defines variables individually, while envFrom imports every key from a ConfigMap or Secret.

env:
  - name: PORT
    value: '8080'

envFrom:
  - configMapRef:
      name: my-config

The chart must define these inputs in its templates. Creating a variable or group in Kubchi does not add anything to a container by itself. See Manage environment variables for using project values and an environment group's Secret.

Kubernetes reads memory quantities in bytes and supports two suffix groups:

• Decimal suffixes: k, M, G, T, P, and E, for example 400M.
• Binary suffixes: Ki, Mi, Gi, Ti, Pi, and Ei, for example 400Mi.