kubecfg-operator

kubecfg-operator

A fluxcd controller for managing remote manifests with kubecfg

This project is in very early stages proof-of-concept. Only latest images are published, and they are not guaranteed stable at the moment.

The ultimate goal is to finish integratating this project with the Flux GitOps Toolkit APIs, along with the existing functionality for absolute URLs.

Quickstart

API Documentation is available here.

Installing

You can use either kustomize or kubecfg to install the controller and its CRDs.

# Using kubecfg - import and extend this file for modifications
## The kubecfg assumes the `flux-system` namespace is present already.
## If it isn't, create it (or import the file and set `create_namespace: true`):
##    kubectl create ns flux-system
kubecfg update config/jsonnet/kubecfg-operator.jsonnet

# Using kustomize
cd config/manager
## This is the current value, but if you want to change the image
kustomize edit set image controller=ghcr.io/pelotech/kubecfg-controller:latest
## Deploy
kustomize build . | kubectl apply -f -

Examples

First (at the moment this is optional), define a GitRepository source for your Konfiguration:

# config/samples/kubecfg-operator-git-repository.yaml
apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
  name: kubecfg-samples
  namespace: flux-system
spec:
  interval: 30s
  ref:
    branch: main
  url: https://github.com/pelotech/kubecfg-operator

Finally, create a Konfiguration for your application:

# config/samples/whoami-source-controller-konfiguration.yaml
apiVersion: apps.kubecfg.io/v1
kind: Konfiguration
metadata:
  name: whoami
spec:
  interval: 30s
  path: config/jsonnet/whoami-tla.jsonnet
  prune: true
  variables:
    tlaStr:
      name: 'whoami'
    tlaCode:
      port: '8080'
  sourceRef:
    kind: GitRepository
    name: kubecfg-samples
    namespace: flux-system

This may change, but for now you can choose to skip the sourceRef and supply a path to a remote file over HTTP(S). The file will be checked for changes at the provided interval.

apiVersion: apps.kubecfg.io/v1
kind: Konfiguration
metadata:
  name: whoami
spec:
  interval: 30s
  path: https://raw.githubusercontent.com/pelotech/kubecfg-operator/main/config/jsonnet/whoami-tla.jsonnet
  prune: true
  variables:
    tlaStr:
      name: 'whoami'
    tlaCode:
      port: '8080'

You can watch the status of the Konfiguration with kubectl:

# Available names and shortnames are konfiguration(s), konfig(s), konf(s)
$ kubectl get konfig
NAME     READY   STATUS                                                            AGE
whoami   True    Applied revision: main/0bceb3d69b046f51565a345f3105febbd7be62bd   1m32s

$ kubectl get konfig -o wide
NAME     READY   STATUS                                                            AGE    CURRENTREVISION                                 LASTATTEMPTEDREVISION
whoami   True    Applied revision: main/0bceb3d69b046f51565a345f3105febbd7be62bd   1m38s   main/0bceb3d69b046f51565a345f3105febbd7be62bd   main/0bceb3d69b046f51565a345f3105febbd7be62bd

Development

Building

You can use the Makefile to perform any build operations:

# After code changes to the API make sure you run deep-copy code and manifest
# generation
make generate manifests

## Below steps are only if you wish to build your own image. You can also download
## from the public repository.

# Builds the docker image
make docker-build

# Builds the docker image with a custom tag
make docker-build IMG=my.repo.com/kubecfg-controller:latest

# Push the docker image (also accepts the IMG argument)
make docker-push

Local Testing

The instructions below assume you are using k3d for running a local kubernetes cluster. The instructions will work mostly the same for kind, minikube, etc. as well.

The most accurate installation manifest is the jsonnet file. You may also use the kubebuilder generated Kustomize manifests, but you will need to bind cluster-admin privileges to the manager yourself.

To use the jsonnet you will need to install kubecfg.

# Make a test cluster
k3d cluster create

# Install flux
flux install

# Import the built image into the cluster if you did not push it
# to a repository. Replace the image name with any overrides you did.
# You can skip this step if you wish to pull the image from the public
# repository.
k3d image import ghcr.io/pelotech/kubecfg-controller:latest

# Deploy the manager and CRDs to the cluster using kubecfg.
kubecfg update config/jsonnet/kubecfg-operator.jsonnet

There are also Makefile helpers to do the equivalent of all of the above:

make cluster flux-install docker-load deploy
#       |           |          |         |
#   Create Cluster  |          |         |
#              Install Flux    |         |
#                          Load Image    |
#                                 Deploy Controller and CRDs

There is a very-simple example of a Konfiguration manifest here. It uses the simple jsonnet whoami-example included in this repo. You can apply it with kubectl.

kubectl apply -f config/samples/apps_v1_konfiguration.yaml

There are also examples of using this controller with Flux's source-controller. But, like the rest of this project, this is all very PoC still. The examples use the whoami jsonnet snippets in this repository as well. See the example GitRepository and Konfiguration.

TODO

These are features and other tasks that need to be completed before an initial release will be ready.

• Unit and E2E Tests
• Metrics
• Better Handling of Cluster Scoped Resources
• Better Validation Options
• Better Patch Strategies