flanksource / konfigadm

konfigadm is a declarative configuration management tool and image builder focused on bootstrapping nodes for container-based environments.

Installation • Kubernetes • Key Features • Compatibility • Design • Prebuilt Images • Full Documentation

konfigadm is a declarative configuration management tool and image builder focused on bootstrapping nodes for container based environments.

Usage

Usage:
  konfigadm [command]

Available Commands:
  apply       Apply the configuration to the local machine
  build-image Build a new image using the specified image and konfig
  cloud-init  Exports the configuration in cloud-init format
  help        Help about any command
  minify      Resolve all lookups and dependencies and export a single config file
  verify      Verify that the configuration has been applied and is in a healthy state
  version     Print the version of konfigadm

Flags:
  -c, --config strings   Config files in YAML or JSON format
  -d, --detect           Detect tags to use
  -h, --help             help for konfigadm
  -v, --loglevel count   Increase logging level
  -t, --tag strings      Runtime tags to use, valid tags: debian,ubuntu,redhat,rhel,fedora,redhat-like,debian-like,centos,aws,vmware
  -e, --var strings      Extra Variables to in key=value format

Installation

Binary

wget -O /usr/bin/konfigadm https://github.com/flanksource/konfigadm/releases/latest/download/konfigadm && chmod +x /usr/bin/konfigadm

Getting Started

Installing Kubernetes on the local machine

sudo konfigadm apply -c - <<-EOF
kubernetes:
  version: 1.21.2
container_runtime:
  type: docker
commands:
  - kubeadm init
EOF

Building a kubernetes image

sudo konfigadm images build --image ubuntu1804 -c - <<-EOF
kubernetes:
  version: 1.21.2
container_runtime:
  type: docker
cleanup: true
EOF

Cloud Images are downloaded and then configured with --build-driver 2 drivers are supported:

1. qemu (default) - Launches the image with KVM and attaches a cloud-init ISO to configure on boot
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.

Features

• Dependency Free and easily embeddable into an image builder.
• 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
• 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)
• Has built-in higher-order abstractions for kubernetes, containers, cri, cni, etc.
• Supports multiple operating systems and package managers
• Abstractions and many of the built-in elements are easily unit-testable due to the use of virtual filesystem and command execution list.
• Automatic testing / verification based on intent, not just command success code
• Generate cloud-init or shell scripts to be used by other systems

Compatibility

Compatibility is tested via the docker systemd images created by jrei, All example fixtures are first verified as false, applied, and then verified as true.

To run integration tests:

make ubuntu

TODO

• Incremental mode
• Merge duplicate command dependencies (e.g. installing curl)
• Support templating everywhere (currently only supported in files)
• Packer/QEMU/VirtualBox/Fusion drivers for building images
• AMI/OVA Image upload
• Multi-OS cleanup scripts for building images

konfigadm's Issues

Add support for managing users

Doc Updates

Add E2E test for ubuntu 20.04

Fedora configuration is failing

Specifying a containers section with no container runtime does not report any errors

executing konfigadm apply with a container segment on a machine without docker/container installed gives no indication that the container was not created

Files: Support go-getter locations

Add support for https://github.com/hashicorp/go-getter based URL's under files

files:
  /etc/motd: https://acme.corp/motd

Support go-getter based config files

https://github.com/hashicorp/go-getter
e.g. konfigadm apply -c https://raw.githubusercontent.com/flanksource/konfigadm/master/fixtures/k8s-1.15.yml

Add ansible playbooks

Dependabot can't resolve your Go dependency files

Dependabot can't resolve your Go dependency files.

As a result, Dependabot couldn't update your dependencies.

The error Dependabot encountered was:

github.com/flanksource/konfigadm/cmd: cannot find module providing package github.com/flanksource/konfigadm/cmd

If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.

View the update logs.

Apply over SSH using an ansible inventory file

.e.g

konfigadm apply config.yml --inventory /etc/ansible/inventory

Dependabot can't parse your go.mod

Dependabot couldn't parse the go.mod found at /go.mod.

The error Dependabot encountered was:

go: github.com/flanksource/[email protected] requires
	github.com/hairyhenderson/gomplate/[email protected] requires
	[email protected] requires
	github.com/Azure/[email protected] requires
	github.com/grpc-ecosystem/[email protected] requires
	gopkg.in/[email protected]: invalid version: git fetch --unshallow -f origin in /opt/go/gopath/pkg/mod/cache/vcs/748bced43cf7672b862fbc52430e98581510f4f2c34fb30c0064b7102a68ae2c: exit status 128:
	fatal: The remote end hung up unexpectedly

View the update logs.

Add golanci-lint

Files: Support deferred loading of large go-getter resources

When generating a cloud-init file some platforms have a size limitation e.g. AWS of 16KB, so support not inlining the resources, but retrieving the resources at runtime using curl, git, aws etc..

runtimeFiles:
    /opt/deploy/: https://github.com/corp/deploy.git

Set ntp/chronyd

Mention that CLA has to be signed in CONTRIBUTING.md

Mention in CONTRIBUTING.md that the CLA (Contributor License Agreement) has to be signed here - https://cla-assistant.io/flanksource/konfigadm

Concepts section in docs doesn't display image

https://www.moshloop.com/konfigadm/concepts/

Code is here https://github.com/flanksource/konfigadm/blob/master/docs/concepts.md

Add kernel option

Essentially make:

kernel: 4.15.0-66

equivalent to

packages:
  - +linux-image-4.15.0-66-generic
  - +linux-headers-4.15.0-66-generic
commands:
   # Update the default boot kernel, ignoring any new kernels that are automatically installed/updated
  - sed 's/GRUB_DEFAULT=.*/GRUB_DEFAULT="Advanced options for Ubuntu>Ubuntu, with Linux 4.15.0-66-generic"/' -i /etc/default/grub
  - update-grub

Dependabot can't resolve your Go dependency files

Dependabot can't resolve your Go dependency files.

As a result, Dependabot couldn't update your dependencies.

The error Dependabot encountered was:

github.com/flanksource/konfigadm/cmd: cannot find module providing package github.com/flanksource/konfigadm/cmd

If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.

View the update logs.

Add tagging support for fixtures

i.e. some fixtures may not be supported for some operating systems/versions

Files: add support for directories

Add support for copying an entire directory structure - Note the / in the path of the file:
Also needs to support #3

files:
    /opt/deploy/: https://github.com/corp/deploy.git

Fix mark/uninstall package prefixes

i.e. +kubeadm should install and mark kubeadm while !kubeadm should remove it if installed

Potential collision and risk from indirect dependence "github.com/gotestyourself/gotestyourself"

Background

Repo flanksource/konfigadm used the old path to import gotestyourself indirectly.
This caused that github.com/gotestyourself/gotestyourself and gotest.tools coexist in this repo：
https://github.com/flanksource/konfigadm/blob/master/go.mod （Line 14 & 28）

github.com/gotestyourself/gotestyourself v2.2.0+incompatible // indirect
gotest.tools v2.2.0+incompatible // indirect 

That’s because the gotestyourself has already renamed it’s import path from "github.com/gotestyourself/gotestyourself" to "gotest.tools". When you use the old path "github.com/gotestyourself/gotestyourself" to import the gotestyourself, will reintroduces gotestyourself through the import statements "import gotest.tools" in the go source file of gotestyourself.

https://github.com/gotestyourself/gotest.tools/blob/v2.2.0/fs/example_test.go#L8

package fs_test
import (
	…
	"gotest.tools/assert"
	"gotest.tools/assert/cmp"
	"gotest.tools/fs"
	"gotest.tools/golden"
)

"github.com/gotestyourself/gotestyourself" and "gotest.tools" are the same repos. This will work in isolation, bring about potential risks and problems.

Solution

1. Add replace statement in the go.mod file:

replace github.com/gotestyourself/gotestyourself => gotest.tools v2.3.0

Then clean the go.mod.

Verify by default

I think verifying changes by default is nice to do after applying to a "live" environment.
But it is probably a must after applying to an image, since that image is probably the beginning of a longer infrastructure deployment pipeline, and it's important to fail early.

Of course, having an escape hatch is a good idea. For that, I suggest --skip-verify=[true|false] flag.

go1.13.5 modules not working

Current go modules files fails to work with go1.13:

$ go1.13.5 list -m -json all
go: github.com/flosch/[email protected] requires
	github.com/go-check/[email protected]: invalid pseudo-version: major version without preceding tag must be v0, not v1

Discrepancies in various package installation instructions.

There appears to be inconsistency in locating different package versions. e.g version below v0.4.14 appears to have various distros package published and available via the installation url in the README.md but versions above it do not have these packages published. This creates confusion for users trying to install the package as there are discrepancies between the installation instruction and what works. Maintaining the two liner installation steps looks better.

Add e2e tests for Amazon Linux

Merge multiple pkg install calls

Add photon OS support

konfigadm apply overriding existing /etc/environment file

konfigadm apply is updating my existing /etc/environment file which is having my proxy info probably because of this

konfigadm/pkg/apps/kubernetes.go

Line 53 in c42cb57

sys.Environment["KUBECONFIG"] = "/etc/kubernetes/admin.conf"

How to reproduce:
Setup /etc/environment with some dummy variables. then give konfigadm apply --config=/tmp/konfigadm.yml. After this cat the /etc/environment and check the variable if you still have dummy variables.

Expected:
konfigadm should append to existing /etc/environment file instead of replacing

Fix import references from moshloop to flanksource

Proposal: Remove docs target from all target in Makefile

Currently

$ make

fails due to no access to push docs to the https://github.com/flanksource/konfigadm . Considering many will not have access to the repo, and also, even if they have access, they are not supposed to host the docs by pushing from local, and that's why it's part of the Circle CI job. So, considering that, we could remove the docs target from all, and if anyone wants to run docs, they can use $ make docs

Proposal: Run only test and integration in all

No binary for stable releases

Not all releases contain binary, for example latest 0.7.3 .
Please provide binary for stable releases.

fix circleci, travis-ci and codecov moshloop references

circleci and codecov, moshloop references in should be replaced by flanksource in README.md, index.md and syntax.md

"index.md" replacements required at the below locations:

• Ln 1 [![CircleCI](https://circleci.com/gh/moshloop/konfigadm.svg?style=svg)](https://circleci.com/gh/moshloop/konfigadm)
• Ln 2 [![codecov](https://codecov.io/gh/moshloop/konfigadm/branch/master/graph/badge.svg)](https://codecov.io/gh/moshloop/konfigadm)

"syntax.md" replacements required at the below locations:

• Ln 1 [![Build Status](https://travis-ci.org/moshloop/konfigadm.svg?branch=master)](https://travis-ci.org/moshloop/konfigadm)
• Ln 2 [![codecov](https://codecov.io/gh/moshloop/konfigadm/branch/master/graph/badge.svg)](https://codecov.io/gh/moshloop/konfigadm)

README.md replacements required at the below locations:

• Ln 2 <a href="https://circleci.com/gh/moshloop/konfigadm"><img src="https://circleci.com/gh/moshloop/konfigadm.svg?style=svg"></a>
• Ln 3 <a href="https://codecov.io/gh/moshloop/konfigadm"><img src="https://codecov.io/gh/moshloop/konfigadm/branch/master/graph/badge.svg"></a>

Use `command` instead of `which` to identify if binary is available

Instead of which we could use command to identify if binary is available or not, please see: here

Originally posted by @Kaitou786 in #100 (comment)

Set timezone

QEMU/KVM + Cloud Init based image builder

libguestfs chroots into the filesystem so verification is not possible for many configs

Trusted CA's

Add a mechanism to add trusted CA's to:

trustedCA:
   - /path/root/ca.pem
   - http://path/to/root/ca/pem
   - | 
       -----BEGIN CERTIFICATE-----
           ...
       -----END CERTIFICATE-----

• System
• Java
• Pip
• Docker

Resources:

https://github.com/moshloop/systools/blob/master/bin/install_certs

Kubernetes fixture requires manual modprobe call

Add cleanup config item

e.g. purge caches and system identity

Flatcar ignition output format

[debian] Add support for installing deb archives from http://

Add container_runtime.type: containerd support

Integrate flanksource/yaml

Add container_runtime.type: cri-o support

Add support for OS major version tags

e.g.

• ubuntu18
• ubuntu20
• centos7
• centos8

Documentation Error

The installation instruction appears to be missing .deb package. Package Not Found. This is a path issue pointing to moshloop for the requested repository which seemed to have moved to flanksource user.

Incorrect container runtime chosen in container exec setup

Specified

container_runtime:
type: containerd

in the config, but ended up with a service that called the docker bin at startup

replace "moshloop.com" reference in README

Add "Full Documentation" content to flanksource.com and update README href

Ln 15 In the README.md is currently <a href="https://www.moshloop.com/konfigadm"> Full Documentation </a>

containerd - Install nerdctl and alias to docker

pre_commands are ran twice

pre_commands:
  - "echo 'hello cloud-init'"
  - 'echo "#Disable root login" >> /etc/ssh/sshd_config'
  - 'echo "PermitRootLogin no" >> /etc/ssh/sshd_config'
  - 'service ssh restart'

$ cat /etc/ssh/sshd_config
...
#Disable root login
PermitRootLogin no
#Disable root login
PermitRootLogin no