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
- Validation Options
- Better error messages for status/events
