Habitat Documentation

Butterfly is the Habitat gossip protocol used for membership management. It implements the SWIM+Inf+Susp protocol for membership and utilizes a ZeroMQ-based newscast-inspired gossip protocol.

Key characteristics include:

• Eventually consistent: Members converge on the same state over time.
• Efficient: The protocol avoids back-chatter by sending messages without requiring confirmations.
• Reliable: Designed as a safe and reliable building block for Habitat.

Chef Habitat Builder is the core of Chef's Application Delivery Enterprise hub. It serves as a repository for plan templates and application delivery content. It is available in two consumption models:

1. Cloud-based (SaaS): A cloud service where plan files are stored, viewed, and accessed by the Chef Habitat community.
2. On-premises: A solution for users who prefer to store packages and run the builder locally. Plan files from the SaaS version can be shared with and maintained by the on-premises version.

This dual-model approach supports air-gapped environments and local package maintenance.

The Habitat Launcher is a minimal sidecar process for the Supervisor. It acts as the entry point for running the Supervisor and is designed to run as process 1. Its primary responsibilities include:

• Launching the Habitat Supervisor.
• Restarting the Habitat Supervisor on shutdown (acting as the 'Supervisor for the Supervisor').
• Starting, stopping, and restarting processes on behalf of the Supervisor.

Launcher is specifically designed to enable the Supervisor to self-update without shutting down or re-parenting the services being supervised. Because it is intended to run as process 1, it is versioned separately and should be updated very infrequently.

A service group is a collection of one or more running services that share a common configuration and topology.

If you start a service without explicitly specifying a group name, Habitat assigns it to a default group based on the package name. For example:

• redis.default
• postgres.financialdb
• postgres.userdb

Chef Habitat utilizes libsodium (a Rust implementation of NaCl) for its cryptographic operations. It employs both symmetric encryption for wire encryption and asymmetric encryption for other security tasks.

• Message Encryption: When wire encryption or service group encryption is enabled, Habitat uses the Curve25519, Salsa20, and Poly1305 ciphers.
• Package Signing: Habitat packages (.hart files) are signed using BLAKE2b cryptographic hash functions.

Progress Chef maintains several official origins for specific package types:

• core: Common dependencies and compilers maintained by Progress Chef.
• chef: Chef products (e.g., Chef Infra Client, Chef InSpec, Chef Automate).
• chef-platform: Chef 360 Platform skills.
• habitat: Packages required for an on-prem Habitat Builder deployment.

In Chef Habitat, a plan is a directory of shell scripts (or PowerShell scripts on Windows) and optional configuration files that define how software is downloaded, configured, built, installed, and managed.

These plans are used to build artifacts, which are cryptographically-signed tarballs (with a .hart extension) containing the application, its dependencies, and lifecycle hooks.

Key components of a plan include:

• plan.sh (Linux) or plan.ps1 (Windows): The required entry point for the build process.
• pkg_* variables: Define metadata like name, version, origin, dependencies, and directory structures.
• Optional files: Configuration templates, runtime hooks, and service configuration files.

When Chef Habitat packages are installed, they are placed in the /hab/pkgs/ directory, organized by their fully-qualified identifiers in the format: origin/name/version/release.

During the build process, the hab-plan-build script generates several metadata files that define dependencies, environment variables, and configuration. These files are used by the Chef Habitat Supervisor during the initialization phase to ensure services have the correct runtime environment.

A service group is a logical grouping of services that share the same package and topology type, connected across a Supervisor network.

Key characteristics:

• Shared Configuration: Services within a group can share configuration and file updates.
• Segmentation: Groups can be used to segment services by workflow or deployment needs (e.g., QA, Production).
• Security: Updates can be encrypted so only members of a specific service group can decrypt them.
• Default Behavior: By default, every service joins a group named <service-name>.default unless specified otherwise at runtime.
• Network Isolation: Multiple service groups can exist within the same Supervisor network, allowing data exposed by Supervisors to be shared across the ring regardless of group membership.