> ## Documentation Index
> Fetch the complete documentation index at: https://timoni.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# GitOps Guide

> Build a GitOps delivery pipeline for module instances with Timoni and Flux.

This guide shows you how Timoni can be used together with
[Flux](https://fluxcd.io) to create a GitOps delivery pipeline
for module instances.

```mermaid theme={"system"}
flowchart LR

A((User)) --> Y
Y(Module Values) --> B((Timoni))
B --> D[Container Registry]
D --> E((Flux CD))
E --> F[Kubernetes]
```

<Warning>
  **Timoni Controller**

  Note that currently Timoni can be used with Flux as a templating engine for Kubernetes manifests.
  Features like app lifecycle management, bundling, runtime values injection and multi-cluster
  deployments are not available when using Timoni as a templating engine. For Timoni to fully embrace GitOps,
  a Kubernetes controller will be implemented when Timoni's CUE APIs reach a more stable form.
</Warning>

## Build and Push workflow

We'll build a module instance with Timoni, and we'll push
the resulting Kubernetes manifests to a container registry with Flux CLI.

```shell theme={"system"}
timoni -n apps build podinfo oci://ghcr.io/stefanprodan/modules/podinfo \
  --values ./staging-values.cue | \
flux push artifact oci://registry.internal/podinfo:staging \
  --source="http://github.com/stefanprodan/podinfo" \
  --revision="6.14.1" \
  --path=-
```

You can also use a Timoni bundle to generate the Kubernetes manifests:

```shell theme={"system"}
timoni bundle build -f podinfo.cue | \
flux push artifact oci://registry.internal/podinfo:staging \
  --source="http://github.com/stefanprodan/podinfo" \
  --revision="6.14.1" \
  --path=-
```

The above commands could be run in CI for the Git repository
that contains the values files. Committing a change to the values, will
result in a new artifact pushed to the registry. From there, Flux running
in Kubernetes, will pick up the latest changes and deploy them on the cluster.

## Continuous Delivery workflow

In the Git repository where Flux was bootstrapped, we'll configure the reconciliation
of the Kubernetes resources pushed to the container registry.

<Info>
  **Flux sync module**

  You can generate the configuration for Flux to reconcile the OCI artifacts
  using the [flux-oci-sync module](/flux-aio#flux-oci-sync-configuration).
</Info>

```yaml theme={"system"}
---
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 1m
  url: oci://registry.internal/podinfo
  ref:
    tag: staging
---
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: podinfo
  namespace: flux-system
spec:
  targetNamespace: apps
  interval: 1h
  retryInterval: 30s
  timeout: 5m
  path: ./
  prune: true
  wait: true
  sourceRef:
    kind: OCIRepository
    name: podinfo
```

Based on the above configuration, Flux will look for changes in the container registry every minute.
When it finds a new digest of the OCI artifact, Flux will automatically reconcile the changes on the cluster.

To find out more about Flux OCI support please see the [Flux OCI docs](https://fluxcd.io/flux/cheatsheets/oci-artifacts/).