github.com/flanksource/konfigadm@v0.12.0/README.md (about)

     1  <p align="center">
     2  <a href="https://circleci.com/gh/flanksource/konfigadm"><img src="https://circleci.com/gh/flanksource/konfigadm.svg?style=svg"></a>
     3  <a href="https://codecov.io/gh/flanksource/konfigadm"><img src="https://codecov.io/gh/flanksource/konfigadm/branch/master/graph/badge.svg"></a>
     4  <a href="https://goreportcard.com/report/github.com/flanksource/konfigadm"><img src="https://goreportcard.com/badge/github.com/flanksource/konfigadm"></a>
     5  <img src="https://img.shields.io/badge/OS-ubuntu%20%7C%20debian%20%7C%20centos%20%7C%20redhat%20%7C%20fedora-lightgrey.svg"/></a>
     6  </p>
     7  
     8  <p align="center">
     9    <a href="#installation">Installation</a> •
    10    <a href="#installing-kubernetes">Kubernetes</a> •
    11    <a href="#features">Key Features</a> •
    12    <a href="#compatibility">Compatibility</a> •
    13    <a href="DESIGN.md">Design</a> •
    14    <a href="https://github.com/moshloop/konfigadm-images/releases">Prebuilt Images</a> •
    15    <a href="https://konfigadm.docs.flanksource.com/"> Full Documentation </a>
    16  </p>
    17  
    18  `konfigadm` is a declarative configuration management tool and image builder focused on bootstrapping nodes for container based environments.
    19  
    20  ## Usage
    21  
    22  ```
    23  Usage:
    24    konfigadm [command]
    25  
    26  Available Commands:
    27    apply       Apply the configuration to the local machine
    28    build-image Build a new image using the specified image and konfig
    29    cloud-init  Exports the configuration in cloud-init format
    30    help        Help about any command
    31    minify      Resolve all lookups and dependencies and export a single config file
    32    verify      Verify that the configuration has been applied and is in a healthy state
    33    version     Print the version of konfigadm
    34  
    35  Flags:
    36    -c, --config strings   Config files in YAML or JSON format
    37    -d, --detect           Detect tags to use
    38    -h, --help             help for konfigadm
    39    -v, --loglevel count   Increase logging level
    40    -t, --tag strings      Runtime tags to use, valid tags: debian,ubuntu,redhat,rhel,fedora,redhat-like,debian-like,centos,aws,vmware
    41    -e, --var strings      Extra Variables to in key=value format
    42  ```
    43  
    44  ## Installation
    45  
    46  
    47  ### Binary
    48  
    49  ```bash
    50  wget -O /usr/bin/konfigadm https://github.com/flanksource/konfigadm/releases/latest/download/konfigadm && chmod +x /usr/bin/konfigadm
    51  ```
    52  
    53  ## Getting Started
    54  
    55  ### Installing Kubernetes on the local machine
    56  
    57  ```bash
    58  sudo konfigadm apply -c - <<-EOF
    59  kubernetes:
    60    version: 1.21.2
    61  container_runtime:
    62    type: docker
    63  commands:
    64    - kubeadm init
    65  EOF
    66  ```
    67  
    68  [![asciicast](https://asciinema.org/a/250079.png)](https://asciinema.org/a/250079)
    69  
    70  ### Building a kubernetes image
    71  
    72  ```bash
    73  sudo konfigadm images build --image ubuntu1804 -c - <<-EOF
    74  kubernetes:
    75    version: 1.21.2
    76  container_runtime:
    77    type: docker
    78  cleanup: true
    79  EOF
    80  ```
    81  
    82  Cloud Images are downloaded and then configured with `--build-driver` 2 drivers are supported:
    83  
    84  1. `qemu` (default) - Launches the image with KVM and attaches a cloud-init ISO to configure on boot
    85  2. `libguestfs` - Uses virt-customize to launch an appliance and chroot into the disk, does not require cloud-init in the image, but also cannot test/verify systemd based services due to the chroot.
    86  
    87  [![asciicast](https://asciinema.org/a/252399.svg)](https://asciinema.org/a/252399)
    88  
    89  ## Features
    90  
    91  * **Dependency Free** and easily embeddable into an image builder.
    92  * **Declarative**, The order of operations cannot be changed, there are no implicit or explicit dependencies between items, no conditionals (besides for os/cloud tags) or control flows
    93  * **Typed**, can validate the configuration (e.g. docker image name is valid, systemd.unit file only includes valid keys, and the values are typed correctly)
    94  * Has built-in higher-order abstractions for kubernetes, containers, cri, cni, etc.
    95  * Supports multiple operating systems and package managers
    96  * Abstractions and many of the built-in elements are easily unit-testable due to the use of virtual filesystem and command execution list.
    97  * Automatic testing / verification based on intent, not just command success code
    98  * Generate cloud-init or shell scripts to be used by other systems
    99  
   100  ## Compatibility
   101  
   102  Compatibility is tested via the docker systemd images created by [jrei](https://github.com/j8r/dockerfiles/tree/master/systemd), All example fixtures are first verified as false, applied, and then verified as true.
   103  
   104  To run integration tests:
   105  
   106  ```bash
   107  make ubuntu
   108  ```
   109  
   110  ## TODO
   111  
   112  * Incremental mode
   113  * Merge duplicate command dependencies (e.g. installing curl)
   114  * Support templating everywhere (currently only supported in files)
   115  * Packer/QEMU/VirtualBox/Fusion drivers for building images
   116  * AMI/OVA Image upload
   117  * Multi-OS cleanup scripts for building images