syngit is a Kubernetes operator that allows you to push resources on a git repository and manage their lifecycle. It leverage the gitops by unifying the source of truth between your cluster and your git repository. It acts as a proxy between your client tool (kubectl, oc or any UI) and the cluster.
Sounds cool, isn't it?
What is the difference with the other Gitops CD tools such as Flux or ArgoCD?
The main approach of these tools is to pull changes from the remote git repository to apply them on the cluster. syngit does the opposite : it pushes the changes that you want to make on the cluster to the remote git repository.
Why do I need syngit?
There is plenty of reasons to use this operator. It is not really user-friendly to make all modifications only through the git repository. Applying manifests will return an instant result of the cluster state.
Basically, if you like to use Kubernetes with cli or through an UI BUT you want to work in GitOps, then syngit is the operator that you need.
Can I use it to keep history of my objects?
Another useful usage is the object logging. Automatic etcd snapshot can be setted on the cluster but it will log the changes of the whole cluster. As a DevOps user (that only deploy application without managing the cluster), I want to keep an history of my objects through commits on a git repository.
- docker version 17.03+.
- kubectl version v1.11.3+.
- helm version v3.0.0+.
- certmanager version 1.13+ on the cluster.
- Access to a Kubernetes v1.11.3+ cluster.
For now, you can only install syngit using Helm. More information about the configuration can be found wiki.
- Add this github repository to your helm repos.
helm repo add syngit https://syngit-org.github.io/syngit- Install the operator You can customize the values before installing the Helm chart.
helm install syngit syngit/syngit --version 0.1.0 -n syngit --create-namespacesyngit is now installed on your cluster!
There is 3 custom objects that are necessary to create in order to use syngit. More information about the usage can be found in the wiki. The detailled descricription of each object can be found here.
The RemoteUser object make the connexion to the remote git server using an user account. In order to use this object, you first need to create a secret that reference a Personal Access Token (and not an Access Token).
apiVersion: v1
kind: Secret
metadata:
name: git-server-my_git_username-auth
type: kubernetes.io/basic-auth
stringData:
username: <MY_GIT_USERNAME>
password: <PERSONAL_ACCESS_TOKEN>apiVersion: syngit.syngit.io/v1beta1
kind: RemoteUser
metadata:
name: remoteuser-sample
spec:
gitBaseDomainFQDN: "github.com"
email: [email protected]
associatedRemoteUserBinding: true
secretRef:
name: git-server-my_git_username-authNow, if you look at the status of the object, the secret should be correctly bound.
kubectl get remoteuser remoteuser-sample -o=jsonpath='{.status.secretBoundStatus}'The RemoteUserBinding bind the Kubernetes user with the remote git user. This is used by syngit when the user apply changes on the cluster. syngit will push on the git server with the associated git user.
By default, the associatedRemoteUserBinding field of the RemoteUser object automatically creates a RemoteUserBinding. The name of the object is associated-rub-<kubernetes_user_id>.
To get the associated RemoteUserBinding object, run :
kubectl get remoteuserbinding associated-rub-$(kubectl auth whoami -o=jsonpath='{.status.userInfo.username}')The RemoteSyncer object contains the whole logic part of the operator.
In this example, the RemoteSyncer will intercept all the configmaps. It will push them to https://github.com/my_repo_path.git in the branch main under the path my_configmaps/. Because the commitProcess is set to CommitApply, the changes will be pushed and then applied to the cluster. CommitOnly will only push the resource on the git server without applying it on the cluster.
apiVersion: syngit.syngit.io/v1beta1
kind: RemoteSyncer
metadata:
name: remotesyncer-sample
spec:
remoteRepository: https://github.com/my_repo_path.git
defaultBranch: main
processMode: CommitApply
pushMode: SameBranch
defaultUnauthorizedUserMode: Block
rootPath: "my_configmaps"
excludedFields:
- metadata.managedFields
- metadata.creationTimestamp
- metadata.annotations.[kubectl.kubernetes.io/last-applied-configuration]
- metadata.uid
- metadata.resourceVersion
scopedResources:
rules:
- apiGroups: [""]
apiVersions: ["v1"]
resources: ["configmaps"]
operations: ["CREATE", "UPDATE"]Now, let's apply this configmap :
apiVersion: v1
kind: ConfigMap
metadata:
name: test-configmap
data:
somedata: hereThe configmap has been applied on the cluster and it has been pushed on the remote git repository as well!
I use an automatic reconciliation with my CD tool, do I really need to use syngit?
Using the CommitApply mode, the automatic reconciliation will not have any effect since the changes made on the cluster are pushed on the remote git repository. It is better to let it enabled and consider syngit to be a transparent tool.
What if the connection with my git repository does not work?
As explained here, by default, the webhook logic will first try to commit & push and then apply the changes to the cluster. If, for any reason, the resource has not been pushed, the resource will not be applied. Therefore, the GitOps philosophy is not broken.
The wiki contains all the information needed!
Please refer to the Contribute page of the wiki.
Please refer to the Roadmap page of the wiki.
This operator has been built using the kubebuilder framework. The framework is under the Apache-2.0 License. The Apache-2.0 license is also used for the syngit operator and can be found in the LICENSE file.